OpenCode 官方教程中文版
基于 OpenCode 官方资料重写的中文查询手册，按功能分类组织。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| 官方教程 | official | 讲 OpenCode 具体功能配置。 |
| 按问题查 | problem-first | 从问题反查章节。 |
| 事实基准 | baseline | 配置以官方为准。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你按要解决的问题定位该读 OpenCode 官方教程哪一章。
你是 OpenCode 官方教程导航顾问。
【角色】
OpenCode 官方教程导航顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 要解决的具体问题：___
- 用的入口 / 场景：___
- 经验水平：___
- 紧迫程度：___
- 现状：___
【工作流程】
1. 把问题归类（入门 / 定制 / agent技能 / 模型 / 工具MCP / 安全 / 集成 / SDK / 平台）
2. 定位对应章节
3. 给阅读顺序
4. 标出需核验的
5. 给落地下一步
【输出规范】
▌一、问题归类
▌二、对应章节
▌三、阅读顺序
▌四、需核验内容
【硬约束】
- 按问题精准定位不通读
- 易变信息以官方为准
- 贴合经验水平
- 不要替我臆测情况或编造不存在的功能，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法这一页是 OpenCode 官方能力的中文查询入口。你不用从头读完，按自己当前卡住的问题进入对应章节：安装看“入门”，项目规则看“个性化”，角色分工看“Agents & Skills”，工具接入看“工具与 MCP”，团队安全看“安全与网络”。
这页解决什么问题：把 OpenCode 官方文档拆成可查询的功能地图。读完你应该知道“我要查的功能在哪一组”，而不是在 CLI、TUI、config、agent、tool、provider 这些词之间来回找。
事实来源：opencode.ai/docs/zh-cn · OpenCode 官方维护的中文文档。具体参数、命令和行为变化以官方页面为准；本页只做中文路径重组和学习顺序建议。
先按问题选入口
| 你现在要做什么 | 进入哪组 | 先看哪一页 |
|---|---|---|
| 第一次安装和启动 | 入门 | 入门 |
| 只想知道 TUI 怎么操作 | 入门 | 使用 TUI |
| 想把配置写进项目 | 个性化 | 配置 OpenCode |
| 想沉淀重复任务 | 个性化 | 创建自定义命令 |
| 想拆角色或专用 agent | Agents & Skills | 配置 Agents |
| 想接外部系统 | 工具与 MCP | 连接 MCP 服务器 |
| 想控制读写和命令权限 | 安全与网络 | 管理权限 |
| 想把 OpenCode 接进团队流程 | 集成 / SDK & 服务 | 接入 GitHub 或 使用 SDK |
阅读顺序建议
第一次学习按这个顺序走，不要直接跳到 plugin 或 SDK：
- 入门：安装、provider、TUI、IDE、分享。
- 个性化：配置文件、快捷键、主题、自定义命令。
- Agents & Skills：agent、skill、plugin、rules 的职责边界。
- 模型与供应商：先理解 provider/model，再考虑默认模型和备用模型。
- 工具与 MCP：先掌握内置工具，再扩展 MCP、LSP、formatter 和 custom tools。
- 安全与网络：真实项目使用前必须回头检查权限、网络和分享。
不要只看能做什么：OpenCode 的危险点也来自“能做什么”。凡是涉及 edit、bash、webfetch、websearch、MCP 写操作、分享会话，都应该同时查权限和安全页面。
完整目录
入门
入门阶段只验证三件事：命令能启动、provider 能连接、OpenCode 能在一个真实项目里完成只读解释。先不要让它大范围改代码。
个性化
个性化不是换皮肤那么简单。真正有长期价值的是把默认模型、权限、instructions、commands、agents、MCP 和 formatter 放到合适的配置层级。
Agents & Skills
这一组最容易混淆。可以先记住一句话：rules 是项目长期约定，commands 是重复任务入口，agents 是角色和权限边界，skills 是可复用能力包，plugins 是运行时扩展。
模型与供应商
OpenCode 的多模型能力适合做任务分层：轻量解释用低成本模型，跨文件修改用更强模型，安全和发布相关任务必须保留人工确认。
工具与 MCP
先用内置工具跑通读文件、改文件、执行测试和查看 diff，再接 MCP。工具越多，权限和误操作风险越高。
安全与网络
安全页面不是最后才看的附录。只要 OpenCode 能读写仓库、执行命令、联网或分享会话，就应该先定义权限边界。
集成
集成类页面适合已经有团队流程的人读。个人上手阶段不需要一开始就接 GitHub/GitLab 自动化。
SDK & 服务
SDK 和 server 说明 OpenCode 不只是终端工具，也能作为服务能力被嵌入系统。但这部分维护成本更高，先确认普通 TUI 工作流稳定，再进入这一层。
平台与故障
平台差异和故障排查最好按症状查。Windows 用户优先看 WSL；provider 不稳定或不想自己筛模型时，看 Zen；IDE/协议集成再看 ACP。