opencode 上手：模型无关的终端编程助手，和它的三个必改配置

一句话总结：OpenCode 是一个开源的终端 AI 编程助手，和 Claude Code 用法相近但模型无关——接哪家、用哪个模型全由 opencode.json 决定，配合自带的 Zen 中转或任意 OpenAI 兼容端点都能跑；真正决定它好不好用的不是安装，是三处配置：provider 定义、AGENTS.md、以及默认模型的工具调用能力。

Claude Code 好用，但有两个绕不过去的问题：只能用一家的模型，以及按订阅付费在重度使用时不够灵活。

opencode 走的是反面：开源、单二进制、模型随便接。代价是配置要自己动手，而且它的「模型无关」有前提——你接的模型得会调工具，否则这个编程助手退化成聊天框。

这篇按「装上 → 接通模型 → 初始化项目 → 日常用法 → 三个扩展」的顺序写。

装上：三行命令选一个

# 通用安装脚本（macOS / Linux）
cuRL -fsSL https://opencode.ai/install | bash

# 有 Node 环境
npm install -g opencode-ai

# macOS / Linux 用 Homebrew
brew install anomalyco/tap/opencode

Windows 上两个选择：choco install opencode 或 scoop install opencode，但官方推荐在 WSL 里跑——TUI 的终端能力和文件监听在原生 Windows 下有些边角问题，这个建议值得听。

装完 opencode --veRSIon 验证一下。

接通模型：两条路

第一条：用 OpenCode Zen（最省事）。 在 TUI 里敲 /connect，选 opencode，浏览器会跳到认证页，登录、绑卡、拿 key，粘回去就完事。Zen 是团队筛过的一批模型，省掉自己比对兼容性的功夫。

第二条：接你自己的 provider。 在项目根目录建 opencode.json，或者放到 ~/.config/opencode/opencode.json 让全局生效：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My Provider",
      "options": {
        "baseURL": "https://API.example.com/v1",
        "apiKey": "{env:MY_PROVIDER_KEY}"
      },
      "models": {
        "my-model-v1": {
          "name": "my-model-v1",
          "liMIT": { "context": 128000, "output": 32000 }
        }
      }
    }
  },
  "model": "myprovider/my-model-v1"
}

三个字段值得解释，因为它们决定了「能不能用」：

npm: "@ai-sdk/openai-compatible" 告诉 opencode 用哪套协议适配器。绝大多数国内外的 OpenAI 兼容端点都用这个。

{env:MY_PROVIDER_KEY} 从环境变量读 key，不要把明文写进配置文件——这个文件是要提交到 git 的。

limit.context 和 limit.output 是元数据，opencode 靠它决定什么时候压缩上下文、单次最多要多少输出。填错会导致要么频繁截断、要么请求被服务端拒绝。

填完之后 opencode 启动，/models 切换，/connect 里选 Other 输入 provider id 完成认证。

初始化：AgentS.md 是这个工具的记忆

进项目目录敲 opencode，第一件事是 /init。

它会扫一遍代码库，在根目录生成 AGENTS.md，里面写了项目结构、技术栈、命名约定、常用的构建和测试命令。

这个文件要提交到 git。 因为它每次会话开场都会被读进去，等于给模型一份常驻的项目说明。没它的话，你得每次重复「这个项目用 pnpm 不用 npm」「测试跑 pnpm test:unit」这类话。

和 Claude Code 的 CLAUDE.md 是同一套逻辑。顺带提醒：既然它会被自动读取并执行，那它也是一个攻击面，编码智能体投毒那篇讲的问题在这里同样成立——别人仓库里的 AGENTS.md 不要盲信。

图 1：安装、provider 配置、AGENTS.md 三层，后两层决定好不好用

日常：六个真正常用的操作

Tab 切 Plan/Build 这个设计值得单独说：Plan 模式下它只读不写，适合让它先把方案说清楚，你确认了再让它动手。比「直接改完再回滚」省事得多，尤其在陌生代码库里。

三个扩展，按性价比排序

自定义 agent。 用 markdown 定义角色，比如一个只做 review 的、一个只写测试的：

---
description: 代码审查，只看不改
mode: subagent
---
你是一个严格的代码审查者。检查：空指针、边界条件、错误处理、命名一致性。
输出问题清单，按严重程度排序，不要直接改代码。

放在约定目录里，然后从 agent 切换器选用。好处是把「审查」这个动作从对话里固化下来，不用每次重复要求。

MCP 服务器。 一行配置接数据库、浏览器或内部 API。和 Claude Code 的 MCP 配置思路一致，站里写 MCP 服务器那篇可以对照。

自定义 slash 命令。 把重复的提示词模板变成 /deploy-check 这样的命令，带参数。

还有个容易被忽略的能力：opencode serve 会把 opencode 以 HTTP 服务形式暴露出来，可以给自己的工具链调用。这个用法超出了「终端助手」的范畴，更像一个可编程的 Agent 后端。

五个坑，按命中率排

坑 1：接了不会调工具的模型。 opencode 的核心是工具调用循环（读文件、改文件、跑命令）。模型不支持 Function Calling，它就只能聊天，改不了代码。接之前先确认这个模型在工具调用榜单上有成绩，别看参数量。

坑 2：limit.context 填大了。 填 1M 但服务端实际只给 128K，会在长对话里突然报错。按服务商的真实上限填，宁可保守。

坑 3：key 写进 opencode.json。 这个文件通常要提交。用 {env:VAR} 从环境变量读，或者只放在全局配置 ~/.config/opencode/opencode.json 里（不进仓库）。

坑 4：不提交 AGENTS.md。 换了机器或换了同事，每次会话都要重新解释项目。提交它，团队共享。

坑 5：在 Windows 原生终端硬扛。 官方推荐 WSL 不是客套。TUI 的重绘、文件监听、路径分隔符在原生 Windows 下都有边角问题，折腾这些的时间够装个 WSL 了。

和桌面客户端怎么选

站里做过桌面 AI 客户端横评，那是 GUI 路线（Cherry Studio、LobeChat、Open WebUI）。opencode 是终端路线，两者的分工其实很清楚：

• 要改代码、跑命令、接进开发流程：终端 Agent 更顺，它的工具集就是为这个设计的
• 要多模型对比、知识库问答、日常对话：GUI 客户端更舒服

不是替代关系。我现在是两个都开着，写代码用终端，查资料和试新模型用桌面端。

边界

opencode 解决的是「自由选择模型」，不解决「模型够不够强」。同一个任务，它接 Opus 和接一个 7B 本地模型的产出质量差好几个档次——自由度换来的责任在你自己身上。

另外提醒一句：它是 MIT 开源的，意味着可以审计、可以改、可以自托管。如果你在企业环境用，这个「可审计」本身就是价值，比功能多一个少一个重要得多。

参考资料

• opencode 官方文档 - 安装、provider 配置与 TUI 操作
• opencode GitHub 仓库 - 源码、issue 与发布版本
• Models.dev - provider 与模型清单，配置字段参考