opencode 官方文档学习（1）：基础用法

之前已经学习过 claude code 的官方文档，之所以花了点时间学习一遍，主要还是想用 claude-agent-sdk 来搭建自己的 Agent。而 claude-agent-sdk 本质上就是对 claude 命令行程序的包装，所以学习一遍 claude code 文档还是有必要的。但简单实践下来，发现 claude-agent-sdk 并不是很灵活。所以打算换个框架，仔细看一下 opencode 的官方文档，尤其 opencode 现在也是我的主力 AI 编程工具。相比于 claude code，opencode 使用起来有种 大开大合 的体感。

多说一下放弃 claude code 作为 Agent 框架的原因：claude code 不是很开放。一个典型的问题是，只能通过 ANTHROPIC_BASE_URL 这一个地方来配置模型 provider 的地址，如果想要实现不同的 subagent 使用不同 provider 的模型，claude-agent-sdk 本身无法做到（AgentDefinition 只支持设置 model 字段，无法设置 provider 字段），而且 claude code 由于不开源，导致很多问题无法得到肯定答案（尤其涉及配置生效顺序相关逻辑时）。虽然如此，claude code 作为目前的明星 Agent，其官方文档的很多知识与最佳实践，还是非常值得学习的。

opencode 简介

OpenCode 是一个开源的 AI 编码代理。它提供终端界面、桌面应用和 IDE 扩展等多种使用方式。要在终端中使用 OpenCode，你需要一款现代终端模拟器，例如 Ghostty（把我用了很久的 iterm2 换了）。

安装

直接通过 curl -fsSL https://opencode.ai/install | bash 就可以安装 opencode。

安装成功后，通过 ~/.config/opencode/opencode.json 可以配置 opencode，主要是配置所使用的模型 provider，尤其现在大家都使用一些模型厂商的 coding plan，例如配置使用火山的 coding plan。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "volcengine": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "volcengine",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/coding/v3",
        "apiKey": "<ARK_API_KEY>"
      },
      "models": {
        "kimi-k2.5": {
          "name": "kimi-k2.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "options": {
            "thinking": {
              "type": "enabled"
            }
          }
        }
      }
    }
  }
}

配置完成后，直接输入 opencode 就可以启动 opencode 了。输入 /models 命令可以从配置的 provider 中选择所要使用的模型。

想要更新升级 opencode，可以执行：

opencode upgrade

一般工作流

晚上上述配置后，就可以进行开始编程工作了：

• 进入到你想要处理的项目目录

cd /path/to/project

• 然后运行 OpenCode

opencode

• 接下来，运行以下命令为项目初始化 OpenCode。 OpenCode 会分析你的项目并在项目根目录创建一个 AGENTS.md 文件。你应该将项目的 AGENTS.md 文件提交到 Git。这有助于 OpenCode 理解项目结构和编码规范

/init

• 之后就可以尽情提问，让 opencode 来处理具体的编程工作了
  • OpenCode 有一个计划模式，该模式下它不会进行任何修改，而是建议如何实现该功能
  • 对于比较简单的修改，你可以直接让 OpenCode 实施，无需先审查计划
  • 使用 @ 键可以模糊搜索项目中的文件
  • OpenCode 有一个计划模式，该模式下它不会进行任何修改，而是建议如何实现该功能。使用 Tab 键切换到计划模式
  • OpenCode 可以扫描你提供的图片并将其添加到提示词中。只需将图片拖放到终端窗口即可（通过 ssh 连接到远程服务器上的 opencode，这种图片拖曳方式似乎不太行）
  • 但你发现结果不是你想要的。你可以使用 /undo 命令来撤销修改。OpenCode 会还原所做的修改，并重新显示你之前的消息
  • 你可以多次运行 /undo 来撤销多次修改。
  • 你也可以使用 /redo 命令来重做修改

配置

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）格式。可以将配置放置在不同的位置，它们具有不同的优先级顺序。配置文件是合并在一起的，而不是被替换。来自以下配置位置的设置会被合并。后面的配置仅在键冲突时覆盖前面的配置。所有配置中的非冲突设置都会被保留。

优先级顺序

配置源按以下顺序加载（后面的源覆盖前面的源）：

• 远程配置（来自 .well-known/opencode）- 组织默认值
• 全局配置（~/.config/opencode/opencode.json）- 用户偏好
• 自定义配置（OPENCODE_CONFIG 环境变量）- 自定义覆盖
• 项目配置（项目中的 opencode.json）- 项目特定设置
• .opencode 目录 - 代理、命令、插件
• 内联配置（OPENCODE_CONFIG_CONTENT 环境变量）- 运行时覆盖

这意味着项目配置可以覆盖全局默认值，全局配置可以覆盖远程组织默认值。

远程

组织可以通过 .well-known/opencode 端点提供默认配置。当您使用支持该功能的提供商进行身份验证时，会自动获取此配置。远程配置最先加载，作为基础层。所有其他配置源（全局、项目）都可以覆盖这些默认值。

全局

将全局 OpenCode 配置放在 ~/.config/opencode/opencode.json 中。使用全局配置来设置用户级别的偏好，例如主题、提供商或快捷键。全局配置覆盖远程组织默认值。

项目级

在项目根目录中添加 opencode.json。项目配置在标准配置文件中具有最高优先级——它会覆盖全局配置和远程配置。

自定义路径

使用 OPENCODE_CONFIG 环境变量指定自定义配置文件路径。

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

自定义配置在优先级顺序中位于全局配置和项目配置之间加载。

自定义目录

使用 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。该目录会像标准 .opencode 目录一样被搜索代理、命令、模式和插件，并且应遵循相同的结构。

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

自定义目录在 全局配置 和 .opencode 目录之后加载，因此可以覆盖它们的设置。

注意，.opencode 和 ~/.config/opencode 目录的子目录使用复数名称：agents/、commands/、modes/、plugins/、skills/、tools/ 和 themes/。为了向后兼容，也支持单数名称（例如 agent/）。

Schema

配置文件具有在 opencode.ai/config.json 中定义的 Schema。编辑器应该能够基于该 Schema 进行验证和自动补全。

{
  "$schema": "https://opencode.ai/config.json",
}

具体的配置格式参加这里。一些需要注意的事项：

• 可以通过 provider、model 和 small_model 选项在 OpenCode 配置中设置要使用的提供商和模型。
• 默认情况下，OpenCode 允许所有操作，无需明确批准。您可以使用 permission 选项更改此行为
• 可以通过 mcp 选项配置要使用的 MCP 服务器
• 可以通过 agent 选项为特定任务配置专用代理，还可以使用 ~/.config/opencode/agents/ 或 .opencode/agents/ 中的 Markdown 文件定义代理。
• 可以通过 command 选项为重复任务配置自定义命令。还可以使用 ~/.config/opencode/commands/ 或 .opencode/commands/ 中的 Markdown 文件定义命令
• 插件通过自定义工具、钩子和集成来扩展 OpenCode。将插件文件放置在 .opencode/plugins/ 或 ~/.config/opencode/plugins/ 中
• 可以通过 instructions 选项为所使用的模型配置指令。
• experimental 键包含正在积极开发中的选项
• 可以在配置文件中使用变量替换来引用环境变量和文件内容。
  • 使用 {env:VARIABLE_NAME} 来替换环境变量。如果环境变量未设置，它将被替换为空字符串
  • 使用 {file:path/to/file} 来替换文件内容。文件路径可以是相对于配置文件所在目录的路径，或者是绝对路径

提供商

在 OpenCode 中使用任意 LLM 提供商。OpenCode 使用 AI SDK 和 Models.dev，支持 75+ LLM 提供商，同时也支持运行本地模型。要添加提供商，你需要：

• 使用 /connect 命令添加提供商的 API 密钥。使用 /connect 命令添加提供商的 API 密钥后，凭据会存储在 ~/.local/share/opencode/auth.json
• 可以通过 OpenCode 配置中的 provider 部分来自定义提供商
  • 通过设置 baseURL 选项来自定义任何提供商的 Base URL。这在使用代理服务或自定义端点时非常有用
• OpenCode Zen 是由 OpenCode 团队提供的模型列表，这些模型已经过测试和验证，能够与 OpenCode 良好配合使用
  • 登录 opencode.ai/auth，添加账单信息，然后复制你的 API 密钥
  • 在 TUI 中执行 /connect 命令，选择 opencode
  • 粘贴你的 API 密钥
• 当然还可以通过 /connect命令添加 OpenAI、DeepSeek、OpenRouter 等 LLM 服务提供商，还可以设置 Ollama 使用本地模型

自定义提供商

要添加 /connect 命令中未列出的任何 OpenAI 兼容提供商（你可以在 OpenCode 中使用任何 OpenAI 兼容的提供商。大多数现代 AI 提供商都提供 OpenAI 兼容的 AP）：

• 执行 /connect 命令，向下滚动到 Other
• 输入该提供商的唯一 ID
• 在项目目录中创建或更新 opencode.json 文件

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI ProviderDisplay Name",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model-name": {
          "name": "My Model Display Name"
        }
      }
    }
  }
}

以下是配置选项说明：

• npm：要使用的 AI SDK 包，对于 OpenAI 兼容的提供商使用 @ai-sdk/openai-compatible
• name：在 UI 中显示的名称。
• models：可用模型。
• options.baseURL：API 端点 URL。
• options.apiKey：可选，如果不使用 auth 认证，可直接设置 API 密钥。
• options.headers：可选，设置自定义请求头。

网络

OpenCode 支持标准代理环境变量和自定义证书，适用于企业网络环境。

• OpenCode 遵循标准代理环境变量。

export HTTPS_PROXY=https://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

• TUI 与本地 HTTP 服务器进行通信。你必须为此连接绕过代理，以防止路由循环
• 如果你的代理需要基本身份验证，请在 URL 中包含凭据。

export HTTPS_PROXY=http://username:password@proxy.example.com:8080

• 如果你的企业使用自定义 CA 进行 HTTPS 连接，请配置 OpenCode 以信任这些证书。

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

故障排除

要调试 OpenCode 的问题，请先检查其存储在磁盘上的日志和本地数据。

• 日志文件写入位置：macOS/Linux: ~/.local/share/opencode/log/

  • 日志文件以时间戳命名（例如 2025-01-09T123456.log），并保留最近的 10 个日志文件
  • 你可以通过 --log-level 命令行选项设置日志级别以获取更详细的调试信息。例如：opencode --log-level DEBUG

• OpenCode 将会话数据和其他应用数据存储在磁盘上：

  • macOS/Linux: ~/.local/share/opencode/
  • 该目录包含：
    • auth.json - 身份验证数据，如 API 密钥、OAuth Token
    • log/ - 应用日志
    • project/ - 项目特定数据，如会话和消息数据
    • 如果项目位于 Git 仓库中，则存储在 .//storage/
    • 如果不是 Git 仓库，则存储在 ./global/storage/

• 如果想移除插件：

  • 打开你的全局配置文件，查找 plugin 键，将其设置为空数组来临时禁用它们

  {
    "$schema": "https://opencode.ai/config.json",
    "plugin": [],
  }

  • OpenCode 还可以从磁盘加载本地插件。临时将这些插件移走（或重命名文件夹），然后重新启动桌面应用。
    • macOS/Linux: ~/.config/opencode/plugins/

• 如果禁用插件没有帮助（或插件安装卡住了），请清除缓存以便 OpenCode 重新构建。

  • Linux：rm -rf ~/.cache/opencode

使用

OpenCode Go

OpenCode Go 是一项低成本的订阅服务（$10/月），为您提供对流行开源编程模型的可靠访问。Go 的工作方式与 OpenCode 中的其他提供商一样。您订阅 OpenCode Go 并获取 API 密钥。这是完全可选的，您不需要它也能使用 OpenCode。

• 我们测试了一组精选的开源模型，并与他们的团队讨论了如何最好地运行它们
• 我们与几家提供商合作，确保这些模型得到正确的服务
• 最后，我们对模型/提供商的组合进行了基准测试，并得出了一个我们乐于推荐的列表。

OpenCode Zen

类似地还有 OpenCode Zen，但是这个订阅不限于开源模型，而且是按照 Token 计费。

TUI

OpenCode 提供了一个交互式终端界面（TUI），用于配合 LLM 处理您的项目。

• 运行 OpenCode 即可启动在当前目录下启动 TUI

opencode

• 可以为指定的工作目录启动它

opencode /path/to/project

• 进入 TUI 后，您可以输入消息进行交互
• 可以使用 @ 在消息中引用文件。这会在当前工作目录中进行模糊文件搜索。文件的内容会自动添加到对话中
• 以 ! 开头的消息会作为 shell 命令执行，命令的输出会作为工具结果添加到对话中

!pwd

命令

使用 OpenCode TUI 时，您可以输入 / 后跟命令名称来快速执行操作

• /connect：将提供商添加到 OpenCode。允许您从可用的提供商中选择并添加其 API 密钥
• /compact：压缩当前会话
• /details：切换工具执行详情的显示
• /editor：打开外部编辑器来编写消息。使用 EDITOR 环境变量中设置的编辑器
• /exit：退出 OpenCode
• /export：将当前对话导出为 Markdown 并在默认编辑器中打开
• /help：显示帮助
• /init：创建或更新 AGENTS.md 文件
• /models：列出可用模型
• /new：开始新的会话。别名：/clear
• /undo：撤销对话中的最后一条消息。移除最近的用户消息、所有后续响应以及所有文件更改。
  • 在内部，这使用 Git 来管理文件更改。因此您的项目需要是一个 Git 仓库
• /redo：重做之前撤销的消息。仅在使用 /undo 后可用
  • 在内部，这使用 Git 来管理文件更改。因此您的项目需要是一个 Git 仓库
• /sessions：列出会话并在会话之间切换。别名：/resume、/continue
• /share：分享当前会话
• /unshare：取消分享当前会话
• /themes：列出可用主题
• /thinking：切换对话中思考/推理块的可见性。启用后，您可以看到支持扩展思考的模型的推理过程

配置 TUI 行为

• 可以通过 OpenCode 配置文件自定义 TUI 行为

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

CLI

OpenCode CLI 在不带任何参数运行时，默认启动 TUI。也可以接受要运行的命令，使您可以通过编程方式与 OpenCode 进行交互。

opencode run "Explain how closures work in JavaScript"

命令行标志

opencode 提供以下命令行标志，用于控制器其行为

| 标志 | 简写 | 描述 |
| :--- | :--- | :--- |
| --continue | -c | 继续上一个会话 |
| --session | -s | 要继续的会话 ID |
| --fork | | 继续时分叉会话（与 --continue 或 --session 配合使用） |
| --prompt | | 要使用的提示词 |
| --model | -m | 要使用的模型，格式为 provider/model |
| --agent | | 要使用的代理 |
| --port | | 监听端口 |
| --hostname | | 监听主机名 |

子命令

OpenCode CLI 还提供以下子命令。

• agent：管理 OpenCode 的代理
• attach：将终端连接到已通过 serve 或 web 命令启动的 OpenCode 后端服务器。这允许将 TUI 与远程 OpenCode 后端配合使用
• auth：管理提供商的凭据和登录信息的命令
• github：管理用于仓库自动化的 GitHub 代理
• mcp：管理 Model Context Protocol 服务器
• models：列出已配置提供商的所有可用模型。
• run：以非交互模式运行 OpenCode，直接传入提示词。这对于脚本编写、自动化或无需启动完整 TUI 即可快速获取答案的场景非常有用。
• serve：启动无界面的 OpenCode 服务器以提供 API 访问。此命令启动一个 HTTP 服务器，提供对 OpenCode 功能的 API 访问，无需 TUI 界面
• session：管理 OpenCode 会话
• stats：显示 OpenCode 会话的 Token 用量和费用统计信息
• export：将会话数据导出为 JSON
• import：从 JSON 文件或 OpenCode 分享链接导入会话数据
• web：启动带有 Web 界面的无界面 OpenCode 服务器
• acp：启动 ACP（Agent Client Protocol）服务器
• uninstall：卸载 OpenCode 并删除所有相关文件
• upgrade：将 OpenCode 更新到最新版本或指定版本

环境变量

OpenCode 可以通过环境变量进行配置。具体的环境变量参见这里。

Web

OpenCode 可以作为 Web 应用在浏览器中运行，无需终端即可获得同样强大的 AI 编码体验。通过如下命令启动 Web 界面：

opencode web

• 这会在 127.0.0.1 上启动一个本地服务器，使用随机可用端口，并自动在默认浏览器中打开 OpenCode
• 要使 OpenCode 在网络中可访问，可以使用 --hostname 0.0.0.0
• --port 标志可用于指定端口
• --cors 为 CORS 添加额外的允许域名（适用于自定义前端）
• 要保护服务器访问，可以通过 OPENCODE_SERVER_PASSWORD 环境变量设置密码

你可以将终端 TUI 连接到正在运行的 Web 服务器，这样你就可以同时使用 Web 界面和终端，共享相同的会话和状态：

opencode web --port 4096
opencode attach http://localhost:4096

你也可以在 opencode.json 配置文件中设置服务器选项。命令行标志的优先级高于配置文件中的设置。

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "cors": ["https://example.com"]
  }
}

分享

OpenCode 的分享功能允许您创建指向 OpenCode 对话的公开链接，方便与团队成员协作或向他人寻求帮助。当您分享一段对话时，OpenCode 会：

• 为您的会话创建一个唯一的公开 URL
• 将您的对话历史同步到我们的服务器
• 通过可分享的链接使对话可访问 — opncd.ai/s/<share-id>

默认情况下，OpenCode 使用手动分享模式。会话不会自动共享，但您可以使用 /share 命令手动分享

• 您可以在配置文件中将 share 选项设置为 auto，启用自动分享后，每个新对话都会自动共享并生成链接
• 在配置文件中将 share 选项设置为 disabled，完全禁用分享功能。
• /unshare 将移除分享链接并删除与该对话相关的数据

共享的对话在您明确取消分享之前将一直保持可访问状态。这包括：

• 完整的对话历史
• 所有消息和回复
• 会话元数据

GitHub

OpenCode 可以与你的 GitHub 工作流集成。在评论中提及 /opencode 或 /oc，OpenCode 就会在你的 GitHub Actions 运行器中执行任务。

• 问题分类：让 OpenCode 调查某个 Issue 并为你做出解释。
• 修复与实现：让 OpenCode 修复 Issue 或实现某个功能。它会在新分支中工作，并提交包含所有变更的 PR。
• 安全可靠：OpenCode 在你自己的 GitHub 运行器中运行

在一个位于 GitHub 仓库中的项目里运行以下命令：

opencode github install

该命令会引导你完成 GitHub App 的安装、工作流的创建以及密钥的配置。你也可以手动进行设置：

• 安装 GitHub App：前往 github.com/apps/opencode-agent，确保已在目标仓库中安装该应用
• 添加工作流：将以下工作流文件添加到仓库的 .github/workflows/opencode.yml 中。请确保在 env 中设置合适的 model 及所需的 API 密钥

name: opencode

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  opencode:
    if: |
      contains(github.event.comment.body, '/oc') ||
      contains(github.event.comment.body, '/opencode')
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
       - name: Checkout repository
         uses: actions/checkout@v6
         with:
           fetch-depth: 1
           persist-credentials: false

       - name: Run OpenCode
        uses: anomalyco/opencode/github@latest
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        with:
          model: anthropic/claude-sonnet-4-20250514
          # share: true
          # github_token: xxxx

• 将 API 密钥存储到 Secrets 中：在你的组织或项目的 Settings 中，展开左侧的 Secrets and variables，然后选择 Actions，添加所需的 API 密钥

OpenCode 可以由以下 GitHub 事件触发：

事件类型	触发方式	详情
issue_comment	在 Issue 或 PR 上发表评论	在评论中提及 /opencode 或 /oc。OpenCode 会读取上下文，并可创建分支、提交 PR 或回复。
pull_request_review_comment	在 PR 中对特定代码行发表评论	在代码审查时提及 /opencode 或 /oc。OpenCode 会接收文件路径、行号和 diff 上下文。
issues	Issue 被创建或编辑	在 Issue 创建或修改时自动触发 OpenCode。需要提供 prompt 输入。
pull_request	PR 被创建或更新	在 PR 被打开、同步或重新打开时自动触发 OpenCode。适用于自动化审查场景。
schedule	基于 Cron 的定时任务	按计划运行 OpenCode。需要提供 prompt 输入。输出会写入日志和 PR（没有 Issue 可供评论）。
workflow_dispatch	从 GitHub UI 手动触发	通过 Actions 选项卡按需触发 OpenCode。需要提供 prompt 输入。输出会写入日志和 PR。

GitLab

OpenCode 通过 GitLab CI/CD 流水线或 GitLab Duo 与你的 GitLab 工作流集成。在这两种情况下，OpenCode 都将在你的 GitLab Runner 上运行。

• OpenCode 可以在常规的 GitLab 流水线中运行。你可以将其作为 CI 组件 集成到流水线中
• OpenCode 与你的 GitLab 工作流集成。 在评论中提及 @opencode，OpenCode 将在你的 GitLab CI 流水线中执行任务

配置

工具

工具允许 LLM 在您的代码库中执行操作。OpenCode 自带一组内置工具，您也可以通过自定义工具或 MCP 服务器来扩展它。默认情况下，所有工具都是启用的，且无需权限即可运行。您可以通过权限来控制工具的行为。

• 使用 permission 字段来控制工具行为。您可以对每个工具设置允许、拒绝或需要审批，还可以使用通配符同时控制多个工具

以下是 OpenCode 中所有可用的内置工具：

• bash：在项目环境中执行 shell 命令
• edit：通过精确的字符串替换来修改现有文件，这是 LLM 修改代码的主要方式
• write：使用此工具允许 LLM 创建新文件。如果文件已存在，则会覆盖现有文件
• read：读取代码库中的文件内容
• grep：使用正则表达式搜索文件内容
• glob：通过模式匹配查找文件
• list：列出指定路径下的文件和目录
• lsp（实验性）：与已配置的 LSP 服务器交互，获取代码智能功能，如定义跳转、引用查找、悬停信息和调用层次结构
• patch：对文件应用补丁
• skill：加载一个技能（即 SKILL.md 文件）并在对话中返回其内容
• todowrite：在编码会话中管理待办事项列表。创建和更新任务列表以跟踪复杂操作的进度。LLM 使用此工具来组织多步骤任务
• todoread：读取现有的待办事项列表。LLM 使用此工具来跟踪哪些任务待处理、哪些已完成
• webfetch：获取网页内容。允许 LLM 获取并读取网页内容。适用于查阅文档或研究在线资源
• websearch：在网络上搜索信息。使用 Exa AI 进行网络搜索以查找相关信息。适用于研究主题、了解时事动态或获取超出训练数据截止日期的信息
• question：在执行过程中向用户提问

自定义工具允许您定义 LLM 可以调用的自定义函数。这些函数在您的配置文件中定义，可以执行任意代码。MCP（Model Context Protocol）服务器允许您集成外部工具和服务，包括数据库访问、API 集成和第三方服务。

在内部，grep、glob 和 list 等工具底层使用 ripgrep。默认情况下，ripgrep 遵循 .gitignore 中的模式，这意味着 .gitignore 中列出的文件和目录将被排除在搜索和列表结果之外。

规则

可以通过创建 AGENTS.md 文件来为 opencode 提供自定义指令。这类似于 Cursor 的规则功能。该文件包含的指令会被纳入 LLM 的上下文中，以便针对您的特定项目自定义其行为。

• 要创建新的 AGENTS.md 文件，您可以在 opencode 中运行 /init 命令，也可以手动创建此文件
• 应该将项目的 AGENTS.md 文件提交到 Git

opencode 还支持从多个位置读取 AGENTS.md 文件，不同的位置有不同的用途。

• 在项目根目录放置一个 AGENTS.md 文件，用于定义项目特定的规则。这些规则仅在您在该目录或其子目录中工作时生效
• 您还可以在 ~/.config/opencode/AGENTS.md 文件中设置全局规则。这些规则会应用于所有 opencode 会话

对于从 Claude Code 迁移过来的用户，OpenCode 支持 Claude Code 的文件约定作为回退方案：

• 项目规则：项目目录中的 CLAUDE.md（在没有 AGENTS.md 的情况下使用）
• 全局规则：~/.claude/CLAUDE.md（在没有 ~/.config/opencode/AGENTS.md 的情况下使用）
• 技能：~/.claude/skills/

当 opencode 启动时，它会按以下顺序查找规则文件，在每个类别中，第一个匹配的文件优先。

• 本地文件，从当前目录向上遍历（AGENTS.md、CLAUDE.md）
• 全局文件，位于 ~/.config/opencode/AGENTS.md
• Claude Code 文件，位于 ~/.claude/CLAUDE.md（除非已禁用，可以通过环境变量禁用 Claude Code 兼容性）

可以在 opencode.json 或全局配置文件 ~/.config/opencode/opencode.json 中指定自定义指令文件。这允许您和团队复用现有规则，而无需将它们复制到 AGENTS.md 中。

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

• 可以使用远程 URL 从网络加载指令
• 所有指令文件都会与您的 AGENTS.md 文件合并

虽然 opencode 不会自动解析 AGENTS.md 中的文件引用，但您可以通过以下两种方式实现类似的功能：

• 推荐的方式是使用 opencode.json 中的 instructions 字段来包含规则文件名
• 可以在 AGENTS.md 中提供明确的指令，教 opencode 读取外部文件

Agent

Agent 是专门的 AI 助手，可以针对特定任务和工作流程进行配置。它们允许您创建具有自定义提示词、模型和工具访问权限的专用工具。您可以在会话期间切换代理，或使用 @ 提及来调用它们。

OpenCode 中有两种类型的 Agent：主 Agent 和子 Agent。

• 主 Agent 是您直接交互的主要助手。您可以使用 Tab 键或配置的 switch_agent 快捷键来循环切换它们。这些代理处理您的主要对话。OpenCode 内置了两个主代理：Build 和 Plan
• 子代理是主代理可以调用来执行特定任务的专业助手。您也可以通过在消息中 @ 提及它们来手动调用。OpenCode 内置了两个子代理：General 和 Explore

内置 Agent

OpenCode 内置了两个主代理和两个子代理。

主代理：

• Build 是启用了所有工具的默认主代理。这是用于需要完全访问文件操作和系统命令的开发工作的标准代理
• Plan 是一个专为规划和分析设计的受限代理。我们使用权限系统来为您提供更多控制权，并防止意外更改。当您希望 LLM 分析代码、建议更改或创建计划，而不对代码库进行任何实际修改时，此代理非常有用

子代理：

• General 是一个用于研究复杂问题和执行多步骤任务的通用代理。拥有完整的工具访问权限（todo 除外），因此可以在需要时修改文件。可用于并行运行多个工作单元。
• Explore 是一个用于探索代码库的快速只读代理。无法修改文件。当您需要按模式快速查找文件、搜索代码中的关键字或回答有关代码库的问题时，请使用此代理。

另外还有几个隐藏的代理：

• Compaction：隐藏的系统代理，将长上下文压缩为较小的摘要。它会在需要时自动运行，且无法在 UI 中选择。
• Title：隐藏的系统代理，用于生成简短的会话标题。它会自动运行，且无法在 UI 中选择
• Summary：隐藏的系统代理，用于创建会话摘要。它会自动运行，且无法在 UI 中选择

对于主代理，在会话期间使用 Tab 键循环切换。您也可以使用配置的 switch_agent 快捷键。子代理可以通过以下方式调用：

• 由主代理根据其描述自动调用以执行专门任务
• 通过在消息中 @ 提及子代理来手动调用

当子代理创建自己的子会话时，可以在会话间通过快捷键导航，使您可以在主对话和专门的子代理工作之间无缝切换。

以自定义内置代理或通过配置创建自己的代理。代理可以通过两种方式进行配置：

• 在 opencode.json 配置文件中配置代理（agent 配置块）
• 使用 Markdown 文件定义代理。将它们放在：
  • 全局：~/.config/opencode/agents/
  • 项目级：.opencode/agents/

代理存在很多配置项，例如描述、温度、最大步数、提示词、模型、工具、权限、模式、top_p 等

• 通过模型配置，适用于针对不同任务使用不同的优化模型
• 如果您不指定模型，主代理将使用全局配置的模型，而子代理将使用调用它的主代理所使用的模型
• 使用 mode 配置控制代理的模式，用于确定代理的使用方式
  • mode 选项可以设置为 primary、subagent 或 all
  • 如果未指定 mode，则默认为 all

另外，使用 hidden: true 将子代理从 @ 自动补全菜单中隐藏。适用于只应由其他代理通过 Task 工具以编程方式调用的内部子代理。

使用 permission.task 控制代理可以通过 Task 工具调用哪些子代理：

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

• 规则按顺序评估，最后匹配的规则优先
• 用户始终可以通过 @ 自动补全菜单直接调用任何子代理，即使代理的任务权限会拒绝它

代理配置中指定的任何其他选项都将作为模型选项直接传递给提供商。这允许您使用提供商特定的功能和参数。例如，使用 OpenAI 的推理模型时，您可以控制推理力度。

模型

OpenCode 使用 AI SDK 和 Models.dev 支持 75+ LLM 提供商，并支持运行本地模型。

• 大多数热门提供商已默认预加载。如果你通过 /connect 命令添加了提供商的凭据，它们将在你启动 OpenCode 时自动可用
• 配置好提供商后，你可以通过输入 /models 命令来选择想要使用的模型
• 要将某个模型设为默认模型，可以在 OpenCode 配置中设置 model 字段
• OpenCode 配置中的模型 ID 使用 provider/model-id
  • 如果你配置了自定义提供商，provider_id 是配置中 provider 部分的键名，model_id 是 provider.models 中的键名
• 可以通过配置文件全局配置模型的选项，还可以为使用中的任何 Agent 配置这些选项。Agent 配置会覆盖此处的全局选项

你也可以定义扩展内置变体的自定义变体。变体允许你为同一个模型配置不同的设置，而无需创建重复的条目：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "opencode": {
      "models": {
        "gpt-5": {
          "variants": {
            "high": {
              "reasoningEffort": "high",
              "textVerbosity": "low",
              "reasoningSummary": "auto",
            },
            "low": {
              "reasoningEffort": "low",
              "textVerbosity": "low",
              "reasoningSummary": "auto",
            },
          },
        },
      },
    },
  },
}

OpenCode 启动时，会按以下优先顺序加载模型：

• –model 或 -m 命令行标志
• OpenCode 配置中的 model 字段
• 上次使用的模型
• 按内部优先级排列的第一个可用模型

快捷键

OpenCode 提供了一系列快捷键，您可以通过 tui.json 进行自定义。

• OpenCode 的大多数快捷键使用 leader（前导键）。这可以避免与终端中的其他快捷键冲突。
• 默认情况下，ctrl+x 是前导键，大多数操作需要您先按下前导键，然后再按对应的快捷键

OpenCode 桌面应用的提示词输入框支持常见的 Readline/Emacs 风格文本编辑快捷键。这些快捷键为内置功能，目前无法通过 opencode.json 进行配置。

命令

自定义命令允许你指定一个提示词，当在 TUI 中执行该命令时会运行这个提示词。

• 在 commands/ 目录中创建 markdown 文件来定义自定义命令
  • frontmatter 定义命令属性，内容则成为模板（template）
  • 通过输入 / 后跟命令名称来使用该命令

---
description: Run tests with coverage
agent: build
model: anthropic/claude-3-5-sonnet-20241022
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

• 也可以在 OpenCode 配置中使用 command 选项创建自定义命令

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    // This becomes the name of the command
    "test": {
      // This is the prompt that will be sent to the LLM
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      // This is shown as the description in the TUI
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    }
  }
}

自定义命令的提示词支持多种特殊占位符和语法。

• 使用 $ARGUMENTS 占位符向命令传递参数。
• 你还可以使用位置参数访问各个参数，$1、$2 等
• 使用 !command 将 bash 命令输出注入到提示词中
• 使用 @ 后跟文件名在命令中引用文件，文件内容会自动包含在提示词中

定义命令时，支持多个配置选项：

• template：定义执行命令时发送给 LLM 的提示词，这是一个必需的配置选项
• description：提供命令功能的简要描述
• agent：使用 agent 配置可选地指定由哪个代理执行此命令。如果这是一个子代理，该命令默认会触发子代理调用。要禁用此行为，请将 subtask 设置为 false。这是一个可选的配置选项。如果未指定，默认使用你当前的代理
• subtask：使用 subtask 布尔值强制命令触发子代理调用
  • 如果你希望命令不污染主要上下文，这会很有用，它会强制代理作为子代理运行。即使代理配置中的 mode 设置为 primary
  • 使用 model 配置覆盖此命令的默认模型

格式化工具

OpenCode 会在文件写入或编辑后，自动使用特定语言的格式化工具对其进行格式化。这确保了生成的代码遵循你项目的代码风格。

• OpenCode 内置了多种适用于主流语言和框架的格式化工具。因此，如果你的项目 package.json 中包含 prettier，OpenCode 会自动使用它进行格式化
• 可以通过 OpenCode 配置中的 formatter 部分自定义格式化工具

权限

OpenCode 使用 permission 配置来决定某个操作是否应自动运行、提示你审批，还是被阻止。从 v1.1.1 开始，旧版 tools 布尔配置已被弃用，并已合并到 permission 中。旧版 tools 配置仍然支持，以保持向后兼容。

每条权限规则解析为以下之一：

• “allow” — 无需审批直接运行
• “ask” — 提示审批
• “deny” — 阻止该操作

你可以全局设置权限（使用 *），并覆盖特定工具的权限。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

你还可以一次性设置所有权限：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": "allow"
}

对于大多数权限，你可以使用对象来根据工具输入应用不同的操作。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

规则通过模式匹配进行评估，最后匹配的规则优先。常见做法是将通配的 “*” 规则放在最前面，更具体的规则放在后面。

使用 external_directory 允许工具调用访问 OpenCode 启动时工作目录之外的路径。这适用于任何接受路径作为输入的工具。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

此处允许的任何目录都会继承与当前工作空间相同的默认值，当需要在这些路径中限制某个工具时，请添加显式规则，例如在保留读取的同时阻止编辑：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

如果你未指定任何配置，OpenCode 将使用宽松的默认值：

• 大多数权限默认为 allow
• doom_loop 和 external_directory 默认为 “ask”
• read 为 allow，但 .env 文件默认被拒绝

你可以为每个代理单独覆盖权限。代理权限会与全局配置合并，且代理规则优先。

LSP 服务器

OpenCode 与你的语言服务器协议（LSP）集成，帮助 LLM 与你的代码库进行交互。它利用诊断信息向 LLM 提供反馈。OpenCode 内置了多种适用于主流语言的 LSP 服务器：检测到上述文件扩展名且满足相应要求时，LSP 服务器会自动启用。

可以通过 opencode 配置文件中的 lsp 部分来配置 LSP 服务器等。

MCP 服务器

你可以通过 Model Context Protocol（MCP）为 OpenCode 添加外部工具。OpenCode 同时支持本地和远程服务器。添加后，MCP 工具会自动与内置工具一起提供给 LLM 使用。

• 使用 MCP 服务器时，它会占用上下文空间。如果你启用了大量工具，上下文消耗会迅速增加。因此，我们建议谨慎选择要使用的 MCP 服务器

你可以在 OpenCode 配置的 mcp 字段下定义 MCP 服务器。为每个 MCP 指定一个唯一的名称，在提示词中可以通过该名称来引用对应的 MCP。

通过在 MCP 对象中将 type 设置为 local 来添加本地 MCP 服务器，此时 command 用于指定本地 MCP 服务器的启动命令。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",
      // Or ["bun", "x", "my-mcp-command"]
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value",
      },
    },
  },
}

通过将 type 设置为 remote 来添加远程 MCP 服务器。此时 url 是远程 MCP 服务器的地址，通过 headers 选项可以传入一组请求头。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

另外，OpenCode 会自动处理远程 MCP 服务器的 OAuth 身份验证。当服务器需要身份验证时，OpenCode 将：

• 检测 401 响应并启动 OAuth 流程
• 在服务器支持的情况下使用动态客户端注册（RFC 7591）
• 安全地存储 Token 以供后续请求使用

你的 MCP 在 OpenCode 中作为工具使用，与内置工具并列。因此，你可以像管理其他工具一样，通过 OpenCode 配置来管理它们。

ACP 支持

OpenCode 支持 Agent Client Protocol（ACP），允许你直接在兼容的编辑器和 IDE 中使用它。ACP 是一个开放协议，用于标准化代码编辑器与 AI 编码代理之间的通信。

要通过 ACP 使用 OpenCode，请在编辑器中配置运行 opencode acp 命令。该命令会将 OpenCode 作为兼容 ACP 的子进程启动，通过 stdio 上的 JSON-RPC 与编辑器进行通信。

技能（skill）

技能让 OpenCode 能够从你的仓库或主目录中发现可复用的指令。 技能通过原生的 skill 工具按需加载：Agent 可以查看可用技能，并在需要时加载完整内容。

为每个技能名称创建一个文件夹，并在其中放入 SKILL.md。 OpenCode 会搜索以下位置：

• 项目配置：.opencode/skills/<name>/SKILL.md
• 全局配置：~/.config/opencode/skills/<name>/SKILL.md
• 项目 Claude 兼容：.claude/skills/<name>/SKILL.md
• 全局 Claude 兼容：~/.claude/skills/<name>/SKILL.md
• 项目 agent 兼容：.agents/skills/<name>/SKILL.md
• 全局 agent 兼容：~/.agents/skills/<name>/SKILL.md

对于项目本地路径，OpenCode 会从当前工作目录向上遍历，直到到达 git 工作树根目录。在此过程中，它会加载 .opencode/ 中所有匹配的 skills/*/SKILL.md，以及匹配的 .claude/skills/*/SKILL.md 或 .agents/skills/*/SKILL.md。

全局定义也会从 ~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md 和 ~/.agents/skills/*/SKILL.md 中加载。

每个 SKILL.md 必须以 YAML frontmatter 开头。 仅识别以下字段：

• name（必填）：与包含 SKILL.md 的目录名称一致
• description（必填）
• license（可选）
• compatibility（可选）
• metadata（可选，字符串到字符串的映射）

OpenCode 会在 skill 工具描述中列出可用技能。 每个条目包含技能名称和描述：

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

Agent 则通过调用工具来加载技能：

skill({ name: "git-release" })

在 opencode.json 中使用基于模式的权限来控制 agent 可以访问哪些技能。

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

为特定代理授予与全局默认值不同的权限。

• 自定义代理在代理 frontmatter 中进行权限配置
• 内置代理在 opencode.json 中进行配置

如果 agent 不需要使用 skill，只要将 skill 工具设置为 false 即可。

自定义工具

自定义工具是你创建的函数，LLM 可以在对话过程中调用它们。它们与 opencode 的内置工具（如 read、write 和 bash）协同工作。

• 工具以 TypeScript 或 JavaScript 文件的形式定义。不过，工具定义可以调用任何语言编写的脚本——TypeScript 或 JavaScript 仅用于工具定义本身

工具可以在以下位置定义：

• 本地定义：将工具文件放在项目的 .opencode/tools/ 目录中
• 全局定义：将工具文件放在 ~/.config/opencode/tools/ 中

创建工具最简单的方式是使用 tool() 辅助函数，它提供类型安全和参数校验。

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

export default tool({
  description: "Query the project database",
  args: {
    query: tool.schema.string().describe("SQL query to execute"),
  },
  async execute(args) {
    // Your database logic here
    return `Executed query: ${args.query}`
  },
})

• 文件名即为工具名称。上面的示例创建了一个名为 database 的工具
• 你也可以从单个文件中导出多个工具。每个导出都会成为一个独立的工具 命名格式为 <filename>_<exportname>。

自定义工具通过工具名称进行索引。如果自定义工具使用了与内置工具相同的名称，则优先使用自定义工具。

你可以使用任何语言编写工具。以下示例展示了如何用 Python 实现两数相加。

• 首先，创建一个 Python 脚本作为工具：

# .opencode/tools/add.py
import sys

a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

• 然后创建调用该脚本的工具定义：

import { tool } from "@opencode-ai/plugin"
import path from "path"

export default tool({
  description: "Add two numbers using Python",
  args: {
    a: tool.schema.number().describe("First number"),
    b: tool.schema.number().describe("Second number"),
  },
  async execute(args, context) {
    const script = path.join(context.worktree, ".opencode/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})