OpenCode 技术文档

一、项目概览

1.1 项目定位

OpenCode 是一款开源的 AI 编程助手，定位为 Claude Code 的开源替代品。它专为开发者设计，提供自主代码生成、修改和项目管理能力，同时避免供应商锁定。

1.2 核心价值

• 供应商无关：支持 Claude、OpenAI、Google、Azure、AWS Bedrock 以及本地模型（Ollama、LM Studio）
• 完全透明：MIT 协议开源，代码可审计，无隐藏遥测
• 原生 LSP 支持：开箱即用的语言服务器协议集成，提供代码定义、引用、悬停信息
• Client/Server 架构：支持远程操作，可在服务器运行 OpenCode 并从本地连接
• 高度可定制：自定义命令、工具、技能、Agent、主题

1.3 社区数据

1.4 技术栈

核心依赖：Bun（包管理器）、Turbo（Monorepo）、Nix（配置）、SST（基础设施）

二、快速开始

2.1 系统要求

2.2 安装方式

# 官方一键安装脚本（推荐）
curl -fsSL https://opencode.ai/install | bash

# 使用 npm
npm install -g opencode-ai@latest

# 使用 Bun
bun install -g opencode-ai@latest

# 使用 pnpm
pnpm add -g opencode-ai@latest

# macOS / Linux
brew install opencode

# 安装桌面应用（Beta）
brew install --cask opencode-desktop

# Windows - Scoop
scoop bucket add extras
scoop install extras/opencode

# Windows - Chocolatey
choco install opencode

# Arch Linux
paru -S opencode-bin

# Nix
nix run nixpkgs#opencode

# Mise
mise use -g github:sst/opencode

2.3 首次运行

cd your-project
opencode

三、核心概念

3.1 Agent 体系

OpenCode 采用双 Agent 架构，通过 Tab 键在不同模式间切换：

Subagent（子代理）

• General：通过 @general 调用，处理复杂的多步骤搜索和研究任务
• Explore：专门用于代码库探索和结构分析

3.2 Provider 支持

OpenCode 通过 AI SDK 和 Models.dev 支持 75+ LLM 提供商：

3.3 配置层级

配置按以下优先级覆盖（后者覆盖前者）：

1. 全局配置：~/.config/opencode/
2. 项目配置：.opencode/（项目根目录）
3. 工作目录配置：.opencode/（当前工作目录）

3.4 主题系统

内置 10+ 预设主题，支持自定义：

// opencode.json
{
  "theme": "tokyonight"
}

四、配置详解

4.1 配置文件结构

主配置文件为 opencode.json，可放置于全局或项目目录：

{
  // 主题设置
  "theme": "tokyonight",

  // Provider 配置
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.anthropic.com/v1"
      }
    }
  },

  // 权限控制
  "permission": {
    "edit": "ask",
    "bash": "ask"
  },

  // 工具配置
  "tools": {
    "lsp": true,
    "webfetch": true
  }
}

4.2 Provider 配置

认证方式

API 密钥存储于 ~/.local/share/opencode/auth.json，通过 /connect 命令配置

自定义 Provider 示例

{
  "provider": {
    "my-provider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Custom Provider",
      "options": {
        "baseURL": "https://api.myprovider.com/v1",
        "apiKey": "{env:MY_API_KEY}"
      },
      "models": {
        "my-model": {
          "name": "My Model"
        }
      }
    }
  }
}

4.3 权限系统

OpenCode 提供细粒度的权限控制，每个工具支持三种权限级别：

Bash 命令粒度控制

{
  "permission": {
    "bash": {
      "git *": "allow",
      "npm test": "allow",
      "rm *": "ask",
      "terraform *": "deny"
    }
  }
}

特殊权限项

• doom_loop：防止无限循环，当相同工具调用连续重复 3+ 次时触发确认
• external_directory：保护工作目录外的文件修改

五、内置工具

OpenCode 提供 13 个内置工具，LLM 可调用这些工具与代码库交互：

工具配置

可在 opencode.json 中全局或按 Agent 配置工具启用状态：

{
  "tools": {
    "lsp": true,
    "webfetch": false,
    "mymcp_*": false  // 通配符批量控制
  }
}

六、Agent 系统

6.1 Agent 配置选项

6.2 创建自定义 Agent

方式一：JSON 配置

{
  "agent": {
    "reviewer": {
      "description": "Code review specialist",
      "mode": "subagent",
      "model": "anthropic/claude-3-opus",
      "temperature": 0.2,
      "tools": {
        "edit": false,
        "write": false
      }
    }
  }
}

方式二：Markdown 文件（~/.config/opencode/agent/reviewer.md）

6.3 Temperature 指南

• 0.0 - 0.2：分析任务，需要精确和一致性
• 0.3 - 0.5：常规开发，平衡创造性和准确性
• 0.6 - 1.0：头脑风暴，需要多样化输出

七、自定义扩展

7.1 自定义命令

创建方式：在 .opencode/command/ 目录下添加 Markdown 文件，或在 opencode.json 中定义

// opencode.json
{
  "command": {
    "test": {
      "template": "Run all tests for $ARGUMENTS and report failures",
      "description": "Run tests for specified module"
    }
  }
}

命令特性

• 参数替换：$ARGUMENTS、$1、$2 等
• Shell 输出注入：!`command` 语法
• 文件引用：@filename 表示法
• 可覆盖内置命令

7.2 自定义工具

使用 TypeScript/JavaScript 定义自定义工具：

// .opencode/tool/database.ts
import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Execute database queries",
  args: {
    query: tool.schema.string().describe("SQL query to execute")
  },
  async execute(args) {
    // 实现逻辑
    return { result: "Query executed" }
  }
})

7.3 Skills（技能）

Skills 是可复用的指令集，存放于 .opencode/skill/<name>/SKILL.md

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
---

## Instructions
When creating a release:
1. Update CHANGELOG.md
2. Bump version in package.json
3. Create git tag
...

命名规则

• 1-64 字符
• 仅小写字母、数字、连字符
• 不能以连字符开头或结尾
• 目录名必须与 name 字段匹配

八、完整实战教程

本教程将引导你从零开始，完成 OpenCode 的完整工作流程。

curl -fsSL https://opencode.ai/install | bash

# 启动 OpenCode
cd your-project
opencode

# 在 TUI 中执行
/connect

/init

分析当前项目结构，规划添加 JWT 用户认证功能的实现方案
需要包括：用户模型、注册/登录接口、中间件

按照上述计划，实现用户认证功能

@src/routes/auth.js 添加密码重置端点

# 撤销上一次修改
/undo

# 重做被撤销的修改
/redo

---
description: Run authentication tests
---
Run all tests in src/__tests__/auth/ and report failures with suggestions

/theme catppuccin

/share

九、最佳实践

9.1 工作流程建议

• 先 Plan 后 Build：复杂任务先用 Plan Agent 分析，确认方案后再切换到 Build
• 精确引用：使用 @filepath 明确指定目标文件，减少误操作
• 分步执行：大型重构分解为小步骤，每步验证后再继续
• 善用 /undo：出错时立即撤销，避免错误累积

9.2 性能优化

• 合理配置 maxSteps 限制迭代次数
• 对大型代码库，使用 glob 和 grep 工具而非全量读取
• 启用 LSP 获得更精确的代码智能，减少不必要的搜索

9.3 安全注意事项

• 生产环境 API Key 使用环境变量，不硬编码
• 敏感命令（如 rm、数据库操作）设置为 ask 权限
• 启用 external_directory 保护，防止修改工作目录外文件
• 定期审计 .opencode/ 中的自定义工具代码

9.4 故障排除

十、资源与参考

10.1 官方资源

• 官网：opencode.ai
• 文档：opencode.ai/docs
• GitHub：github.com/sst/opencode
• NPM：npmjs.com/package/opencode-ai

10.2 社区渠道

• Discord：opencode.ai/discord
• Twitter/X：@opencode
• GitHub Discussions：项目 Issues 和 Discussions 板块

10.3 相关项目对比

10.4 贡献指南

如需贡献代码，请参阅：

• CONTRIBUTING.md
• STYLE_GUIDE.md