opencode 2.x 的安装和使用

发表于 2026-10-21 分类于 ai 置顶精品

阅读次数： 0 本文字数： 6.6k 阅读时长 ≈ 24 分钟

摘要

OpenCode 官网，OpenCode 2.x 文档，OpenCode 下载页
从 V1 迁移的官方说明
1.x 的安装和基本用法见 opencode的安装和使用。
本文写 OpenCode 2.x 的安装、从 1.x 升级，以及升级后配置和日常命令的写法。2.x 文档以英文为准。

OpenCode 1 和 OpenCode 2 都提供 opencode 这条命令，默认不能并排安装。用包管理器装的 1.x，先卸掉再装 2.x。用安装脚本装的 1.x，改用下面的 2.x 脚本，它会替换旧二进制。

brew upgrade anomalyco/tap/opencode 和 1.x 里的普通更新都停留在 1.x。换到 2.x 是一次单独操作。

升级时会碰到的变化

现有的 opencode.json、agent、command、skill 和 .opencode/ 可以继续用。2.x 在内存里识别 1.x 字段，不改写配置文件。日常终端用法可以先升级，再按需要改成 2.x 写法。

官方列出的三处不兼容：

项目	2.x 的要求
插件	按新的插件 API 重写。只改配置键或把文件挪进 `plugins/`，1.x 插件代码不会执行
服务端 API 和自写客户端	改用 `@opencode/client` 和 2.x 接口。2.1 又把回放数据字段统一成 `native`
终端界面配置	多层 `tui.json` 改为一个全局文件 `~/.config/opencode/cli.json`，首次启动会迁移全局配置

就算配置一个字都不改，这几处行为也会变：

项目外目录默认允许访问。1.x 会先询问。要恢复询问，加上 external_directory 的 ask 规则。
待办工具默认关闭。需要时打开 experimental.todo。
lsp 配置仍会被接受，2.x 不启动语言服务器，也不提供 lsp 工具。原来靠 lsp 做的检查，改跑项目自己的 lint、类型检查或编译命令。
远程 MCP 默认走 OAuth。只用 API Key 的服务要写 "oauth": false。
MCP 工具默认经 Code Mode 调用。要像 1.x 那样直接出现在工具列表里，给该服务器加 "codemode": false。
会话分享在 1.19.1 已经停止，/share 和分享链接不再可用。

安装

装完执行 exec $SHELL，再用下面两条确认 shell 找到的是新程序：

1 2	which opencode opencode --version

版本号应是 2. 开头。写作时 changelog 最新版本是 v2.1.2（2026-10-21）。

macOS

选一种方式即可。已经用 1.x 那篇里的 tap 装过的，走下一节的升级步骤，不要在旧 formula 旁边再装一个。

# 官方安装脚本。会把 opencode 写入 PATH；没有 ~/.zshrc 时会创建
curl -fsSL https://opencode.ai/v2/install | bash

# npm。包名是 @opencode/cli，1.x 的包名 opencode-ai 只对应 1.x
npm install -g @opencode/cli

# bun。--trust 用来允许安装脚本挑选当前平台的二进制
bun install -g --trust @opencode/cli

# Homebrew Core。formula 名是 opencode，跟踪 2.x
brew install homebrew/core/opencode

# 下载页给出的 tap
brew install anomalyco/tap/opencode-v2

用 mise 安装时，mise 需要 2026.10.9 或更新版本。更早的 mise 会装到 OpenCode 1。

Homebrew 两条都装时会抢同一个 opencode 命令。机器上如果还留着 anomalyco/tap，brew install opencode 可能同时匹配 tap 里的 1.x formula 和 Core 里的 2.x formula，所以这里写成完整名 homebrew/core/opencode。

在 2.x 内升级

# 安装脚本、npm、bun
opencode upgrade

# 升到指定版本。--method 换成自己的安装方式，例如 bun、npm
opencode upgrade 2.1.2 --method bun

# Homebrew Core
brew upgrade homebrew/core/opencode

# tap
brew upgrade anomalyco/tap/opencode-v2

Homebrew 安装的版本以 formula 为准，用 brew upgrade 保持和 formula 一致。升级前先退出正在运行的 opencode。

自动更新写在全局配置里，项目级配置里的同名字段不生效。默认是发现新版本后提示，不自动安装：

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

update 取值：notify（提示）、auto（自动安装）、disable（不检查）。自动安装不会重启已经在跑的后台服务，装完后执行 opencode service restart。

卸载

1 2	opencode uninstall --dry-run opencode uninstall

卸载会停掉后台服务，并删掉各版本共用的全局缓存。会话、配置和 state 会保留。包管理器安装会走对应的包管理器；安装脚本会打印删除二进制的命令。

桌面版、Windows 和 Linux

桌面版和终端版是两套程序。macOS 可以用：

1	brew install --cask opencode-desktop

Windows、Linux 的桌面安装包在下载页。官方文档写明不支持 Windows 包管理器；Windows 用 npm、bun，或下载页上的独立二进制。

Linux 同样可以用上面的安装脚本和 npm。Arch 系下载页给出的包名是：

1 2	paru -S opencode-beta yay -S opencode-beta

Docker 镜像使用带版本号的 tag，例如 ghcr.io/anomalyco/opencode:2.0.0。具体版本以镜像仓库里的 tag 为准。

从 1.x 升级到 2.x

升级前

退出所有 opencode 窗口，再备份配置。1.x 和 2.x 读写同一批配置路径，备份留到确认 2.x 可用之后再删。

1	cp -a ~/.config/opencode ~/.config/opencode.v1-backup

项目里的 opencode.json、opencode.jsonc 和 .opencode/ 一并复制备份。先不要把配置改成只有 2.x 才认识的写法；回退到 1.x 时，1.x 读不了这种文件。

建议先把 1.x 升到 1.19 或更高，再做大版本切换。1.19.0 开始提供 opencode upgrade --major 和 TUI 里的 /update。1.19.2 起，普通更新只看 opencode-ai 的 1.x 版本，不会把 2.x 当成一次普通更新装上来。

Homebrew

1.x 那篇用的是 brew install anomalyco/tap/opencode。这个 formula 继续提供 1.x。

brew uninstall anomalyco/tap/opencode
brew install homebrew/core/opencode
exec $SHELL
which opencode
opencode --version

想跟下载页走 tap 时，把第二条换成：

1	brew install anomalyco/tap/opencode-v2

Core 和 opencode-v2 二选一。

npm

1.x 的全局包是 opencode-ai，2.x 是 @opencode/cli。Windows 上 1.x 自带的升级器经常报 Upgrade failed for npm，直接换包即可。先关掉所有 opencode 进程，避免文件被占用。

1
2
3

npm uninstall -g opencode-ai
npm install -g @opencode/cli
opencode --version

安装脚本

1.x 的安装脚本会拒绝安装 2.x。使用 2.x 的地址，它会替换原来的二进制：

1
2
3

curl -fsSL https://opencode.ai/v2/install | bash
exec $SHELL
opencode --version

1.19 的大版本升级命令

1.19 及以上可以在终端执行：

1	opencode upgrade --major

TUI 里用 /update，其中的 2.0 选项也是同一次大版本升级。这个升级器失败时，改用上面和自己安装方式对应的换包命令。失败不表示必须先改配置。

升级后核对

opencode --version
opencode auth list
opencode mcp list
opencode plugin list
opencode debug agents
opencode debug config

然后在一个熟悉的项目里打开 opencode，确认模型、登录状态、agent、权限提示和 MCP 连接。插件需要按下一节处理，升级完成时插件列表里出现旧包名，不代表 1.x 插件已经在运行。

配置

可以继续用的部分

2.x 读取和 1.x 相同的配置位置，并在内存里归一化，不回写文件：

/Library/Application Support/opencode/opencode.json(c)
/etc/opencode/opencode.json(c)
%ProgramData%\opencode\opencode.json(c)
~/.config/opencode/opencode.json(c)
<项目>/opencode.json(c)
<项目>/.opencode/opencode.json(c)

macOS 还会读 MDM 下发的受管偏好，域名是 ai.opencode.managed。用户级文件优先于机器级文件：

1 2	/Library/Managed Preferences/<user>/ai.opencode.managed.plist /Library/Managed Preferences/ai.opencode.managed.plist

优先级从低到高：

顺序	位置	说明
1	`~/.config/opencode/opencode.json(c)`	当前用户，所有项目
2	从外到内的 `<目录>/opencode.json(c)`	越靠近当前目录越高
3	从外到内的 `<目录>/.opencode/opencode.json(c)`	同一层里，`.opencode` 里的配置盖过直接放在目录下的配置
4	系统目录	macOS 为 `/Library/Application Support/opencode`，Linux 为 `/etc/opencode`，Windows 为 `%ProgramData%\opencode`
5	macOS 受管偏好	最高。受管策略也压过全局和项目里的策略

系统目录里除了 opencode.json(c)，还会加载 agents/、commands/、skills/、plugins/。JSON 和 JSONC 都可以；JSONC 能写注释和行尾逗号。编辑器校验使用：

1
2
3

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

配置字符串里可以写 {env:变量名} 和 {file:路径}。变量或文件不存在时替换成空字符串。文件路径相对当前配置文件，也可以是绝对路径或以 ~/ 开头。

看实际合并了哪些文件：

1 2	opencode debug config opencode debug paths

改完配置后可以不重启服务：

1	opencode reload

正在进行的会话会在下一步开始使用新配置。被监视目录里的 opencode.json 保存后也会自动重载，不必为此重启后台服务。换掉已经安装的 Git 插件版本是例外，见下面的 Plugin。

字段对照

1.x 字段可以继续留着。准备改成 2.x 写法时，同一层里两种写法可以并存；同一个值两边都写了，有效的 2.x 值优先。mcp、compaction、experimental 内部允许混用。单个 agent、provider、command、model 不要一半 1.x、一半 2.x。

1.x	2.x
`permission`	`permissions`，有序数组，后匹配的规则生效
`bash`	`shell`
`task`	`subagent`
`write`、`patch` 权限	并入 `edit`
`tools.websearch: false`	`{ "action": "websearch", "resource": "*", "effect": "deny" }`
`plugin`	`plugins`。带选项的项从 `[路径, 选项]` 改为 `{ "package", "options" }`
`provider`	`providers`
`provider.*.npm`	`package`。AI SDK 包加前缀 `aisdk:`
`provider.*.api`	`settings.baseURL`
`provider.*.options`	按用途拆到 `settings`、`headers`、`body`
`agent`、`mode`	`agents`。旧 `mode` 成为 primary agent
`prompt`	`system`。Markdown agent 的正文就是系统提示，不必再写 `system` 字段
`disable`	`disabled`
`model` + `variant`	`provider/model#variant`
`maxSteps`	`steps`
`snapshot`	`snapshots`
`attachment`	`media`
`mcp` 下直接写服务器名	`mcp.servers`
`enabled: true`	`disabled: false`
`timeout: 30000`	`timeout.catalog` 与 `timeout.execution`
`clientId`、`clientSecret`、`callbackPort`、`redirectUri`	`client_id`、`client_secret`、`callback_port`、`redirect_uri`
`compaction.preserve_recent_tokens`	`compaction.keep.tokens`
`compaction.reserved`	`compaction.buffer`
`skills.paths` 和 `skills.urls`	`skills` 字符串数组
`command`	`commands`
`subtask`	`subagent`。旧字段仍接受；两个都写时 `subagent` 生效
`reference`	`references`
`autoupdate`	`update`。`false` 为 `disable`，`true` 为 `auto`，`notify` 仍是 `notify`
`small_model`	`agents.title.model`
`enabled_providers`、`disabled_providers`	由内部策略实现，旧字段可以留着
`azure-cognitive-services`	`azure`
`google-vertex-anthropic`	`google-vertex`

顶层 model 不会自动把旧 provider id 换成上表的新 id，用到这两个旧 id 时自己改。

下面这些 1.x 字段会被忽略并给出警告：logLevel（改用启动时的 OPENCODE_LOG_LEVEL）、顶层 server、顶层 subagent_depth（改到 experimental.subagent_depth）、compaction.tail_turns、compaction.prune，以及一批没有 2.x 行为的实验字段和 provider 字段。完整列表见迁移文档。

shell、model、default_agent、watcher、formatter、instructions、enterprise、tool_output 的形状不用改。

终端配置

界面主题、快捷键、标签页、diff 视图放在：

1	~/.config/opencode/cli.json

设置了 XDG_CONFIG_HOME 时，路径是 $XDG_CONFIG_HOME/opencode/cli.json。后台服务不读这个文件。2.x 第一次启动、且 cli.json 还不存在时，会把全局 tui.json 里支持的项迁过来，并保留原来的 tui.json。项目里的 tui.json 不会迁，因为 2.x 的终端配置只有全局一份。

临时盖过全局界面配置：

1	OPENCODE_CLI_CONFIG_CONTENT='{"tabs":{"mode":"off"}}' opencode

Schema 是 https://opencode.ai/v2/cli.json。字段说明见 CLI settings。

让 OpenCode 改配置

2.x 跑通之后，可以把改写交给它。先保留备份。

1 2	Migrate my OpenCode configuration, including file-based definitions, from the V1 format to the native V2 format. Preserve its behavior and all unrelated settings.

改完的文件不要再交给 1.x 使用。

使用

启动和后台服务

cd your-project
opencode

# 打开另一个目录
opencode ~/code/my-project

2.x 默认为本机用户启动一个共享后台服务。终端、桌面和网页都连这个服务，会话、配置、权限和工具执行都在服务里。

opencode service status
opencode service restart
opencode service stop

# 这次使用私有服务，不挂到共享服务上
opencode --standalone

# 连到指定服务
opencode --server http://localhost:4096

# 以后默认都用私有服务。配对需要共享服务，关掉之后不可用
opencode service set disabled true
opencode service unset disabled

推荐终端是 Ghostty、WezTerm、Alacritty、Kitty。支持 truecolor 时主题颜色最准确。

不打开全屏界面、直接要回复：

1
2
3

opencode run "Explain this repository"
opencode run --continue "Now handle the expired case"
opencode run --model anthropic/claude-sonnet-4-5 --agent build "Fix the failing test"

不写 --model 时，opencode run 使用配置里的 model；没有这项时，使用上次在 TUI 里选中的模型。看到 insufficient balance (1008) 表示这次请求打到了余额不足的付费账号。1008 是 MiniMax 的余额不足错误码。自己在 providers 里配置的按量计费模型，例如 my-minimax/MiniMax-M2.7，和 OpenCode Zen 的免费模型不是同一条线路。

免费模型的提供商是 opencode。单次运行直接指定：

opencode run --model opencode/big-pickle "Explain this repository"
opencode run --model opencode/glm-5.3-flash-free "Explain this repository"
opencode run --model opencode/deepseek-v4.1-flash-free "Explain this repository"
opencode run --model opencode/minimax-m3.1-flash-free "Explain this repository"

让以后不带 --model 的 opencode run 也走免费模型，在全局 opencode.json 里写上：

1
2
3

{
  "model": "opencode/big-pickle"
}

这项会自动加载，不用重启 service。可用模型以 opencode models 和 OpenCode Zen 为准，选名字里带 Free 的，或 big-pickle。换成免费模型后如果变成 api_key_expired，按「免费模型报 API key 过期」换一把新的 oc_sk_ key。

CI 里加上 --standalone，让这次私有服务拿到密钥。轻量交互界面：

1	opencode mini

把浏览器连到本机服务。链接 5 分钟内有效，且只能用一次：

1	opencode pair

输入

在项目里输入任务后回车。换行用 Shift+Enter、Ctrl+Enter、Alt+Enter 或 Ctrl+J。模型还在工作时，回车会把这句话送进当前这轮；先按 Ctrl+X 再回车，则排到后面。

输入	作用
`/`	斜杠命令。继续输入可以过滤，`Ctrl+P` 打开命令面板
`!`	写在空提示开头时进入 shell。`Esc` 退出且不执行。输出留在会话里
`@`	提及文件。`@src/auth.ts#20-45` 可以带行范围
`/btw 问题`	用当前会话的上下文问一句。回答不写回会话
`/copy`	复制最近一条助手回复，或已完成的压缩摘要

Leader 键默认是 Ctrl+X。常用组合：

快捷键	作用
`Ctrl+P`	命令面板
`Ctrl+X` 然后 `M`	选择模型。`F2` 在最近用过的模型间切换
`Ctrl+X` 然后 `A`，或 `Shift+Tab`	选择或轮换 agent
`Ctrl+X` 然后 `N`	新会话
`Ctrl+X` 然后 `L`	会话列表。`Ctrl+O` 同时看最近的会话和项目
`Ctrl+X` 然后 `U` / `R`	撤销 / 重做上一轮用户消息及其后的改动
`Ctrl+X` 然后 `E`	用 `VISUAL` 或 `EDITOR` 编辑当前输入
`Ctrl+Tab` / `Ctrl+Shift+Tab`	切换标签。`Ctrl+X` 然后 `W` 关闭，`Ctrl+Shift+T` 重新打开
`Ctrl+T`	切换模型变体

全部按键见 Keybinds。TUI 里的 / 列表会随版本增加，以命令面板为准。

常用命令

斜杠命令里常用的有 /models、/agents、/sessions、/undo、/redo、/editor、/mcps、/connect、/diff、/highlights、/copy、/btw。

终端子命令：

命令	作用
`opencode auth login <provider>`	登录模型服务。`auth list`、`auth logout`、`auth switch` 管理账号
`opencode models`	列出可用模型
`opencode mcp`	添加、列出、登录 MCP
`opencode plugin`	安装、检查、更新、移除插件
`opencode session list`	列出会话。还有 `delete`、`export`、`import`
`opencode stats`	用量统计
`opencode serve`	起 API 和网页服务
`opencode pair`	生成一次性连接链接
`opencode service`	管理后台服务
`opencode reload`	重载配置
`opencode upgrade`	升级 2.x
`opencode debug config`	查看配置来源
`opencode debug agents`	列出 agent
`opencode debug paths`	打印 db、config、cache 等路径

每个子命令都可以加 --help。

免费模型报 API key 过期

免费模型走 OpenCode Console（Zen）的凭证。看到下面这句时，本机保存的是一把已经过期的 API key：

1	This API key has expired. Create a new API key in OpenCode Console and replace it in your client or secret store. Signing in again will not renew this key.

重新登录不会把这把 key 续期。浏览器设备码登录拿到的是另一套 OAuth 令牌，替换不了已经写进客户端的过期 key。到 Console 新建一把，再用 API key 方式写回去。

打开 opencode.ai/auth 登录，进入 Account › Personal API keys，点 Add API key。选好工作区，过期时间选 Never，创建后立刻复制。完整 key 只显示一次，以 oc_sk_ 开头。
先删掉旧账号，再写入新 key。集成 id 是 opencode，界面名称是 OpenCode Zen。--method key 用来指定 API key，避免又走进浏览器登录：

1
2
3

opencode auth logout
opencode auth login opencode --method key
opencode auth list

TUI 里等价操作是 /connect，选择 OpenCode Zen，认证方式选 API key，粘贴新 key。

重启后台服务，让正在运行的进程用上新凭证。桌面版和终端共用这份凭证，改完后把桌面版完全退出再开。

1	opencode service restart

执行 /models，选一个名字里带 Free 的模型，发一句短消息。免费模型列表和价格见 OpenCode Zen。

还是 api_key_expired 时，说明旧 key 仍在被发送。逐项检查，把旧值换成新 key，或直接删掉：

位置	处理
`OPENCODE_API_KEY`	看 `~/.zshrc` 和项目 `.env`。后台服务里用 `opencode service unset env OPENCODE_API_KEY` 清掉
全局或项目配置里的 `apiKey`	1.x 写法在 `provider.opencode.options.apiKey`，2.x 写法在 `providers.opencode.settings.apiKey`
已保存的账号	`opencode auth list` 里仍是旧账号时，再执行一次 `auth logout` 和 `auth login`

凭证存在服务端的 SQLite 里，用 opencode debug paths db 可以看路径，通常是 ~/.local/share/opencode/opencode.db。不要手改这个库。同一个集成上，已保存的账号优先于环境变量。

新 key 创建后本身也报过期，就是 Console 一侧的问题。把发生时间和完整报错发给 help@anoma.ly，邮件里不要贴完整 key。

权限

规则是有序数组，后匹配到的生效。没有任何规则命中时才回退到询问。内置 agent 自己带一份基础策略，默认允许工具，读取 *.env 和 *.env.* 时询问，*.env.example 允许。用户配置接在基础策略后面。

1.x 那篇里的 bash / edit 例子，在 2.x 写成：

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git *", "effect": "allow" },
    { "action": "shell", "resource": "npm *", "effect": "allow" },
    { "action": "shell", "resource": "rm *", "effect": "deny" },
    { "action": "shell", "resource": "grep *", "effect": "allow" },
    { "action": "edit", "resource": "*", "effect": "deny" },
    { "action": "edit", "resource": "packages/web/src/content/docs/*.mdx", "effect": "allow" }
  ]
}

effect 为 allow（直接执行）、ask（询问）、deny（拒绝）。* 匹配任意长度，? 匹配一个字符。以 * 结尾的 shell 规则同时匹配不带参数的命令，所以上面的 git * 同时覆盖 git 和 git status。

搜索工具的动作是 grep，资源是正则本身。shell 里执行 grep 命令仍用 shell。这是两条规则。

要恢复 1.x「走出项目目录先询问」：

{
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" }
  ]
}

常用动作：read、edit（含 write 和 patch）、glob、grep、shell、subagent、skill、question、webfetch、websearch、external_directory。选择 Always 会把允许规则存进项目，且不能压过配置里的 deny。

组织级硬拒绝写在 policies 里。策略只能把结果收紧成拒绝，不能把拒绝改成允许。受管配置和全局策略压过项目配置。

Agents

Agent	模式	作用
`build`	primary	默认编码 agent。工具默认可用，读 `.env` 会询问
`plan`	primary	规划。普通项目文件不可编辑，可以写 `~/.opencode/plan` 下的计划文件
`general`	subagent	多步任务。不能再派生子 agent，也不能向用户提问
`explore`	subagent	搜索和阅读。可以使用 shell、读取、glob、grep 和网页工具，不能改文件
`title`、`summary`、`compaction`	隐藏	标题、摘要、压缩上下文。不能手动选择

2.x 没有内置 scout。旧的 mode/、modes/、agent/ 目录仍会被发现。新文件放在：

1 2	~/.config/opencode/agents/<name>.md .opencode/agents/<name>.md

从 mode/ 或 modes/ 挪到 agents/ 时，在 frontmatter 里加上 mode: primary。嵌套路径会进 id，例如 .opencode/agents/team/reviewer.md 的 id 是 team/reviewer。

---
description: Reviews changes for correctness and regressions
mode: subagent
model: anthropic/claude-sonnet-4-5#high
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---

Review the current changes. List findings in severity order with file and line references.

mode 省略时，新建的自定义 agent 默认是 primary。还可以是 subagent 或 all。默认主 agent：

1
2
3

{
  "default_agent": "build"
}

查看已加载的 agent：

1	opencode debug agents

1.x 的 opencode agent create 交互命令在 2.x 文档里没有对应子命令，直接写 Markdown 或配置即可。

自定义命令

新文件放在 commands/。1.x 的 command/ 仍会被发现。

1 2	~/.config/opencode/commands/review.md .opencode/commands/review.md

---
description: Review code for correctness
agent: plan
model: anthropic/claude-sonnet-4-5#high
---

Review $ARGUMENTS. Report bugs first.

$ARGUMENTS 是整段参数。$1、$2 是按空格拆开的参数，引号里的空格算一个参数。模板里没有这些占位符时，参数会附加在正文后面。

用 !`命令` 可以把命令输出插进提示。这个 shell 在提交前提前执行，不走 agent 的权限询问，只放自己信任的命令。

subagent: true 时，命令在后台子会话里跑，父会话保持原来的 agent 和模型。同名命令，项目级盖过全局。

Plugin

配置键是 plugins。全局、项目和 .opencode/opencode.json(c) 里的数组合并，按优先级从低到高追加，不是整段替换。

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": [
    "opencode-example-plugin",
    {
      "package": "./plugins/local.ts",
      "options": { "enabled": true }
    }
  ]
}

本地插件还会从这些目录自动加载直接放进去的 .ts、.js 和插件包目录：

1 2	~/.config/opencode/plugins/ .opencode/plugins/

1.x 的 .opencode/plugin/ 也会被发现。新插件放 plugins/。和 opencode.json 平级的 plugins/ 不会自动加载，需要写进 plugins 配置，或挪到 .opencode/plugins/。

用 - 前缀关闭某个插件，* 表示全部：

1
2
3

{
  "plugins": ["*", "-opencode.provider.*", "opencode.provider.openai"]
}

管理全局 npm / Git 插件：

opencode plugin add opencode-example-plugin
opencode plugin add github:acme/opencode-plugin
opencode plugin list
opencode plugin check
opencode plugin update
opencode plugin remove opencode-example-plugin

Git 地址可以在 # 后面加标签、分支或完整 commit，用来固定版本。# 后面是完整 commit 时，opencode plugin update 会跳过它。去掉这段之后，安装的是仓库默认分支的当前提交，启动时会检查更新，但这次检查不会替换已经装好的包。

superpowers 在 2.x 上的官方写法不带标签，跟踪 main：

{
  "plugins": [
    "superpowers@git+https://github.com/obra/superpowers.git"
  ]
}

要停在某个发布版，加上标签。2.x 使用 v6.4.1 或更高；v6.3.0 及更早的包只在 1.x 里加载：

{
  "plugins": [
    "superpowers@git+https://github.com/obra/superpowers.git#v7.0.0"
  ]
}

从带标签改成不带标签时，配置会自动重载，已经按旧标签装进缓存的包不会因此换成默认分支。执行：

1	opencode service restart

重启会中断正在跑的会话。起来之后如果内容仍是旧标签里的版本，再执行 opencode plugin update。已解析过的 Git 依赖可能留在缓存里，只重启不会拉到新提交。

1.x 插件函数在 2.x 里不会运行。配置从 plugin 改名，或把文件拷到 plugins/，都不够。入口要改成 @opencode/plugin 的 Plugin.define({ id, setup })。迁移步骤见 Migrate plugins from V1。

2.1 对插件和 HTTP 接口又改了一批字段：回放数据统一叫 native，不再使用 providerState、providerResultState 这些名字。终端日常使用不受影响。自写插件和自写客户端要按 changelog 的 v2.1.0 改。

只在终端生效的插件写在 cli.json 的 plugins 里，连远程服务时仍然加载。

Skill

技能文件的发现位置和 1.x 相同，.claude/skills 也仍会发现。新技能放在：

1 2	.opencode/skills/<name>/SKILL.md ~/.config/opencode/skills/<name>/SKILL.md

单数目录 skill/ 也会被发现。搬迁时移动整个技能目录，目录名就是技能 id。SKILL.md 的 frontmatter 不用为 2.x 重写。

额外搜索路径和 URL 合成一个数组，写在后面的优先：

1
2
3

{
  "skills": ["./team-skills", "https://example.com/.well-known/skills/"]
}

在对话里用 / 打开技能列表，或在提示里点名某个技能。也可以用权限只放开指定 id：

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "deny" },
    { "action": "skill", "resource": "effect", "effect": "allow" }
  ]
}

不需要发现 .claude 技能时，设置环境变量 OPENCODE_DISABLE_CLAUDE_CODE_SKILLS。OPENCODE_DISABLE_CLAUDE_CODE 会一并关掉相关的 Claude Code 发现。

MCP

服务器写在 mcp.servers 下面，不再直接挂在 mcp 上。1.x 的写法仍能被读入；改成 2.x 时用下面的形状。

1.x 那篇里的高德远程服务只用 key、不走 OAuth，2.x 要显式关掉 OAuth：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "amap": {
        "type": "remote",
        "url": "https://mcp.amap.com/mcp?key={env:AMAP_KEY}",
        "oauth": false
      }
    }
  }
}

命令行添加。不加 --global 时写入当前项目配置：

# 远程，默认 OAuth
opencode mcp add context7 --url https://mcp.context7.com/mcp

# 所有项目可用
opencode mcp add context7 --global --url https://mcp.context7.com/mcp

# 本地进程。命令放在 -- 后面
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything

# 带环境变量
opencode mcp add everything --env LOG_LEVEL=debug -- npx -y @modelcontextprotocol/server-everything

opencode mcp list
opencode mcp auth sentry
opencode mcp logout sentry

TUI 里用 /mcps 查看、连接、断开和登录。断开连接不改配置；要一直保持不连接，把该服务器设为 "disabled": true。

本地服务器：

{
  "mcp": {
    "timeout": {
      "startup": 30000,
      "catalog": 30000,
      "execution": 600000
    },
    "servers": {
      "everything": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
        "environment": {
          "MCP_API_KEY": "{env:MCP_API_KEY}"
        }
      }
    }
  }
}

startup 和 catalog 默认 30 秒，execution 默认 12 小时。某个服务器自己的 timeout 盖过这组默认值。

默认 codemode: true，agent 通过 Code Mode 按服务器命名空间调用工具。希望工具直接出现在模型的工具列表里：

{
  "mcp": {
    "servers": {
      "amap": {
        "type": "remote",
        "url": "https://mcp.amap.com/mcp?key={env:AMAP_KEY}",
        "oauth": false,
        "codemode": false
      }
    }
  }
}

工具名会规范成 <服务器>_<工具>，字母、数字、_、- 以外的字符变成 _。需要预注册 OAuth 客户端时，字段用 client_id、client_secret、callback_port、redirect_uri。

工具

直接描述要做的事即可，模型自己选工具。和 1.x 对照：

工具	说明
`read` `glob` `grep`	读文件、按模式找文件、按正则搜内容
`edit` `write`	精确替换，或整文件创建、覆盖。权限动作都是 `edit`
`patch`	多文件补丁。目前提供给受支持的 GPT 模型，其他模型使用 `edit` 和 `write`
`shell`	1.x 的 `bash`。用 `workdir` 指定目录，用 `timeout` 指定毫秒。长驻进程设 `background: true`
`webfetch` `websearch`	抓取 URL，或搜索网页。搜索服务由 `websearch.provider` 选择
`question`	向用户提问
`skill`	加载一个技能
`subagent`	1.x 的 task。启动子会话
`execute`	在 Code Mode 里组合工具调用。拒绝 `execute` 的 `*` 后，只通过它暴露的工具一并不可用
`todowrite`	默认关闭。配置 `experimental.todo: true` 后才有，TUI 会显示任务列表

项目外路径还会再过一遍 external_directory，这条默认允许。

改文件之后可以自动格式化：

1
2
3

{
  "formatter": true
}

摘要