OpenCode 官方教程中文版
基于 OpenCode 官方资料重写的中文查询手册，按功能分类组织。
这一页是 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。