OpenCode 从原理到实战

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、什么时候切模型、什么工具值得接、什么权限必须收紧。

这组文章不重复官方手册。要查某个命令或配置项，去官方教程中文版；要理解功能背后的使用判断，读这里。

8 篇文章的主线

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”，第二到第三篇解决“怎么跑起来并稳定使用”，第四到第七篇解决“怎么把能力沉淀成系统”，第八篇解决“怎么把风险收住”。

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

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

和官方教程中文版的分工

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

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

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

先记住一张分层图

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

入口层      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 能做什么、看什么	进真实项目、对外分享、团队共用前

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

OpenCode 从原理到实战

8 篇文章的主线

先跑起来

再沉淀规则

最后收紧边界

推荐阅读顺序

三个学习阶段

和官方教程中文版的分工

先记住一张分层图

接下来去哪

OpenCode 到底是什么

安装、连接模型与第一次运行

官方教程中文版

OpenCode 中文教程

本页目录