---
title: "01 · OpenCode 是什么"
description: "理解 OpenCode 的定位：开源、终端优先、多模型可换、配置开放的 AI Coding Agent。"
verifiedAt: "2026-05-07"
---

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

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

> [!NOTE]
> **这一篇解决什么问题**：把 OpenCode 从“另一个 AI 编程工具”重新理解成“开放配置的 coding agent 运行时”。读完你应该能说清：它和 Claude Code / Codex 差在哪，适合什么项目，不适合什么期待，以及后面 7 篇为什么按现在这个顺序讲。

## 1. 一个真实选择题

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

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

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

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

> [!IMPORTANT]
> **先把问题问对**：选 OpenCode 不是因为它一定比 Claude Code 或 Codex 更聪明，而是因为你想要更开放的 provider、config、agent、skill、plugin 和 tool 组合空间。

## 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 运行时。

这句话里有四个关键词。

| 关键词 | 不是在说什么 | 真正在说什么 |
| --- | --- | --- |
| 开源 | 不是“免费所以更好” | 你能看源码、审计行为、理解运行边界 |
| 终端优先 | 不是“只能在终端用” | TUI、shell、文件系统、测试命令是一等工作流 |
| 多模型可换 | 不是“随便切模型玩” | provider/model 是配置项，可以按任务和成本分层 |
| 配置开放 | 不是“配置越多越高级” | 项目规则、agent、command、skill、plugin 可以沉淀和版本化 |

## 3. 先看它长在哪个位置

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

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

```mermaid
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。

> [!TIP]
> **通俗讲**：多模型能力不是“开模型超市”，而是让不同风险等级的任务走不同成本结构。

### 4.2 终端 TUI 是主战场

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

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

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

| 模式 | 行为 | 何时用 |
|---|---|---|
| **Plan mode** | 禁用文件修改，只输出"打算怎么做" | 任务复杂、范围不清、第一次接触陌生模块 |
| **Build mode** | 允许执行修改和命令 | 计划已确认、改动范围明确 |

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

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

### 4.3 项目规则可以沉淀

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

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

| 内容 | 更适合放哪里 | 原因 |
| --- | --- | --- |
| 默认模型、权限、MCP、formatter | `opencode.json` | 运行参数需要机器可读 |
| 项目长期约定 | rules / AGENTS.md | 每次任务都应该被读取 |
| 重复任务流程 | commands | 用 slash command 固定入口 |
| 特定角色和权限 | agents | 把 review、docs、test、plan 分开 |
| 跨项目能力包 | skills | 复用流程和检查清单 |
| 运行时扩展 | plugins | 需要代码接入和维护 |

### 4.4 扩展能力进入运行时

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

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

## 5. 和 Claude Code / Codex 的差异

先给推荐判断：

| 工具 | 更像什么 | 你应该优先考虑它的情况 |
| --- | --- | --- |
| Claude Code | Anthropic 官方深度打磨的 coding agent | 你想要默认体验统一，少配置，权限、记忆、subagent、hook、command 体系清晰 |
| Codex | OpenAI 生态里的多形态 coding agent | 你已经重度使用 OpenAI / ChatGPT / Codex CLI / IDE / cloud task，希望产品联动更强 |
| OpenCode | 开源、终端优先、provider 可换的 agent 运行时 | 你要开放配置、多模型策略、项目级规则、可审计源码和可扩展运行时 |

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

- 你的团队是否愿意维护配置？
- 你是否需要 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、权限、分享和网络访问边界。
- 把开源等同于“没有治理成本”。

> [!WARNING]
> **新手坑**：OpenCode 的配置面越开放，越不能把它当成“省心一键替代品”。开放给了你控制权，也把治理责任交给了你。

## 7. 最小心智模型

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

| 层 | 包含什么 | 第一天必动 | 不做会怎样 |
|---|---|:---:|---|
| **入口层** | CLI / TUI / IDE 扩展 / Desktop / Web / ACP | ✓ | 不知道任务从哪发起 |
| **上下文层** | `@file` 引用 / `AGENTS.md` 项目规则文件 / rules / session（会话）/ compact（压缩） | ✓ | 模型每次重新认识项目，token 浪费 |
| **执行层** | read / edit / bash 终端 / LSP（语言服务器，类型提示）/ formatter / MCP | ✓ | 模型只会聊天不会动手 |
| **角色层** | commands（斜杠命令）/ agents（专用代理）/ skills（技能包）/ plugins（运行时插件） | — | 重复任务每次都从零讲 |
| **模型层** | provider（供应商）/ model / small_model 小模型 / OpenCode Zen 精选组合 / API key | — | 所有任务用同一个最贵模型 |
| **治理层** | permissions（权限）/ network（网络）/ share（分享）/ team config（团队配置） | — | 团队场景安全风险无法收敛 |

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

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

| # | 问题 | 自检 |
|:-:| --- |:---:|
| 1 | OpenCode 为什么不是 Claude Code / Codex 的简单替代品？ | ☐ |
| 2 | “多模型可换”的价值是什么，不是什么？ | ☐ |
| 3 | 哪些内容应该放 rules，哪些内容应该放 commands 或 agents？ | ☐ |

> [!TIP]
> **过关标准**：能用一句话说清——OpenCode 的核心价值不是默认体验最省心，而是把 coding agent 的入口、模型、规则、工具和权限开放成可配置体系。

## 接下来去哪

<Cards>
  <Card title="安装、连接模型与第一次运行" description="先验证 OpenCode 能在真实项目里启动、连接 provider、读取上下文并完成低风险任务。" href="/docs/opencode/understanding/02-install-first-run" />
  <Card title="OpenCode 从原理到实战" description="回到理解篇路线图，按 8 篇文章建立完整学习路径。" href="/docs/opencode/understanding" />
  <Card title="入门官方整理" description="如果你要直接查安装、CLI、TUI、IDE 和分享入口，看官方教程中文版。" href="/docs/opencode/official/00-getting-started" />
  <Card title="模型与供应商策略" description="理解 OpenCode 的 provider 可换之后，再看模型策略怎么落地。" href="/docs/opencode/understanding/06-model-provider-strategy" />
</Cards>

## 官方资料

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