---
title: "OpenCode 中文教程"
description: "基于 OpenCode 官方资料和源码重写的中文教程。"
verifiedAt: "2026-05-09"
---

OpenCode 是一个开源 AI coding agent。它可以跑在终端 TUI、CLI、桌面应用、IDE 扩展和 Web/server 里，也可以通过 SDK、GitHub/GitLab 集成、ACP、MCP、LSP、Plugin 和 Skill 接到更大的开发流程里。

这个中文教程解决两个问题：第一，帮你快速查到官方功能怎么用；第二，帮你理解 OpenCode 适合放在什么工作流里。读完以后，你应该能判断什么时候用 OpenCode、怎么连接模型、怎么配置项目规则、哪些能力可以交给 agent，哪些动作必须继续人工确认。

> [!NOTE]
> **先给结论**：如果你只是第一次打开 OpenCode，先走“官方教程中文版”；如果你已经能跑起来，但不知道怎么把 rules、commands、agents、skills、MCP 和权限体系连成长期工作流，再读“从原理到实战”。

## 两条互补路径

```mermaid
flowchart LR
    Start["OpenCode 中文教程"] --> Official["官方教程中文版"]
    Start --> Understanding["从原理到实战"]
    Official --> Lookup["安装 / CLI / TUI / 配置 / 工具 / 权限"]
    Understanding --> Judgment["定位 / 工作流 / 模型策略 / 团队边界"]

    style Start fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style Official fill:#dcfce7,stroke:#22c55e
    style Understanding fill:#fef3c7,stroke:#f59e0b
```

## 接下来去哪

<Cards>
  <Card title="官方教程中文版" description="按官方文档功能分类，适合查命令、配置项和入口位置。" href="/docs/opencode/official" />
  <Card title="从原理到实战" description="8 篇中文讲解，理解 OpenCode 的定位、配置体系和团队使用边界。" href="/docs/opencode/understanding" />
  <Card title="安装、连接模型与第一次运行" description="第一次使用时，先跑通安装、provider、只读和低风险写入。" href="/docs/opencode/understanding/02-install-first-run" />
  <Card title="安全、分享与团队使用" description="进入真实项目或团队流程前，先收紧权限、密钥、分享和网络边界。" href="/docs/opencode/understanding/08-security-share-team" />
</Cards>

## 怎么选择阅读路径

第一次接触 OpenCode，不要从复杂配置开始。先把安装、模型连接和第一轮只读任务跑通，再进入 agent、skill、plugin、MCP、LSP 和团队配置。

| 你的状态 | 先读什么 | 目标 |
| --- | --- | --- |
| 还没安装 | [官方教程中文版](/docs/opencode/official) | 找到安装方式、启动 TUI、完成 provider 连接 |
| 能打开 TUI，但不会稳定使用 | [安装、连接模型与第一次运行](/docs/opencode/understanding/02-install-first-run) | 跑通一个低风险任务，确认能读项目、能解释、能受控修改 |
| 已经日常使用，但配置很散 | [配置、Rules 与自定义命令](/docs/opencode/understanding/04-config-rules-commands) | 把重复提醒沉淀成项目规则和 slash command |
| 想接更多工具 | [工具、MCP、LSP 与格式化器](/docs/opencode/understanding/07-tools-mcp-lsp) | 判断什么应该用内置工具，什么才值得接 MCP 或 LSP |
| 准备团队使用 | [安全、分享与团队使用](/docs/opencode/understanding/08-security-share-team) | 控制权限、分享、密钥、网络和项目级配置边界 |

> [!IMPORTANT]
> **不要反过来读**：还没跑通第一轮任务，就研究 plugin 和 SDK，很容易把 OpenCode 当成“可配置项合集”。OpenCode 真正的价值来自“能在真实项目里长期、受控、可复用地执行任务”。

## 这组教程会讲清什么

- OpenCode 和 Claude Code、Codex 的差异：不是谁更强，而是开放配置、多模型和终端优先这三个取舍不同。
- 终端 TUI 的核心动作：`@` 文件引用、`!` shell 命令、`/` 命令、会话压缩、attach 和 server。
- 配置体系：全局配置、项目配置、`.opencode/`、rules、commands、agents、skills、plugins 各自放什么。
- 模型策略：provider、model、small model、Zen、备用模型和 agent 绑定模型怎么取舍。
- 工具系统：内置工具、MCP、LSP、formatter、custom tools 的职责边界。
- 安全底线：permissions、网络访问、会话分享、密钥隔离和团队公共配置。

## 事实基准

- 官方文档：[https://opencode.ai/docs](https://opencode.ai/docs)
- 上游源码：[https://github.com/anomalyco/opencode](https://github.com/anomalyco/opencode)

这里不会把官方英文文档逐页直译。官方页面负责给事实和参数，本教程负责按中文开发者的学习顺序重写：先解释这个功能解决什么问题，再给最小可执行动作，最后补常见坑和下一步。

## 使用前的安全提醒

OpenCode 能读文件、改文件、跑命令、联网、调用工具、分享会话。这些能力进入真实项目之前，先按低风险顺序推进：

1. 第一次任务只读。
2. 第一次写操作限定单文件。
3. 大范围修改先让它给计划。
4. 涉及密钥、账号、支付、数据删除、发布部署时必须人工确认。
5. 分享会话前先脱敏；敏感项目直接关闭分享。

这不是保守，而是让你敢把 OpenCode 放进长期工作流。

## 引流出口

- Aaron工作流主站：[xiangyugongzuoliu.com](https://xiangyugongzuoliu.com)
- AI 编程实操课：[课程页](https://flowus.cn/xiangyugongzuoliu/share/d392dcad-b537-44ee-a3e2-56ff5af02bce)
