---
title: "OpenCode 官方教程中文版"
description: "基于 OpenCode 官方资料重写的中文查询手册，按功能分类组织。"
verifiedAt: "2026-05-09"
---

这一页是 OpenCode 官方能力的中文查询入口。你不用从头读完，按自己当前卡住的问题进入对应章节：安装看“入门”，项目规则看“个性化”，角色分工看“Agents & Skills”，工具接入看“工具与 MCP”，团队安全看“安全与网络”。

> [!NOTE]
> **这页解决什么问题**：把 OpenCode 官方文档拆成可查询的功能地图。读完你应该知道“我要查的功能在哪一组”，而不是在 CLI、TUI、config、agent、tool、provider 这些词之间来回找。

事实来源：[opencode.ai/docs/zh-cn](https://opencode.ai/docs/zh-cn) · OpenCode 官方维护的中文文档。具体参数、命令和行为变化以官方页面为准；本页只做中文路径重组和学习顺序建议。

## 先按问题选入口

| 你现在要做什么 | 进入哪组 | 先看哪一页 |
| --- | --- | --- |
| 第一次安装和启动 | 入门 | [入门](/docs/opencode/official/00-getting-started) |
| 只想知道 TUI 怎么操作 | 入门 | [使用 TUI](/docs/opencode/official/00-getting-started/tui) |
| 想把配置写进项目 | 个性化 | [配置 OpenCode](/docs/opencode/official/01-customization/config) |
| 想沉淀重复任务 | 个性化 | [创建自定义命令](/docs/opencode/official/01-customization/commands) |
| 想拆角色或专用 agent | Agents & Skills | [配置 Agents](/docs/opencode/official/02-agents-skills/agents) |
| 想接外部系统 | 工具与 MCP | [连接 MCP 服务器](/docs/opencode/official/04-tools-mcp/mcp-servers) |
| 想控制读写和命令权限 | 安全与网络 | [管理权限](/docs/opencode/official/05-security/permissions) |
| 想把 OpenCode 接进团队流程 | 集成 / SDK & 服务 | [接入 GitHub](/docs/opencode/official/06-integrations/github) 或 [使用 SDK](/docs/opencode/official/07-sdk/sdk) |

## 阅读顺序建议

第一次学习按这个顺序走，不要直接跳到 plugin 或 SDK：

1. [入门](/docs/opencode/official/00-getting-started)：安装、provider、TUI、IDE、分享。
2. [个性化](/docs/opencode/official/01-customization/config)：配置文件、快捷键、主题、自定义命令。
3. [Agents & Skills](/docs/opencode/official/02-agents-skills/agents)：agent、skill、plugin、rules 的职责边界。
4. [模型与供应商](/docs/opencode/official/03-models/models)：先理解 provider/model，再考虑默认模型和备用模型。
5. [工具与 MCP](/docs/opencode/official/04-tools-mcp/tools)：先掌握内置工具，再扩展 MCP、LSP、formatter 和 custom tools。
6. [安全与网络](/docs/opencode/official/05-security/permissions)：真实项目使用前必须回头检查权限、网络和分享。

> [!IMPORTANT]
> **不要只看能做什么**：OpenCode 的危险点也来自“能做什么”。凡是涉及 `edit`、`bash`、`webfetch`、`websearch`、MCP 写操作、分享会话，都应该同时查权限和安全页面。

## 完整目录

### 入门

- [入门](/docs/opencode/official/00-getting-started)
- [使用 CLI](/docs/opencode/official/00-getting-started/cli)
- [使用 TUI](/docs/opencode/official/00-getting-started/tui)
- [连接 IDE](/docs/opencode/official/00-getting-started/ide)
- [分享会话](/docs/opencode/official/00-getting-started/share)

入门阶段只验证三件事：命令能启动、provider 能连接、OpenCode 能在一个真实项目里完成只读解释。先不要让它大范围改代码。

### 个性化

- [切换主题](/docs/opencode/official/01-customization/themes)
- [配置快捷键](/docs/opencode/official/01-customization/keybinds)
- [创建自定义命令](/docs/opencode/official/01-customization/commands)
- [配置 OpenCode](/docs/opencode/official/01-customization/config)

个性化不是换皮肤那么简单。真正有长期价值的是把默认模型、权限、instructions、commands、agents、MCP 和 formatter 放到合适的配置层级。

### Agents & Skills

- [配置 Agents](/docs/opencode/official/02-agents-skills/agents)
- [使用 Agent Skills](/docs/opencode/official/02-agents-skills/skills)
- [安装插件](/docs/opencode/official/02-agents-skills/plugins)
- [编写规则](/docs/opencode/official/02-agents-skills/rules)

这一组最容易混淆。可以先记住一句话：rules 是项目长期约定，commands 是重复任务入口，agents 是角色和权限边界，skills 是可复用能力包，plugins 是运行时扩展。

### 模型与供应商

- [选择模型](/docs/opencode/official/03-models/models)
- [配置模型供应商](/docs/opencode/official/03-models/providers)

OpenCode 的多模型能力适合做任务分层：轻量解释用低成本模型，跨文件修改用更强模型，安全和发布相关任务必须保留人工确认。

### 工具与 MCP

- [连接 MCP 服务器](/docs/opencode/official/04-tools-mcp/mcp-servers)
- [创建自定义工具](/docs/opencode/official/04-tools-mcp/custom-tools)
- [管理工具](/docs/opencode/official/04-tools-mcp/tools)
- [连接 LSP 服务器](/docs/opencode/official/04-tools-mcp/lsp)
- [配置格式化工具](/docs/opencode/official/04-tools-mcp/formatters)

先用内置工具跑通读文件、改文件、执行测试和查看 diff，再接 MCP。工具越多，权限和误操作风险越高。

### 安全与网络

- [管理权限](/docs/opencode/official/05-security/permissions)
- [配置网络](/docs/opencode/official/05-security/network)

安全页面不是最后才看的附录。只要 OpenCode 能读写仓库、执行命令、联网或分享会话，就应该先定义权限边界。

### 集成

- [接入 GitHub](/docs/opencode/official/06-integrations/github)
- [接入 GitLab](/docs/opencode/official/06-integrations/gitlab)
- [了解生态系统](/docs/opencode/official/06-integrations/ecosystem)
- [配置企业版](/docs/opencode/official/06-integrations/enterprise)

集成类页面适合已经有团队流程的人读。个人上手阶段不需要一开始就接 GitHub/GitLab 自动化。

### SDK & 服务

- [使用 SDK](/docs/opencode/official/07-sdk/sdk)
- [启动服务器](/docs/opencode/official/07-sdk/server)
- [在 Web 中使用 OpenCode](/docs/opencode/official/07-sdk/web)

SDK 和 server 说明 OpenCode 不只是终端工具，也能作为服务能力被嵌入系统。但这部分维护成本更高，先确认普通 TUI 工作流稳定，再进入这一层。

### 平台与故障

- [在 Windows WSL 中使用 OpenCode](/docs/opencode/official/08-platform/windows-wsl)
- [使用 Zen 模型列表](/docs/opencode/official/08-platform/zen)
- [排查故障](/docs/opencode/official/08-platform/troubleshooting)
- [接入 ACP](/docs/opencode/official/08-platform/acp)

平台差异和故障排查最好按症状查。Windows 用户优先看 WSL；provider 不稳定或不想自己筛模型时，看 Zen；IDE/协议集成再看 ACP。

## 接下来去哪

<Cards>
  <Card title="从原理到实战" description="理解这些官方功能为什么这样分层，以及真实项目里怎么长期使用。" href="/docs/opencode/understanding" />
  <Card title="安装、连接模型与第一次运行" description="已经准备动手时，从第一天安全闭环开始。" href="/docs/opencode/understanding/02-install-first-run" />
  <Card title="安全、分享与团队使用" description="准备接真实项目时，先补权限、密钥、分享和团队边界。" href="/docs/opencode/understanding/08-security-share-team" />
  <Card title="OpenCode 中文教程" description="回到总入口，在官方查询和理解路线之间切换。" href="/docs/opencode" />
</Cards>
