OpenCode 怎么用

0030 秒速览：三条结论 + 按处境挑动作

读完这一篇，你能做出三个判断：你该用哪条安装路线、第一件事该敲什么、以及在哪一步必须先把闸门关上（因为 OpenCode 默认允许 AI 直接改你的文件，这一步不做，风险是你自己的）。

按你的处境，直接做这一件

一条可执行的上手路径

01它到底会改我的文件吗

会。这是理解 OpenCode 的第一道分水岭，也是最多人误解的地方——所以先把这句话放在最前面：你说一句"把登录那块的 bug 修了"，它真的会去改你的源码文件，不是给你一段建议让你自己粘。

它不是哪几样东西

下面这几个"它不是"，每一条都对应一个新手真的会踩的误解。看的时候顺便对一下你自己的预期。

它和最常见的三个近邻差在哪

这一张表不是评测，是"该选哪个"的判断依据。下面每一行的差异点都能在你自己的使用场景里对照出来。

里面有什么：六个零件

你不需要背这张图，但看一眼能省掉后面一半的困惑——比如"为什么我要登录两次""为什么模型列表在另一个地方"。

02为什么不全用现成的工具

官方的仓库描述只有一句：The open source coding agent.（开源的编程代理）。它刻意把自己定位在"开源"和"代理"这两个字上，所以它的价值主张也得从这两处读。

它解决的是四类具体问题，不是"更好用"

决定要不要用它，问自己三句话

• 我的活儿主要在终端里发生吗？如果开发、构建、测试全在终端，它的贴合度最高。
• 我愿意让一个程序直接改我的文件吗？如果不愿意，它还有一半价值——你可以只用 Plan 模式当"会读库的分析师"。
• 我手上有没有一个可用的模型入口？没有 API Key 也没有 Zen，就先去 04 把这一步解决，别急着装。

03装哪一条：六种安装方式怎么选

OpenCode 的安装方式多到有点烦，但它们的差别其实只有两点：谁帮你管更新、你的机器上已经有什么。先看表选一条，再往下抄命令。

先看这张表决定用哪个包管理器

把命令抄走

官方推荐的是安装脚本这一条：

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

不想用脚本，就用包管理器。下面这些命令按平台分组，只抄你需要的那一行：

# Node 生态（npm / bun / pnpm / yarn，四选一）
npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai
yarn global add opencode-ai

# Homebrew（macOS / Linux，官方 tap，更新最快）
brew install anomalyco/tap/opencode

# Arch Linux：稳定版 / AUR 最新版
sudo pacman -S opencode
paru -S opencode-bin

# Windows：Scoop / Chocolatey / NPM
scoop install opencode
choco install opencode
npm install -g opencode-ai

# Mise（统一管版本的工具）
mise use -g github:anomalyco/opencode

# Docker（一次性跑，用完即走）
docker run -it --rm ghcr.io/anomalyco/opencode

装完想升级、想卸掉

# 升到最新版
opencode upgrade

# 升到指定版本（注意官方文档里的示例写的是 v0.1.48 这种老版本号，格式一致）
opencode upgrade v0.1.48

# 指定安装方式来升级：curl / npm / pnpm / bun / brew
opencode upgrade --method brew

# 卸载：先看不删什么（--dry-run 只打印要删哪些东西）
opencode uninstall --dry-run

# 真的卸：保留配置、保留会话数据与快照、不再问确认
opencode uninstall --keep-config --keep-data --force

它把东西都放在哪

出问题时你基本只需要翻这三个位置，所以值得记一下：

桌面应用（Beta）：不想用终端的人

官方除了终端界面，也提供了桌面版。可以从下载页取安装包，也可以走包管理器：

# macOS（Homebrew cask）
brew install --cask opencode-desktop

# Windows（Scoop，注意要先进 extras 这个 bucket）
scoop bucket add extras; scoop install extras/opencode-desktop

安装包的下载页是 opencode.ai/download，提供 macOS、Windows、Linux 三个平台。桌面版目前官方标着 Beta，所以本文讲的配置与命令都以终端版为基准，桌面版的界面差异请以它自己的文档为准。

让 /editor 和 /export 用你惯用的编辑器

这两个命令都会去读 EDITOR 这个环境变量。不设它的话，打开的可能是一个你不想用的默认编辑器。

# 设置编辑器
export EDITOR="code --wait"   # VS Code
export EDITOR="cursor --wait" # Cursor
export EDITOR=nvim            # Neovim

# 想永久生效，把上面那行加进 shell 配置：~/.bashrc、~/.zshrc 等

# Windows 上不一样：CMD 用 set，PowerShell 用 $env:
set EDITOR=notepad
set EDITOR=code --wait
$env:EDITOR = "notepad"
$env:EDITOR = "code --wait"

04先接上一个模型

装完 OpenCode 之后，它还不能用——因为它自己没有模型。这一步做错或跳过，后面所有命令都会卡住。整个流程就三步。

三条命令之外没有别的坑

不想进界面也能做同样的事——命令行里也有一条：

# 交互式登录某个提供商（会问你要哪种登录方式、然后要 Key）
opencode auth login

# 直接指定提供商和登录方式，跳过两次选择
opencode auth login --provider anthropic --method api-key

# 看看现在已经接了哪些（这个命令不需要进界面）
opencode auth list
opencode auth ls

# 退掉某一家
opencode auth logout

不想折腾选模型，就用官方筛过的那一套

官方给新手的建议很直接：如果不知道选哪个模型，用 OpenCode Zen。它是 OpenCode 团队自己测过的模型集合，官方原话是"a curated list of models that have been tested and verified by the OpenCode team"（一份经过团队测试与验证的精选模型清单）。做法是：

# 1. 在 TUI 里敲 /connect
/connect

# 2. 在提供商列表里选 opencode

# 3. 浏览器打开下面这个地址，注册、绑支付方式、复制 API Key
#    https://opencode.ai/auth

# 4. 把 Key 粘回 TUI

# 5. 接完敲 /models，官方推荐的模型就在列表里
/models

把"接了哪几家"和"有哪些模型"查清楚

# 命令行里列出所有提供商提供、且你已配置的模型（格式是 provider/model）
opencode models

# 只看看 anthropic 家的
opencode models anthropic

# 模型清单是缓存的，刚上新模型时手动刷一下
opencode models --refresh

# 想看带价格、上下文长度这类元数据的版本
opencode models --verbose

输出里的 provider/model-id 就是你在配置里该写的那串字。举个例子：如果你用的是 Zen，想看 GPT 5.1 Codex，写的就是 opencode/gpt-5.1-codex 这个格式——斜杠前面是店家，后面是具体那个模型。

05最小例子：十分钟走完一遍

下面这一段是一条从头到尾能照着敲的路径：从一个真实项目到让 AI 改一个真实文件，最后再安全地撤回来。全流程只需要一个终端窗口。

第一步：进入项目并启动

cd /path/to/your/project
opencode

第二步：让它先读懂这个项目

/init

/init 会扫描仓库里的重要文件，必要时问你一两个它自己答不上来的问题，然后生成（或就地改进）一份 AGENTS.md。它重点记的是：构建 / 检查 / 测试命令、命令的执行顺序、从文件名看不出来的架构、项目特有的约定。

第三步：先问一个只读的问题

用 @ 引用文件是它最基本的动作。@ 会触发一次项目内的模糊搜索（你打几个字母它就把候选文件名列出来）：

给我这个项目的代码结构做一个快速总结
How is authentication handled in @src/auth.ts

文件内容会被自动读进对话里。所以问"这个函数做什么"这类问题，它答得比你自己翻文件快。

第四步：让它跑一次命令给你看

消息以 ! 开头，就表示"这条不是给模型的话，是要执行的 shell 命令"，输出会作为工具结果进入对话：

!git status
# 输出会被加入对话上下文，AI 能看到命令结果

更实用的写法是命令加问题一起来：

!git log --oneline -10
最近这 10 个提交里，哪个最可能跟"登录后偶发 500"有关？

第五步：要改代码，先切 Plan

按 Tab 或 Shift+Tab 在主代理之间切换（默认的两个是 Build 和 Plan，右下角会显示当前是哪个）。Plan 模式下"改文件"和"跑命令"默认都要问你，所以它只会给你方案：

# 1. 按 Tab 切到 Plan 模式
当用户删除笔记时，我们需要在数据库中标记为已删除。
然后创建一个页面显示最近删除的笔记，
用户可以从这个页面恢复或永久删除笔记。

# 2. AI 给出实现方案
# 3. 觉得可以，按 Tab 切回 Build 模式
看起来不错，开始实现吧。

第六步：撤回来看看

这一步强烈建议现在就试一次——知道"能撤"之后，你才敢放手让它改：

/undo
# 它会撤掉最近这条消息、以及它引起的所有文件和代码改动
# 然后把你刚才那句话重新显示出来，方便你改一改再发一次

/redo
# 反悔了：重做刚才撤销掉的那一批改动

第七步：长对话了把它压一压

/compact
# 把当前这一段长历史压成摘要，接着聊（别名 /summarize）

/new
# 或者干脆开一段新会话（别名 /clear）——任务换了一个主题时更推荐这个

完整的一套照抄版

如果你只想复制一整段，从装到撤回是这样的：

# 装（一次）
curl -fsSL https://opencode.ai/install | bash
opencode --version

# 接模型（一次）：进界面敲 /connect 并粘 Key
opencode

# 在项目里干活
cd /path/to/your/project
opencode

# 在 TUI 里依次敲：
#   /init                    生成 AGENTS.md
#   这个项目的入口在哪？     先问只读问题
#   !git status              让它看看工作区状态
#   Tab                      切到 Plan 出方案
#   Tab                      切回 Build 执行
#   /undo                    不满意就撤回
#   /exit                    走人（别名 /quit、/q）

06终端界面长什么样

OpenCode 的主界面就是一个「终端里的应用」。它复用了你终端的一部分能力（滚动、选中），又接管了一部分（键盘输入）。知道哪块归谁管，能省掉一次「我打了个字怎么没反应」的困惑。

两种启动方式

# 在当前目录启动
opencode

# 指定项目目录启动（不 cd 也能直接开）
opencode /path/to/project

四块区域，各管一件事

输入框里几个键，先认清它们

把界面调成你顺手的样子

界面相关的东西放在另一个文件里：tui.json（或带注释的 tui.jsonc）。它和管运行行为的 opencode.json 是分开的两份，可以放全局的 ~/.config/opencode/tui.json，也可以放项目里。

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "opencode",
  "leader_timeout": 2000,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "cursor": {
    "style": "block",
    "blinking": true
  },
  "mouse": true
}

三样东西跑在 TUI 之外，但你要知道它们在

# 浏览器界面：起一个本地服务并自动打开浏览器
opencode web
opencode web --port 4096

# 让局域网里别人也能连（注意：同时必须设访问密码，否则等于裸奔）
opencode web --hostname 0.0.0.0
OPENCODE_SERVER_PASSWORD=secret opencode web

# 只起后端、不给界面（给别的客户端用）
opencode serve

# 一台机器起后端，另一台机器把 TUI 接上去
opencode web --port 4096 --hostname 0.0.0.0
opencode attach http://10.20.30.40:4096

VS Code 里的扩展是怎么装上的

这里要纠正一个很常见的误解：你不需要先去装扩展。官方给的做法是——打开 VS Code，打开集成终端，在里面敲 opencode，扩展会自己装上。

# 在 VS Code / Cursor / Windsurf / VSCodium 的集成终端里敲：
opencode
# 之后扩展自动安装。装不上时按下面的三步查。

07第一次进项目先敲什么

上面那十分钟已经覆盖了主干。这一节补的是"能跑通之后，第一周真正会反复用的东西"——尤其是当你一次想干几件事的时候。

并行干活：同一份代码，几条会话同时开

每次 /new 都是一段独立会话。这带来一个很实用的用法：让一段会话去研究、另一段去实现，互不干扰。

# 会话 1：让它研究"认证是怎么做的"
# 会话 2：让它改一个完全无关的小 bug
# 用 /sessions 在它们之间来回切（别名 /resume、/continue）
/sessions

# 或者直接用命令行起一段新会话
opencode --continue              # 接着上一次
opencode --session <session-id> # 接指定的那一段
opencode --fork                  # 在续接时岔出一支，不污染原来那条线

不进交互界面也能问一句

这是它最被低估的一条能力——opencode run 把整个代理塞进一条命令里，跑完就退出：

opencode run "Explain how closures work in JavaScript"

# 挂到一个已经跑着的后端上，省掉每次冷启动 MCP 服务器的等待
opencode serve
opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

# 让它把结果按 JSON 吐出来，方便脚本解析
opencode run --format json "列出这个仓库里所有的 TODO 注释"

# 自动批准没有被显式禁止的权限（CI 里用，见 08）
opencode run --auto "Refactor this module"

对团队：分享、导出、交接

# 生成一个链接并复制到剪贴板
/share

# 取消分享
/unshare

# 导出成 Markdown，用你的默认编辑器打开
/export

# 命令行里：导出某段会话为 JSON（不给 id 会让你选）
opencode export
opencode export --sanitize   # 抹掉敏感内容再导出

# 把别人给你的会话 JSON 导进来（也支持分享链接）
opencode import session.json
opencode import https://opncd.ai/s/abc123

训练自己的肌肉记忆：五条就够

08斜杠命令与快捷键

在界面里敲 /，候选列表就出来了。这些叫斜杠命令——它们是"你控制这个工具"的开关，不是发给模型的提示词。下面按"你什么时候需要"分两张表。

十七个斜杠命令，一次列全

第三列是这套清单里哪一条会咬人，赶时间的话只看它。

没有斜杠版本的那些快捷键

下面这些只在键盘上。默认的前缀键是 Ctrl+X（表里写成 <leader>）。

把你每天重复说的话做成一条命令

斜杠命令列表里还可以有你自己的东西。做法有两种，先看 Markdown 文件那种——它最直观：

# 建这个文件（项目级）或 ~/.config/opencode/commands/test.md（全局级）
# .opencode/commands/test.md
---
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.

文件名 test.md 就成了命令名 test，敲 /test 就发出去。不想用文件，也可以全写在配置里：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

自定义命令里能塞三种动态内容

这是把"重复劳动"真正消掉的地方。三种写法可以混着用。

# 1. 参数占位：$ARGUMENTS 收全部参数，$1 $2 $3 收第几个
# .opencode/commands/component.md
---
description: Create a new component
---
Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing and basic structure.

# 用起来：/component Button  →  $ARGUMENTS 被换成 Button

# .opencode/commands/create-file.md
---
description: Create a new file with content
---
Create a file named $1 in the directory $2
with the following content: $3

# 用起来：/create-file config.json src "{ \"key\": \"value\" }"
#   →  $1 = config.json，$2 = src，$3 = { "key": "value" }

# 2. 把命令输出塞进提示词：用 !`命令` 这个写法
# .opencode/commands/analyze-coverage.md
---
description: Analyze test coverage
---
Here are the current test results:
!`npm test`
Based on these results, suggest improvements to increase coverage.

# .opencode/commands/review-changes.md
---
description: Review recent changes
---
Recent git commits:
!`git log --oneline -10`
Review these changes and suggest any improvements.

# 3. 引用文件：还是用 @
# .opencode/commands/review-component.md
---
description: Review component
---
Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

09模型、提供商和 Agent 是三件事

这是最容易混成一团的一组词，而且混了之后所有配置都写不对。一句话先分开：提供商是店家，模型是货，Agent 是"用哪件货、配哪些工具、说什么话"的一个组合。

用一张收货单理解这三层

官方对 small_model 的解释正好说明这三层是可以拆开配的：它专门给"起标题"这类小事配一个便宜模型，默认行为是"能从你的提供商那里找到更便宜的模型就用它，找不到就退回主模型"。

# 把主模型和"干杂活的模型"分开
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

同一家店还能调什么

调完店、调完货，还有一层"这家店怎么联系"的参数。它们在 provider.<名字>.options 里：

# 一家店的常见调法：超时、缓存键、换接口地址、藏掉不用的模型
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true,
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      },
      "blacklist": ["claude-opus-4-20250514"]
    }
  }
}

不想让某个提供商被自动加载

有时候你机器上有某个 Key，但你就是不想让这次的会话用它——比如公司要求只走指定的店。两个配置项管这件事：

# 明确禁掉几家（优先级更高）
{
  "disabled_providers": ["openai", "gemini"]
}

# 或者反过来：只允许这几家，其余全不加载
{
  "enabled_providers": ["anthropic", "openai"]
}

不确定该用哪个模型时

官方给的答案就是 OpenCode Zen，理由写在它自己的文档里：There are a large number of models out there but only a few of these models work well as coding agents.（模型很多，但真正适合当编程代理的只有少数。）而且同一件货在不同店家那里的表现也不一样，所以官方做了三件事：测了一批模型并与模型团队沟通怎么跑最好、和几家提供商一起确保服务方式正确、最后对"模型 + 提供商"这个组合做实测打分，得出一份可推荐的清单。

10别让它乱改：权限与自动模式

这是全文最该认真读的一节。官方在配置文档里写得很明白：By default, opencode allows all operations without requiring explicit approval.（默认情况下，OpenCode 允许所有操作，不需要明确批准。）也就是说——它一装上就是"什么都不问"的状态。不改它，你的第一周就是拿真实项目试手。

三种动作：放行、问你、禁止

先抄一份"能睡好觉"的配置

如果你只想抄一段就走，抄这个。它的思路是：读放开、写和跑命令要问、几类危险命令直接禁、密钥文件不许读。

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "npm test *": "allow",
      "git push *": "deny",
      "rm -rf *": "deny"
    }
  }
}

哪里能写、写了能不能被覆盖

可配的权限清单：十四个键

第三列告诉你"这个键为什么值得单独配"——多数人只需要动其中三四个。

细粒度规则：让"读能进去、改不能"

权限的值除了写一个动作，还可以写一个"模式 → 动作"的对象。中间支持的匹配规则很简单：* 匹配任意多个字符，? 匹配正好一个字符，其他字符按字面匹配。另外 ~ 和 $HOME 可以在开头代表你的主目录。

# 一个典型场景：只允许读某个目录，不允许改它
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

"ask" 弹出来之后，三个选项分别是什么

自动模式：批量放行，但禁掉的仍然禁掉

有些场合你不想被问（比如在 CI 里跑、或者你自己盯着屏幕），可以开自动模式：

# 启动时开
opencode --auto

# 非交互的一次性任务也支持
opencode run --auto "Refactor this module"

官方对它的边界说得很清楚：Explicit "deny" rules are still enforced. Auto mode only changes requests that would otherwise ask for approval.（显式写 "deny" 的规则照样执行；自动模式只改那些「本来会来问你」的请求。）在界面里也能切：按 Ctrl+P 打开命令面板，搜 "auto-approve" 就能开关；开着的时候，输入框旁边会有一个淡淡的 auto 提示。

三段可以直接抄的细粒度配置

前面讲的是规则，这里是三段真实可用的写法。它们的差别在于"你想拦到多细"。

# ① 全局两档：改要问、跑命令要问（最小可用）
{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

# ② 把 bash 拆开：默认问，几条读类命令放行，几条危险命令禁止
{
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git status *": "allow",
      "npm test": "allow",
      "npm test *": "allow",
      "git push": "deny",
      "git push *": "deny"
    }
  }
}

# ③ 按代理分开配：全局不许改，但 build 这个主代理例外
{
  "permission": { "edit": "deny" },
  "agent": {
    "build": {
      "permission": { "edit": "allow" }
    }
  }
}

# ④ 同一个思路，写在一个 Markdown 代理文件里（只读审查代理）
# ~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
Only analyze code and suggest changes.

最后这段值得多看一眼：它只放行了三条读类命令（git diff、以 git log 开头的、以及 grep 带参数的），其余 bash 一律要问、抓网页直接禁止。一个"只做审查、绝不改代码"的代理，配出来就是这么几行。

11@ 和 ! 什么时候用

消息框里有两个符号不是普通文字：@ 表示"去把项目里的文件喂给我看"，! 表示"这条先当命令跑掉"。这两个符号决定了它到底知不知道你在说什么，所以值得单独讲清。

@ 引用文件：它替你做了"复制粘贴文件内容"这件事

你在消息里打 @，它会在这个项目里做一次模糊搜索——你打几个字母，候选文件名就列出来了，选中即可。官方文档的说法是：The content of the file is added to the conversation automatically.（文件内容会被自动加进对话。）

这个函数的逻辑不太对，帮我看看 @src/utils/format.ts
# OpenCode 会自动读取文件内容并加入对话上下文

# 更具体的问法：把两个文件一起给它
我们需要给 /settings 路由加认证。
参考 @packages/functions/src/notes.ts 里的写法，
在 @packages/functions/src/settings.ts 里实现同样的逻辑。

! 前缀：让它的眼睛看到"现场"

以 ! 开头的整条消息会被当成 shell 命令执行，输出作为工具结果进入对话。官方的说法是 The output of the command is added to the conversation as a tool result——注意"工具结果"这个词，意味着它和它自己跑命令看到的东西是同一种东西。

!ls -la
!git log --oneline -10
!git diff HEAD~3

引用别名：把"隔壁仓库"也变成 @ 得出来的东西

项目里常有这种情况：真正要参考的文档在另一个仓库。references 就是为这个场景准备的——配一次别名，之后 @别名 即可。

# 完整写法：本地目录用 path，Git 仓库用 repository + 可选 branch
{
  "$schema": "https://opencode.ai/config.json",
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use for product behavior and documentation conventions"
    },
    "sdk": {
      "repository": "anomalyco/opencode-sdk-js",
      "branch": "main",
      "description": "Use for JavaScript SDK implementation details"
    }
  }
}

# 简写：不需要分支和描述时，直接写路径或仓库
{
  "references": {
    "docs": "../docs",
    "effect": "Effect-TS/effect"
  }
}

# 用起来：@别名 挂上整个根，@别名/ 继续往里搜文件
对比我们的配置和 @docs/README.md
对比一下我们的实现和 @sdk/src/client.ts

引用和权限是什么关系

这一条挺关键，因为它解释了"为什么我配了 @docs 就能读隔壁目录，而别的目录还是要问"：

• 配成引用的目录，OpenCode 会自动把它从"项目外路径"那道闸里放行；
• 但普通工具权限照样管用——官方举的例子是：一个不允许改文件的代理，不会因为某个目录被配成了引用就获得改动它的权限；
• Git 类型引用的拉取是异步的，刚配好时可能还在 clone，过一会儿才可用。

# 把引用藏起来，不污染 @ 补全列表（但仍然希望模型知道它存在 → 保留 description）
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true
    }
  }
}

12主代理与子代理

Agent（代理）这个词在 OpenCode 里指的不是模型，而是一套预设：用哪个模型、允许用哪些工具、系统提示词是什么、在界面上什么颜色。官方把内置的代理分两类：主代理（直接和你对话的）和子代理（被主代理派出去干专项活的）。

两类的差别只有一句话

五个内置代理，各管一段

除了这五个，还有三个"隐藏的系统代理"（compaction、title、summary），它们负责压缩上下文、起会话标题、写会话摘要，自动跑，你在界面上选不到。

怎么调用子代理

三条路，按你可能用到的顺序排：

# 1. 手动点名：在消息里 @ 它
@general help me search for this function

# 2. 自动：主代理按子代理的 description 自己决定派谁

# 3. 看它干的活：子代理会开自己的"子会话"
#    进入第一个子会话        <leader>+↓（默认 ctrl+x 然后方向键下）
#    在子会话之间轮换        →（右箭头）
#    反向轮换                ←（左箭头）
#    回到父会话              ↑（上箭头）

它手上到底有哪些工具

这是"权限表"的另一面。上一节讲的是"怎么拦"，这一张讲的是"它本来能干什么"。

# 联网搜索的两条开启方式（默认不满足前置条件时不出现这个工具）
OPENCODE_ENABLE_EXA=1 opencode
OPENCODE_ENABLE_PARALLEL=1 opencode

# LSP 工具是实验性的，要显式打开
OPENCODE_EXPERIMENTAL_LSP_TOOL=true opencode

!node_modules/
!dist/
!build/

自己造一个代理：两种写法

内置的五个不够用时，可以加自己的。JSON 那种适合"顺手改一下内置代理"，Markdown 那种适合"长期维护一个专用代理"。

# 写法一：写在配置里（opencode.json）
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "你是一个代码审查专家。关注安全性、性能和可维护性。",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

# 写法二：一个 Markdown 文件。放项目级或全局级：
#   .opencode/agents/review.md
#   ~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
permission:
  edit: deny
  bash: deny
---
You are in code review mode. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
Provide constructive feedback without making direct changes.

这是同一个机制做出来的第二个代理——一个安全审计用的子代理。它和上面那个只差在提示词和文件位置：

# .opencode/agents/security-auditor.md
---
description: 代码安全审计
mode: subagent
permission:
  edit: deny
---
你是一个安全专家。关注：
- 输入验证漏洞
- 认证和授权缺陷
- 数据暴露风险
- 依赖漏洞

文件的名字就是代理名：review.md 就创建了一个叫 review 的代理；security-auditor.md 就是 security-auditor。两者都被设成 mode: subagent、edit: deny，所以它们能看、能分析，但改不了你的代码——这正是"审查类代理"该有的形状。

一个代理能配哪些选项

# 用命令行交互式造一个新代理（想量产时把四个参数都给全，就变成非交互）
opencode agent create
opencode agent list

# 四个参数都给全时，它不再问你任何问题
opencode agent create --path .opencode/agents --description "审查 SQL 注入风险" --mode subagent --permissions read,grep,glob

13配置文件与优先级

OpenCode 的配置是多份合并的，不是"一份覆盖另一份"。官方原话：Configuration files are merged together, not replaced.（配置文件是合到一起的，不是替换关系。）明白这一点，才能解释"我明明改了全局配置怎么不生效"——因为项目里那份把它盖掉了。

八层优先级，从低到高

后面盖前面。你日常只会碰到中间三层，但知道有托管层存在，能解释"为什么这条配置我改不动"。

放配置的三条经验规则

• 项目根目录的 opencode.json 是最该用的一个：官方说明它启动时会从当前目录往上找到最近的 Git 目录；所以放在仓库根最稳，也建议提交进 Git。
• .opencode 和 ~/.config/opencode 里的子目录用复数名：agents/、commands/、modes/、plugins/、skills/、tools/、themes/。单数名（比如 agent/）也仍然能用，是为向后兼容留的——但新写就写复数。
• 想让配置跟着人走而不是跟着仓库走：放全局；总在没有 .git 的目录里手动跑时要知道，"往上找最近的 Git 目录"这一步会一路找到家目录为止。

常用配置项：一份能直接用的样例

下面这份把最常动的几项都放进去了，注释写在右侧。抄的时候记得删掉注释——或者干脆把文件命名成 opencode.jsonc，那种格式允许注释。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "formatter": true,
  "lsp": true,
  "permission": {
    "edit": "allow",
    "bash": "ask"
  },
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

其余常用项，按你的需求点菜

两个占位符，让配置不写死秘密

官方支持两种替换：{env:变量名} 取环境变量，{file:路径} 取文件内容。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

# 从文件里读密钥，避免把密钥写进配置文件
{
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

常被问到的几个环境变量

接一个 MCP 服务器：让模型多出几只手

MCP（Model Context Protocol，模型上下文协议）是"给模型接外部工具"的一套标准接口。接上之后，那个服务器提供的工具会和内置工具一样出现在模型手里。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
    },
    "my-local-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "my_env_var_value"
      }
    },
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

# 接上之后，在提示里直接点名那个服务器的工具
use the mcp_everything tool to add the number 3 and 4

# 命令行管 MCP：加、列、授权、退授权、排查
opencode mcp add
opencode mcp list
opencode mcp auth my-oauth-server
opencode mcp logout my-oauth-server
opencode mcp debug my-oauth-server

# 一个接数据库的例子（官方文档里的另一种写法：type 用 local，command 是数组）
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "database": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

# 想临时停掉某一个而不从配置里删：把它的 enabled 设成 false
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

# 需要手填客户端凭据时（服务器方给你的）
{
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"
      }
    }
  }
}

更多现成的 MCP 服务器怎么配，官方有一个单独页面：opencode.ai/docs/mcp-servers。想少装东西试一下，可以用官方文档里那个只提供一个加法工具的测试服务器 @modelcontextprotocol/server-everything。

# 1. 服务器选项（serve / web 共用）
{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

# 2. 自定义格式化器（保留内置的，只加/改某一个）
{
  "formatter": {
    "prettier": { "disabled": true },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": { "NODE_ENV": "development" },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

# 3. 只允许某些提供商使用（企业里常见的白名单写法）
{
  "experimental": {
    "policies": [
      { "effect": "deny", "action": "provider.use", "resource": "openai" }
    ]
  }
}

14AGENTS.md：写给 AI 的项目说明书

如果说 10 管的是"它能做什么"，这一节管的是"它知不知道该怎么做"。答案是：靠项目根目录那个叫 AGENTS.md 的文件。官方对它的定位是：里面的指令会被放进模型的上下文里，用来把它的行为调成适合你这个项目的样子。

/init 到底做了什么

不用手写。敲一条命令它就替你建：

/init

官方对它的描述值得逐句读，因为它决定了你该期待什么：它会扫一遍仓库里的重要文件、在代码本身答不上来时问你几个有针对性问题，然后创建或更新 AGENTS.md。它重点记的是这五类东西：

• 构建 / 检查 / 测试的命令；
• 命令的执行顺序、以及什么时候需要"只跑一小块验证"；
• 从文件名看不出真实意图的架构与仓库结构；
• 项目特有的约定、装环境的怪癖、运维上的坑；
• 对已有指令来源（比如 Cursor 或 Copilot 的规则文件）的引用。

一份可以照抄结构的 AGENTS.md

下面是官方文档里的示例。它的写法很克制——只写"命令 + 约定 + 结构"，不写状态、不写历史。这个取舍值得学：这份文件每次会话都会被读进去，写多了等于每次都在多花你的上下文预算。

# SST v3 Monorepo Project
This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
## Project Structure
- `packages/` - Contains all workspace packages (functions, core, web, etc.)
- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
- `sst.config.ts` - Main SST configuration with dynamic imports
## Code Standards
- Use TypeScript with strict mode enabled
- Shared code goes in `packages/core/` with proper exports configuration
- Functions go in `packages/functions/`
- Infrastructure should be split into logical files in `infra/`
## Monorepo Conventions
- Import shared modules using workspace names: `@my-app/core/example`

放哪一份、哪一份说了算

不想要 Claude Code 那套兼容，就关掉

# 完全关掉对 .claude 的读取（提示词 + 技能）
export OPENCODE_DISABLE_CLAUDE_CODE=1

# 只关 ~/.claude/CLAUDE.md 这份提示词
export OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1

# 只关 .claude/skills 里的技能
export OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1

规则文件不止一份时，用 instructions 汇总

很多项目已经有自己的规范文档（CONTRIBUTING.md、.cursor/rules/……）。与其把它们复制进 AGENTS.md，不如让 OpenCode 直接去读：

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

它和 Plan 模式不是一回事

这两个是新手最容易混的一对，因为它们都"让 AI 更懂规矩"，但管的是完全不同的两件事：

15六个真实场景

前面讲的是零件。这一节把零件拼成六件真事，每一件都给一段能直接抄进去的话。注意每段的写法有共同点：都给上下文（@文件）、都给验收标准（"加测试""只看失败的"），最后一件还先自己把现场贴进去（!命令）。

先按你的任务挑一个

场景一：理解陌生代码库

别一上来就"给我讲讲这个项目"——那样你得到的是一篇概括。更有效的做法是先要一张地图，再按块追问。

给我这个项目的整体架构做一个总结
重点关注 @src/api/ 目录下的路由设计

如果 @src/api/ 这种目录级引用让它一次读太多文件，就换成"先列文件、再逐个问"：

先列出 @src/api/ 下面所有的路由文件，不要读内容。
然后告诉我哪个文件负责处理用户登录。

场景二：加一个新功能

先用 Plan 出方案，确认后再切 Build。这是整套用法里最省返工的一步。

# 1. 按 Tab 切到 Plan 模式，然后说需求
我想给用户系统加一个"最近登录时间"字段。
先分析一下需要改哪些文件，给我一个方案。

# 2. 看方案、提意见（这一步不要跳）
数据库迁移你打算怎么做？线上已经有数据了，不能停机。

# 3. 按 Tab 切回 Build，再让它动手
方案看起来不错，开始实现吧。

场景三：修一个具体的 bug

这个场景的关键是：把"能复现的现象"说出来，而不是只说"有 bug"。前者能让它验证自己的修复，后者只能让它猜。

@src/utils/auth.ts 里的 login 函数有问题，
用户输入空密码时不会报错。帮我修复并加上测试。

# 更好的版本：把复现步骤也给出来
@src/utils/auth.ts 的 login 函数在 password 传空字符串时返回成功。
我在 @src/utils/auth.test.ts 里加了这条用例但它失败了：
!npm test -- auth.test.ts
先看失败信息，再修 login，不要改测试。

场景四：代码重构

重构最容易失控，因为它涉及的文件多。先小范围试跑是这里唯一值得记住的技巧。

帮我把 @src/components/ 里的 class 组件
全部重构成 functional component + hooks

# 更稳的做法：先让它在一个文件上证明它理解了模式
先只改 @src/components/UserCard.tsx 这一个文件，
按 functional component + hooks 重写一遍，其他文件先别动。
改完告诉我你做了哪几处等价变换。

场景五：写测试

给 @src/services/api.ts 写单元测试，
覆盖正常流程和错误场景

想让它写得像你团队的样子，就把现有的测试文件也引用上——一个例子顶十句描述：

给 @src/services/api.ts 写单元测试。
格式和断言风格参考 @src/services/user.test.ts，
要覆盖正常流程、网络错误、以及返回空数据三种情况。

场景六：审查最近的改动

这一类最值得用 ! 前缀：你自己先把现场贴进去，它就不用猜"最近"是哪几次。

审查一下最近的改动，关注安全性和性能问题
!git diff HEAD~3

如果改动很多、你又只想看有风险的部分：

!git diff HEAD~3 --stat
上面这些文件里，只挑涉及认证和数据库查询的改动来审。
每条问题按"文件:行 · 问题 · 为什么危险 · 怎么改"列出来。

16十个最常见的坑

下面这些是真实会撞上的。前三类是"刚装完"的坑，中间是"用起来"的坑，最后两条是"你以为配好了其实没有"的坑——那两条不发脾气、不报错，最危险。

第一类：装完就卡住

第二类：接不上模型

第三类：用起来不对劲

最后两条：没有报错，但已经在出血

# ❌ 反了：git push 会命中后面那条 "*"，结果所有命令都是 ask
"bash": { "git push *": "deny", "*": "ask" }

# ✅ 对了：把兜底的 "*" 放前面，具体规则放后面
"bash": { "*": "ask", "git status *": "allow", "git push *": "deny" }

排错：先跑这三条命令

出问题时不要凭感觉猜，先把机器上的事实读出来。这三条覆盖了绝大多数情况：

# 1. 版本对不对（也是确认 PATH 通不通）
opencode --version

# 2. 到底接了哪几家提供商
opencode auth list

# 3. 当前这份配置最终解析成了什么（能看出哪一层盖掉了哪一层）
opencode debug config

# 附：想看它把请求发去哪、报了什么，就把日志级别压到 DEBUG
opencode --print-logs --log-level DEBUG

# 附：怀疑是插件在捣乱时，用"纯净模式"跑一次（不加载外部插件）
opencode --pure

17成对示例：同一件事的两种问法

同一件事，两种说法，结果的差距通常不是"它聪明不聪明"，而是你有没有把它需要的东西放到它面前。下面四对都是可以直接对照的。

第一对：修一个 bug

帮我修复这个 bug

@src/auth.ts 的 login 函数在空密码时不报错。
!npm test -- auth.test.ts
先看失败信息，再改 login，不要改测试。

第二对：让它改代码但别乱改

把这个项目里的 class 组件都改成函数组件

先只改 @src/components/UserCard.tsx 这一个文件，
按函数组件 + hooks 重写，其他文件先别动。
改完告诉我你做了哪几处等价变换。

第三对：问它"为什么"

我的构建为什么这么慢？

!npm run build --profile
上面是我们项目的构建输出，最慢的三步是哪些？
只分析这三个，不要重写构建配置。

第四对：权限

# 什么也不配 = 所有操作都不问就执行
# 它可能直接跑 git push、跑迁移脚本

{
  "permission": {
    "*": "ask",
    "read": "allow",
    "bash": {
      "*": "ask",
      "git push *": "deny"
    }
  }
}

把好写法归纳成一张模板

四对看下来，会发现"好"的那一栏总是同四样东西。它不是提示词工程，就是把任务说清楚的常识：

18什么时候别用它

这一节不属于开头（开头该给的是"怎么用"），但它确实该存在——因为它决定你会不会在错误的地方浪费一周。

五件它不适合的事

它和"直接问模型"的分工

这一条能帮你省订阅费，也能帮你省时间：

19术语对照表

下面这十七个词在文中反复出现。第三列不是翻译，是"它在整套体系里为什么重要、以及别拿它当什么用"——同一个词用错地方，往往就是一次配置事故。

20一页纸速查

这一节是留给你第二遍回来查的。不需要从头读。

装完到用顺：一份检查清单

按"我想做什么"查

第三列写清"在哪儿敲"，因为其中有几条不是敲在 OpenCode 的输入框里的。

四份配置模板，按需抄

下面四段覆盖了绝大多数人的实际需求。第一段是最该抄的那一份。

# ① 最小安全配置：读放开、改和跑命令要问、推代码直接禁
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow",
    "bash": {
      "*": "ask",
      "git status *": "allow",
      "git push *": "deny"
    }
  }
}

# ② 主模型 + 杂活模型分开，密钥走环境变量
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }
    }
  }
}

# ③ 一个只读的子代理（审查用，永远不改文件）
# 存成 ~/.config/opencode/agents/review.md，或用 /review 点名它
---
description: Reviews code for quality and best practices
mode: subagent
permission:
  edit: deny
  bash: ask
---
You are in code review mode. Focus on code quality, edge cases,
performance, and security. Provide feedback without direct changes.

# ④ 一条自定义命令：把"跑测试 + 只看失败 + 给建议"压成一个词
# 存成 .opencode/commands/test.md，然后敲 /test
---
description: Run tests with coverage
agent: build
---
Here are the current test results:
!`npm test`
Focus on the failing tests and suggest fixes.

99一句话总结

98参考来源与证据边界

来源清单

本文的每条事实都对着下面这些一手来源核过。日期栏写的是抓取时页面上标注的"最后更新"或接口返回的时间。

证据边界：哪些地方我核不到一手来源

• 「16M+ 月活跃开发者」这类使用量数字没有来源。它在网上流传，但官方文档和仓库都不提供这个口径。本文因此没有把它当作事实写进正文，hero 里的四个数字全部改成了能从 GitHub / npm 接口直接复核的量。
• 贡献者数量在不同口径下差一倍以上。GitHub 贡献者接口按每页 100 条返回时，最后一页是第 5 页，也就是约 401–500 人；而按每页 1 条返回时最后一页是第 456 页，也就是 456 人。两个数字都对，区别是接口把匿名与合并后提交者的计法。本文取的是"每页 100 条、共 5 页"这个口径，写成 401，并在 hero 里标注了这是 GitHub 计数。旧版本写的「950+ 贡献者」在两种口径下都对不上，见下面的修订清单。
• 「13K+ 代码提交」也已过期。按默认分支 dev 的提交接口读，最后一页是第 15717 页（每页 1 条），所以是约 15,717 次提交。
• 斜杠命令清单取自文档，而不是运行中的程序。我核对的是 docs/tui 页面上的命令列表，没有在本机装一份去逐条敲。如果你装的版本里 /themes 之类不存在了，以你的实际界面为准——这类清单在上游是会更新的。
• 截图与界面布局描述来自文档文字，不是截图。文档没有配图，所以"顶部/中部/底部/右下角"这四块是依据文档对界面元素的叙述改写的；不同版本的外观细节可能不同。
• MCP 的 type 取值变化只找到文档层面的证据。旧版本里写 "type": "stdio"，现在文档只列 local 与 remote，且旧的 tools 配置被明确标为废弃。我没有找到"stdio 从哪个版本开始不再接受"的变更记录，所以正文只说"旧教程里的写法和现在的取值不一样"，没有断言它到底还能不能用。

时效说明

本文的档案是 tool、时效标记是 evolving（演进型），校对日期 2026-09-13，版本锚点是 anomalyco/opencode v1.18.30（2026-09-09 发布）。这个项目迭代很快——光是在我核对的那一天，默认分支就有新提交。所以下面这几类内容最可能先过期，请以官方源为准：

• 斜杠命令清单与键位：命令会增删，别名会变（/compact 的别名 /summarize、/sessions 的别名 /resume、/continue 就是这类变化的结果）。
• 内置代理与内置工具清单：官方文档里已经有多个工具带"实验性"标注（lsp、websearch 的开关方式），这类功能最容易变。
• 配置项的默认值：比如权限默认值、subagent_depth 的默认层数、MCP 超时的 5000 毫秒。默认值一变，文中"默认是……"那几句就过期。
• 版本号与仓库数字：hero 里的四个数字、以及正文里的 1.18.30，都是 2026-09-12/13 的快照。

# 1. 版本锚点是不是真的
curl -sSL https://registry.npmjs.org/opencode-ai/latest | python3 -c "import json,sys;print(json.load(sys.stdin)['version'])"

# 2. hero 里的仓库数字
curl -sSL https://api.github.com/repositories/975734319 | python3 -c "import json,sys;d=json.load(sys.stdin);print(d['full_name'],d['stargazers_count'],d['license']['spdx_id'])"

# 3. 斜杠命令清单的原页面
curl -sSL https://opencode.ai/docs/tui/ | grep -o '/themes' | head -1