OpenCode：开源、能换任意模型的
编码 Agent

01

它是什么：不锁在任何一家模型上的终端 Agent

OpenCode 是一个开源的 AI 编码 Agent，主战场是终端：进入项目目录敲 opencode，就得到一个能读代码、改文件、跑命令、回答问题的全屏 TUI。它的卖点和 Claude Code、Codex 这类「绑定自家模型」的工具正好相反——模型只是插件，Anthropic、OpenAI、Google、DeepSeek、本地 Ollama 都能接，用 /models 随时换。

它由 SST 团队开发（该团队现已更名 Anomaly），代码在 GitHub 上完全公开，迭代速度极快：从 2025 年 5 月的 v0.x 一路演进到今天的 2.x 大版本，还提供了桌面应用和 IDE 扩展——但终端 TUI 始终是文档最完整、能力最全的主入口。

和同类工具比，它的差异点可以浓缩成三个词：开源（代码可审、生态共建）、模型无关（模型目录接在 models.dev 上，75+ 家 provider 随换）、约定通用（AGENTS.md、MCP、Agent Skills 等开放标准它都认）。如果你想在「工具能力」和「模型选择」两个维度上分开做决定，它就是为此而生的。

开发团队

SST（现已更名 Anomaly）

代码仓库

github.com/anomalyco/opencode（原 sst/opencode）

软件形态

终端 TUI / 桌面应用 / IDE 扩展

模型接入

任意 provider，含本地 Ollama

npm 包名

opencode-ai（不是 opencode）

配置目录

~/.config/opencode/

项目规则文件

AGENTS.md（/init 自动生成）

当前大版本

2.x（与 1.x 不能并存）

02

安装：脚本、npm、包管理器，三选一

推荐官方脚本——下载独立二进制、无需 Node.js。全平台通用；Windows 用户官方文档建议优先用 WSL，纯 Windows 也可以走 Chocolatey / Scoop。

# macOS / Linux / WSL：下载二进制 + 安装，无需 Node
curl -fsSL https://opencode.ai/install | bash

# 装完重开一个终端，确认进 PATH 了
opencode --version

# 注意：包名是 opencode-ai，不是 opencode
npm install -g opencode-ai

# Bun / pnpm / Yarn 同理
bun install -g opencode-ai
pnpm install -g opencode-ai

opencode --version

# macOS / Linux（Homebrew，官方 tap）
brew install anomalyco/tap/opencode

# Windows（Chocolatey / Scoop）
choco install opencode
scoop install opencode

# 也可以直接跑 Docker 镜像
docker run -it --rm ghcr.io/anomalyco/opencode

03

快速上手：五分钟跑通第一问

OpenCode 的能力边界跟着工作目录走：在哪个目录启动，它默认就只能看到那个目录里的东西。所以第一戒律和所有终端 Agent 一样——先 cd 进仓库，再启动。

# 1. 进项目，启动 TUI
cd ~/your-project
opencode

# 2. 首次使用：接一个模型 provider（选厂商、贴 API Key）
> /connect

# 3. 提第一个问题，@ 可以模糊搜索并引用文件
> 解释一下 @src/main.go 的启动流程

# 4. 改坏了随时撤：撤销上一条消息和它产生的文件改动
> /undo

• 01

  接模型：/connect 或命令行 auth

  在 TUI 里 /connect 选厂商贴 Key；不想进 TUI 也可以直接 opencode auth login。凭证存本机，之后所有会话共用。

• 02

  先用只读任务试水

  「解释这个模块」「画出调用关系」这类请求不写文件，适合拿来验证模型接通了、上下文装得下你的仓库。

• 03

  用 @ 引文件、用 ! 跑命令

  输入 @ 会弹出文件模糊搜索；消息前加 !（如 !ls -la）直接执行 shell 并把输出交给模型。这两个符号是最常用的效率开关。

• 04

  记住 Tab 和 /undo

  Tab 在 Build / Plan 两种模式间切换（先规划再动手）；/undo 撤掉上一轮消息与文件改动，/redo 找回来。这两个保命键依赖 Git，见第 07 节。

04

核心概念：Agent、规则、模型、权限四件套

主代理与子代理：Build、Plan、general、explore

OpenCode 里的「Agent」是一套可配置的提示词 + 工具权限 + 模型组合。内置两个主代理：Build（全工具，直接干活）和 Plan（默认禁止改文件，先出计划），用 Tab 切换。另有内置子代理 general（全权干杂活）和 explore（只读探索）——主代理会按任务自动派活，你也可以用 @general 帮我…… 手动点名。

子代理默认只能由主代理派起（subagent_depth 默认 1，不许套娃）；要让它「只干活不上菜单」，配置里加 hidden: true；要整个关掉某个 Agent，用 disable: true。这套开关让「谁能干什么」变成仓库里看得见的配置，而不是口头约定。

AGENTS.md：把项目约定写进仓库

第一次在仓库里跑 /init，它会扫描代码库并在项目根生成 AGENTS.md——构建命令、代码风格、目录结构都写在这份文件里，每次会话自动加载，建议提交进 Git。它的加载规则很宽厚：向上逐级找 AGENTS.md；没有才回退读 CLAUDE.md；个人全局规则放 ~/.config/opencode/AGENTS.md。这就是 AGENTS.md 开放标准的好处——约定写一份，Claude Code、Codex、OpenCode 都认。

模型无关：一个命令接一家 provider

# 命令行登录 provider（也可用 TUI 里的 /connect）
opencode auth login
opencode auth list        # 看已配置的凭证

# 列出可用模型；--refresh 从 models.dev 刷新缓存
opencode models
opencode models anthropic

# 临时指定模型跑一条命令
opencode run --model google/gemini-2.5-pro "总结这个仓库的技术栈"

# TUI 里随时换模型
> /models

想写死默认模型，在配置里加 "model": "anthropic/claude-sonnet-4-5"；轻量任务（起标题、做摘要）走 small_model。本地模型一样是 provider：起好 Ollama，opencode auth login 里选 ollama 即可。

权限与 MCP：问、放行、拒绝三档

权限用 permission 键控制，值为 ask（默认弹审批）、allow（放行）、deny（拒绝），可以按工具名配，也可以用通配符精确到某条 shell 命令。外部系统能力走 MCP：配置里的 "mcp" 键声明服务器，或命令行 opencode mcp add 接入，接入后的工具名以 mymcp_ 前缀出现，权限照样能对它下通配符。

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

05

速查表：装完就靠这张表

下面这块表格能搜。忘了某个命令叫什么，直接搜 会话、模型、撤销 之类的词。

06

实战：把 OpenCode 培养成你仓库的成员

裸装的 OpenCode 是个通才。按下面四步做完，它就带上了你仓库的记忆、你的审查标准和你自己的快捷命令——这一套做完大概 20 分钟。

第一步：生成并打磨 AGENTS.md

cd ~/your-project
git status          # 确认工作区干净，改动可回滚
opencode

> /init
# 它会扫仓库、写 AGENTS.md，你人工补两段：
#   1. 构建与测试命令（npm test / go test ./...）
#   2. 团队红线（不许动 migrations/、提交信息格式）
git add AGENTS.md && git commit -m "docs: add AGENTS.md for AI agents"

第二步：加一个 review 子代理

子代理用 Markdown 定义，文件名即 Agent 名。在项目根建 .opencode/agents/review.md：

---
description: 审查当前改动，输出问题清单，不改任何文件
mode: subagent
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

你是资深代码审查者。审查当前 git diff：

1. 先按严重度分组：bug / 安全 / 风格
2. 每条问题给出文件、行号、修法
3. 不改任何文件，只输出清单
4. 最后用一句话给出「可合并 / 需修改」结论

关键在 permission：把 edit 和 bash 都设为 deny，它就只能读只能想——审查者不该动手改代码。之后主代理会按 description 自动派活，你也可以 @review 看一下刚才的改动 手动点名。

第三步：把常用流程做成自定义命令

在 .opencode/commands/ 下放一个 Markdown 文件，文件名就是斜杠命令：

---
description: 跑测试、修失败用例，直到全绿
agent: build
---

1. 运行测试命令并收集失败用例
2. 逐个分析失败原因，最小化修复，不顺手重构
3. 再跑一遍，直到全部通过
4. 输出：改了哪些文件、为什么改

$ARGUMENTS

存盘后在 TUI 里敲 /fix-tests 只看 unit 目录——$ARGUMENTS 会替换成你附带的说明。

第四步：非交互接进脚本与 CI

# 单发任务：审查未提交改动，结果存档
opencode run --agent review "审查当前工作区改动" | tee review.md

# JSON 事件流，喂给脚本或日志管道
opencode run --format json "把 CHANGELOG.md 更新到最新版本"

# 查看本周用量，确认没跑飞
opencode stats --days 7

第五步（可选）：接上 GitHub，让它守 PR

# 安装 GitHub 集成（含给仓库配 Action）
opencode github install

# 之后可以在 issue / PR 评论里让它干活：
#   @opencode 帮我看看这个 PR 有没有漏掉迁移脚本
# 手动触发一次集成运行：
opencode github run

这一步把 OpenCode 从本地工具升级成团队的异步成员：PR 里的评论就是任务，改完的代码回到分支里等你 review。权限依然走配置里的 permission 键，CI 里尤其要先收紧再放开。

07

避坑与常见问题：四个最常见的坎

坑一：opencode: command not found

九成是 PATH 问题。脚本装的二进制在用户 bin 目录，新装的路径往往要重开终端才生效；npm 装的则是全局 bin 目录不在 PATH。

which opencode                      # 有输出说明 PATH 正常
echo $PATH | tr ':' '\n' | grep -iE 'opencode|npm|homebrew'

# 临时验证：直接用绝对路径跑
~/.opencode/bin/opencode --version

坑二：装错了包 / 装错了仓库

# 错：npm i -g opencode（这不是本工具）
npm uninstall -g opencode
# 对：
npm install -g opencode-ai

# Homebrew 用官方 tap 全名
brew install anomalyco/tap/opencode

顺带一提：OpenCode 1.x 和 2.x 用的是同一个 opencode 命令，两者不能并存。从 1.x 升 2.x 前先看一眼官方 changelog，别在半路混装。

坑三：/undo 没反应或撤不干净

坑四：权限全开后跑飞了

有 --auto 参数可以把未明确禁止的权限全部自动放行，方便但危险。在陌生仓库、有未提交改动、或目录里躺着生产密钥时，别用。更稳的做法是把红线写进配置：

{
  "permission": {
    "bash": {
      "rm -rf *": "deny",
      "git push*": "ask",
      "curl * | sh": "deny"
    }
  }
}

08

进阶方向与资源

• OpenCode 官方文档——安装、配置、Agent、权限的权威来源，先通读 Getting Started。
• GitHub 仓库 anomalyco/opencode——原 sst/opencode；看 README、提 issue、读源码都在这里。
• 官方 Changelog——版本迭代极快，升级前扫一眼新特性与破坏性变更。
• Agents 文档——主代理、子代理、权限细粒度配置的完整说明，本页 s6 的展开版。
• Config 文档——opencode.json 全部键位说明，含企业托管配置。
• models.dev——OpenCode 的模型目录来源，各家 provider 与定价一目了然。
• Permissions 文档——ask / allow / deny 的完整规则与通配符写法。

09

收尾：照着勾一遍

0 / 5