---
title: "OpenCode 从原理到实战"
description: "从定位、终端工作流、配置、Agent、模型、工具和安全边界理解 OpenCode。"
verifiedAt: "2026-05-09"
---

OpenCode 的难点不在“命令记不住”，而在“能力太开放”。它有六种入口（TUI 终端界面、CLI 命令行、IDE 插件、桌面端、Web 浏览器、ACP 编辑器协议），进入会话后还有十多类可配置项——provider（模型供应商）、rules（项目规则）、commands（自定义命令）、agents（角色）、skills（能力包）、plugins（运行时扩展）、MCP（外部工具协议）、LSP（代码补全/跳转引擎）、formatter（代码格式化器）、SDK（编程接入）、server（HTTP 服务模式）、share（会话分享）——初学者很容易把它当成一堆功能列表。

它最有标志性的设计藏在第一次会话里：按 **Tab** 键就能在 *Plan mode*（只规划、不动文件）和 *Build mode*（按计划改代码）之间切换。先用 Plan 想清楚再切 Build 落地，是 OpenCode 与其他终端 AI 编程工具最直观的差异点。

这一组文章只解决一个问题：**怎样把 OpenCode 理解成一套可长期使用的 AI 编程工作流**。读完以后，你应该能判断哪些规则写进项目、哪些任务交给 agent、什么时候切模型、什么工具值得接、什么权限必须收紧。

> [!NOTE]
> **这组文章不重复官方手册**。要查某个命令或配置项，去 [官方教程中文版](/docs/opencode/official)；要理解功能背后的使用判断，读这里。

## 8 篇文章的主线

```mermaid
flowchart TD
    A["01 定位：OpenCode 是什么"] --> B["02 跑通：安装与第一次运行"]
    B --> C["03 工作流：终端 TUI 怎么用"]
    C --> D["04 沉淀：配置、Rules、Commands"]
    D --> E["05 扩展：Agents、Skills、Plugins"]
    E --> F["06 策略：模型与供应商"]
    F --> G["07 工具：MCP、LSP、Formatter"]
    G --> H["08 治理：安全、分享、团队"]

    style A fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style D fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style H fill:#fee2e2,stroke:#ef4444,stroke-width:2px
```

第一篇解决“为什么用 OpenCode”，第二到第三篇解决“怎么跑起来并稳定使用”，第四到第七篇解决“怎么把能力沉淀成系统”，第八篇解决“怎么把风险收住”。

<Cards>
  <Card title="先跑起来" description="安装、连接 provider、启动 TUI，完成第一轮只读任务。" href="/docs/opencode/understanding/02-install-first-run" />
  <Card title="再沉淀规则" description="把反复提醒写成 rules，把重复流程写成 slash command。" href="/docs/opencode/understanding/04-config-rules-commands" />
  <Card title="最后收紧边界" description="权限、网络、分享、密钥和团队配置先定义，再扩大使用范围。" href="/docs/opencode/understanding/08-security-share-team" />
</Cards>

## 推荐阅读顺序

1. [OpenCode 到底是什么](/docs/opencode/understanding/01-what-is-opencode)：先建立定位，避免把它当成 Claude Code 或 Codex 的简单替代品。
2. [安装、连接模型与第一次运行](/docs/opencode/understanding/02-install-first-run)：跑通 CLI、TUI、IDE 和 provider 连接。
3. [终端 TUI 工作流](/docs/opencode/understanding/03-terminal-workflow)：理解文件引用、命令、会话、压缩和 attach。
4. [配置、Rules 与自定义命令](/docs/opencode/understanding/04-config-rules-commands)：把一次性提示词变成项目约定。
5. [Agents、Skills 与 Plugins](/docs/opencode/understanding/05-agents-skills-plugins)：区分角色、能力包和运行时扩展。
6. [模型与供应商策略](/docs/opencode/understanding/06-model-provider-strategy)：按任务选择模型，而不是只追最新模型。
7. [工具、MCP、LSP 与格式化器](/docs/opencode/understanding/07-tools-mcp-lsp)：把 OpenCode 接到真实开发环境。
8. [安全、分享与团队使用](/docs/opencode/understanding/08-security-share-team)：控制权限、网络和公开分享边界。

## 三个学习阶段

| 阶段 | 先解决的问题 | 过关标准 |
| --- | --- | --- |
| 上手 | OpenCode 能不能在我的项目里工作 | 能安装、连接 provider、启动 TUI，并让它只读解释项目结构 |
| 沉淀 | 怎么让一次经验变成下次自动遵守 | 能区分 config、rules、commands、agents、skills、plugins，各自只放合适内容 |
| 治理 | 怎么让它进真实项目不失控 | 能写出权限基线，知道什么时候禁止分享、联网、部署和读取密钥 |

> [!IMPORTANT]
> **别急着追高级功能**：OpenCode 的上限来自开放扩展，但稳定性来自低风险起步。第一轮任务如果连“只读解释项目结构”都不稳定，就先不要接 MCP、plugin 或自动化。

## 和官方教程中文版的分工

官方教程中文版按功能分类，适合查 API、命令、配置项和入口位置：

- [OpenCode 官方教程中文版](/docs/opencode/official)
- [CLI / TUI / IDE / 分享](/docs/opencode/official/00-getting-started)
- [配置 / 命令 / 快捷键 / 主题](/docs/opencode/official/01-customization/config)
- [Agents / Skills / Plugins / Rules](/docs/opencode/official/02-agents-skills/agents)
- [模型 / Provider](/docs/opencode/official/03-models/models)
- [工具 / MCP / LSP / Formatter](/docs/opencode/official/04-tools-mcp/tools)
- [权限 / 网络](/docs/opencode/official/05-security/permissions)

从原理到实战不重复官方手册，而是把这些能力串成使用判断：

- **功能是什么**：只保留足够理解的定义，不堆参数。
- **为什么要用**：解释这个能力解决的真实开发问题。
- **怎么上手**：给一个低风险最小动作。
- **常见坑**：指出新手最容易误用的地方。
- **下一步**：把当前文章接到前后篇和官方页。

## 先记住一张分层图

OpenCode 可以先拆成 6 层。后面 8 篇都围绕这张图展开。

```text
入口层      TUI / CLI / IDE / Desktop / Web / ACP
上下文层    AGENTS.md / rules / @file / session / compact
执行层      read / edit / bash / LSP / formatter / MCP
角色层      commands / agents / skills / plugins
模型层      provider / model / small_model / Zen / API key
治理层      permissions / network / share / team config
```

每一层解决的问题和你需要关心它的时机：

| 层 | 解决的问题 | 什么时候开始关心 |
| --- | --- | --- |
| 入口层 | OpenCode 在哪里运行、长什么样 | 选 TUI 还是 IDE / 桌面端 / Web 时 |
| 上下文层 | 让模型知道项目结构和当前会话状态 | 写 AGENTS.md、用 @file 引用、对话变长想压缩时 |
| 执行层 | 模型怎么读代码、改文件、跑命令 | 接外部工具、想看模型实际做了什么时 |
| 角色层 | 把重复任务沉淀成可复用动作 | 想让一次经验下次自动遵守时 |
| 模型层 | 用哪个供应商和模型、怎么管 key | 任务复杂度变化、预算需要分级时 |
| 治理层 | 控制 OpenCode 能做什么、看什么 | 进真实项目、对外分享、团队共用前 |

如果你只想快速使用，先掌握入口层、上下文层和执行层。如果要团队复用，再进入角色层、模型层和治理层。

## 接下来去哪

<Cards>
  <Card title="OpenCode 到底是什么" description="先拆清 OpenCode 和 Claude Code、Codex 的差异，建立正确定位。" href="/docs/opencode/understanding/01-what-is-opencode" />
  <Card title="安装、连接模型与第一次运行" description="已经理解定位后，进入第一天安全闭环。" href="/docs/opencode/understanding/02-install-first-run" />
  <Card title="官方教程中文版" description="需要查具体命令、配置项和功能入口时，回到官方查询手册。" href="/docs/opencode/official" />
  <Card title="OpenCode 中文教程" description="回到总入口，在官方查询和理解路线之间切换。" href="/docs/opencode" />
</Cards>
