01 · OpenCode 是什么

你已经听过 Claude Code，也可能用过 Codex。现在又来了一个 OpenCode，第一反应很自然：是不是又一个"能在终端里写代码的 AI"？

这个判断只对了一半。OpenCode 确实是 AI coding agent（AI 编程代理），但它最重要的不是"又能写代码"，而是把开源实现、终端 TUI（Terminal UI 文本界面）、多模型供应商、项目级配置和运行时扩展放在同一个体系里。理解了这个定位，你才知道它该放在工作流的哪个位置。

1. 一个真实选择题

假设你现在维护一个 Next.js 项目，想引入 AI agent 帮你做三件事：

1. 平时解释代码、改小 bug、跑测试。
2. 给不同任务配不同模型，避免所有事情都用最贵模型。
3. 把项目规则、review 流程、专用 agent 和工具配置一起放进仓库。

Claude Code 可以很顺手，Codex 也可以很强。但如果你特别在意“配置能不能版本化、模型供应商能不能替换、运行时能不能扩展、源码能不能审计”，OpenCode 就开始变得有意义。

这不是“谁替代谁”的问题，而是“你要哪一种控制面”的问题。

2. OpenCode 的一句话定位

OpenCode 官方把它定义为 open source AI coding agent。它可以通过终端界面使用，也提供桌面应用和 IDE 扩展；官方文档还覆盖 CLI、Web、SDK、server（HTTP 服务模式）、GitHub/GitLab 集成、ACP（Agent Client Protocol，让编辑器和 AI agent 用统一协议通信，配 Zed/JetBrains/Neovim 等编辑器）、MCP（Model Context Protocol，把外部系统/工具变成 agent 可调用工具的标准协议）、LSP（Language Server Protocol，编辑器拿代码诊断、跳定义、找引用的协议）、permissions、skills 和 plugins。

这一段术语很多，不必现在全懂——下面 7 篇会按入口、上下文、执行、角色、模型、治理 6 层分别展开，每个术语都会在它真正起作用的篇里讲清"为什么需要它"。

用中文开发者更容易理解的话说：

OpenCode 是一个开源、终端优先、多模型可换、配置开放的 AI 编程 agent 运行时。

这句话里有四个关键词。

3. 先看它长在哪个位置

很多 AI 编程工具的差异，不在模型，而在“AI 住在哪里、能碰到什么、由谁控制”。

OpenCode 的基本形状可以这样看：

flowchart TD
    User["开发者"] --> Entry["入口层：TUI / CLI / IDE / Desktop / Web"]
    Entry --> Context["上下文层：AGENTS.md / rules / @file / session"]
    Context --> Agent["Agent 层：commands / agents / skills"]
    Agent --> Tools["执行层：read / edit / bash / LSP / MCP / formatter"]
    Agent --> Model["模型层：provider / model / small_model / Zen"]
    Tools --> Project["真实项目：文件 / 测试 / Git / 本地工具"]
    Model --> Provider["模型供应商"]
    Agent --> Policy["治理层：permissions / network / share / team config"]

    style Entry fill:#dbeafe,stroke:#3b82f6
    style Agent fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Policy fill:#fee2e2,stroke:#ef4444,stroke-width:2px

这个图里有一个关键点：OpenCode 不只是“聊天框 + 改代码”。它把入口、上下文、角色、工具、模型和权限都暴露成可配置层。

所以 OpenCode 的学习顺序不能只按功能菜单来。你要先理解它的层次，再决定哪一层该由个人配置，哪一层该写进项目，哪一层必须收紧权限。

4. 四个核心特征

4.1 模型不是绑定死的

OpenCode 可以接不同 provider，也可以在配置里声明默认模型和 lightweight task 使用的小模型。官方也提供 OpenCode Zen 这类经过 OpenCode 团队测试的模型和供应商组合。

这意味着你可以把模型选择当成工程策略：

• 轻量解释和文档整理，用低成本模型。
• 跨文件 bug 和重构，用更强模型。
• 安全、发布、数据处理，用强模型加人工确认。
• 主 provider 限流时，有备用 provider。

4.2 终端 TUI 是主战场

OpenCode 的 TUI 不是把网页聊天搬进终端。它围绕开发者已经在用的项目目录、shell、文件引用、slash command（斜杠命令）、session（会话）、compact（上下文压缩）和工具详情来组织交互。

你可以在对话里 @file 引用文件让它读项目；可以让它执行命令把测试输出带回上下文；也可以把常用动作做成 command（命令），减少每次重新解释任务边界。

最值得理解的是 OpenCode 的 Plan mode（计划模式）vs Build mode（构建模式）双模式——按 Tab 键切换：

跨模块改动、上线前重构、不熟悉的代码库——先 Tab 切到 Plan mode 看 OpenCode 的方案，确认后再切回 Build mode 让它真改。这是 OpenCode 最有标志性的安全交互。

终端优先的好处是：OpenCode 不需要假装替代你的开发环境，它直接进入你本来就在用的环境。

4.3 项目规则可以沉淀

OpenCode 的配置不是单一文件。你会遇到 opencode.json、.opencode/、AGENTS.md、rules、commands、agents、skills、plugins、tools、themes 等入口。

新手最容易犯的错，是把所有内容都塞进一个长提示词。更稳的分法是：

4.4 扩展能力进入运行时

OpenCode 不只调用模型。它能接 MCP server、LSP、formatter、custom tools、SDK、server、GitHub/GitLab 集成，也能通过 plugin 扩展运行时能力。

这让它可以从“个人终端助手”向“团队自动化组件”延伸。但代价也很清楚：工具越多，权限越复杂，排障和安全成本越高。

5. 和 Claude Code / Codex 的差异

先给推荐判断：

不要用“哪个更强”做唯一判断。更现实的问题是：

• 你的团队是否愿意维护配置？
• 你是否需要 provider 可替换？
• 你是否需要把规则和 agent 文件纳入版本控制？
• 你是否能接受开放体系带来的配置成本？
• 你是否有能力治理 permissions、network、share 和工具调用边界？

如果这些问题的答案偏“是”，OpenCode 才能发挥它的优势。

6. 适合和不适合

OpenCode 适合这些场景：

• 你想把 coding agent 能力放进终端工作流，而不是只在 IDE 侧边栏里聊天。
• 你需要按任务切换 provider/model，控制成本和限流风险。
• 你希望把项目规则、commands、agents、skills 放进仓库，让团队共享。
• 你想接 MCP、LSP、formatter、custom tools 或内部系统。
• 你需要开源实现，方便审计、二次扩展或接入自动化。

OpenCode 不适合这些期待：

• 希望“打开就完美”，不想理解配置、权限和 provider。
• 希望 AI 自动接管整个项目，不愿意先从只读和单文件任务开始。
• 不打算维护 rules、commands、agents，却期待输出长期稳定。
• 不愿意管理 API key、权限、分享和网络访问边界。
• 把开源等同于“没有治理成本”。

7. 最小心智模型

后面 7 篇可以先按这 6 层理解：

第一天只跑前 3 层（入口 / 上下文 / 执行）。沉淀经验后进角色层；准备长期使用再设计模型层和治理层。

8. 怎么验证你真的理解了

接下来去哪

官方资料

• OpenCode 官方入门：https://opencode.ai/docs
• OpenCode 配置：https://opencode.ai/docs/config
• OpenCode 权限：https://opencode.ai/docs/permissions
• OpenCode GitHub 仓库：https://github.com/anomalyco/opencode