---
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="/zh-Hant/docs/opencode/official" />
  <Card title="從原理到實戰" description="8 篇中文講解，理解 OpenCode 的定位、配置體系和團隊使用邊界。" href="/zh-Hant/docs/opencode/understanding" />
  <Card title="安裝、連線模型與第一次執行" description="第一次使用時，先跑通安裝、provider、只讀和低風險寫入。" href="/zh-Hant/docs/opencode/understanding/02-install-first-run" />
  <Card title="安全、分享與團隊使用" description="進入真實專案或團隊流程前，先收緊許可權、金鑰、分享和網路邊界。" href="/zh-Hant/docs/opencode/understanding/08-security-share-team" />
</Cards>

## 怎麼選擇閱讀路徑

第一次接觸 OpenCode，不要從複雜配置開始。先把安裝、模型連線和第一輪只讀任務跑通，再進入 agent、skill、plugin、MCP、LSP 和團隊配置。

| 你的狀態 | 先讀什麼 | 目標 |
| --- | --- | --- |
| 還沒安裝 | [官方教程中文版](/zh-Hant/docs/opencode/official) | 找到安裝方式、啟動 TUI、完成 provider 連線 |
| 能開啟 TUI，但不會穩定使用 | [安裝、連線模型與第一次執行](/zh-Hant/docs/opencode/understanding/02-install-first-run) | 跑通一個低風險任務，確認能讀專案、能解釋、能受控修改 |
| 已經日常使用，但配置很散 | [配置、Rules 與自定義命令](/zh-Hant/docs/opencode/understanding/04-config-rules-commands) | 把重複提醒沉澱成專案規則和 slash command |
| 想接更多工具 | [工具、MCP、LSP 與格式化器](/zh-Hant/docs/opencode/understanding/07-tools-mcp-lsp) | 判斷什麼應該用內建工具，什麼才值得接 MCP 或 LSP |
| 準備團隊使用 | [安全、分享與團隊使用](/zh-Hant/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)
