---
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 官方維護的中文文件。具體引數、命令和行為變化以官方頁面為準；本頁只做中文路徑重組和學習順序建議。

## 先按問題選入口

| 你現在要做什麼 | 進入哪組 | 先看哪一頁 |
| --- | --- | --- |
| 第一次安裝和啟動 | 入門 | [入門](/zh-Hant/docs/opencode/official/00-getting-started) |
| 只想知道 TUI 怎麼操作 | 入門 | [使用 TUI](/zh-Hant/docs/opencode/official/00-getting-started/tui) |
| 想把配置寫進專案 | 個性化 | [配置 OpenCode](/zh-Hant/docs/opencode/official/01-customization/config) |
| 想沉澱重複任務 | 個性化 | [建立自定義命令](/zh-Hant/docs/opencode/official/01-customization/commands) |
| 想拆角色或專用 agent | Agents & Skills | [配置 Agents](/zh-Hant/docs/opencode/official/02-agents-skills/agents) |
| 想接外部系統 | 工具與 MCP | [連線 MCP 伺服器](/zh-Hant/docs/opencode/official/04-tools-mcp/mcp-servers) |
| 想控制讀寫和命令許可權 | 安全與網路 | [管理許可權](/zh-Hant/docs/opencode/official/05-security/permissions) |
| 想把 OpenCode 接進團隊流程 | 整合 / SDK & 服務 | [接入 GitHub](/zh-Hant/docs/opencode/official/06-integrations/github) 或 [使用 SDK](/zh-Hant/docs/opencode/official/07-sdk/sdk) |

## 閱讀順序建議

第一次學習按這個順序走，不要直接跳到 plugin 或 SDK：

1. [入門](/zh-Hant/docs/opencode/official/00-getting-started)：安裝、provider、TUI、IDE、分享。
2. [個性化](/zh-Hant/docs/opencode/official/01-customization/config)：配置檔案、快捷鍵、主題、自定義命令。
3. [Agents & Skills](/zh-Hant/docs/opencode/official/02-agents-skills/agents)：agent、skill、plugin、rules 的職責邊界。
4. [模型與供應商](/zh-Hant/docs/opencode/official/03-models/models)：先理解 provider/model，再考慮預設模型和備用模型。
5. [工具與 MCP](/zh-Hant/docs/opencode/official/04-tools-mcp/tools)：先掌握內建工具，再擴充套件 MCP、LSP、formatter 和 custom tools。
6. [安全與網路](/zh-Hant/docs/opencode/official/05-security/permissions)：真實專案使用前必須回頭檢查許可權、網路和分享。

> [!IMPORTANT]
> **不要只看能做什麼**：OpenCode 的危險點也來自“能做什麼”。凡是涉及 `edit`、`bash`、`webfetch`、`websearch`、MCP 寫操作、分享會話，都應該同時查許可權和安全頁面。

## 完整目錄

### 入門

- [入門](/zh-Hant/docs/opencode/official/00-getting-started)
- [使用 CLI](/zh-Hant/docs/opencode/official/00-getting-started/cli)
- [使用 TUI](/zh-Hant/docs/opencode/official/00-getting-started/tui)
- [連線 IDE](/zh-Hant/docs/opencode/official/00-getting-started/ide)
- [分享會話](/zh-Hant/docs/opencode/official/00-getting-started/share)

入門階段只驗證三件事：命令能啟動、provider 能連線、OpenCode 能在一個真實專案裡完成只讀解釋。先不要讓它大範圍改程式碼。

### 個性化

- [切換主題](/zh-Hant/docs/opencode/official/01-customization/themes)
- [配置快捷鍵](/zh-Hant/docs/opencode/official/01-customization/keybinds)
- [建立自定義命令](/zh-Hant/docs/opencode/official/01-customization/commands)
- [配置 OpenCode](/zh-Hant/docs/opencode/official/01-customization/config)

個性化不是換皮膚那麼簡單。真正有長期價值的是把預設模型、許可權、instructions、commands、agents、MCP 和 formatter 放到合適的配置層級。

### Agents & Skills

- [配置 Agents](/zh-Hant/docs/opencode/official/02-agents-skills/agents)
- [使用 Agent Skills](/zh-Hant/docs/opencode/official/02-agents-skills/skills)
- [安裝外掛](/zh-Hant/docs/opencode/official/02-agents-skills/plugins)
- [編寫規則](/zh-Hant/docs/opencode/official/02-agents-skills/rules)

這一組最容易混淆。可以先記住一句話：rules 是專案長期約定，commands 是重複任務入口，agents 是角色和許可權邊界，skills 是可複用能力包，plugins 是執行時擴充套件。

### 模型與供應商

- [選擇模型](/zh-Hant/docs/opencode/official/03-models/models)
- [配置模型供應商](/zh-Hant/docs/opencode/official/03-models/providers)

OpenCode 的多模型能力適合做任務分層：輕量解釋用低成本模型，跨檔案修改用更強模型，安全和釋出相關任務必須保留人工確認。

### 工具與 MCP

- [連線 MCP 伺服器](/zh-Hant/docs/opencode/official/04-tools-mcp/mcp-servers)
- [建立自定義工具](/zh-Hant/docs/opencode/official/04-tools-mcp/custom-tools)
- [管理工具](/zh-Hant/docs/opencode/official/04-tools-mcp/tools)
- [連線 LSP 伺服器](/zh-Hant/docs/opencode/official/04-tools-mcp/lsp)
- [配置格式化工具](/zh-Hant/docs/opencode/official/04-tools-mcp/formatters)

先用內建工具跑通讀檔案、改檔案、執行測試和檢視 diff，再接 MCP。工具越多，許可權和誤操作風險越高。

### 安全與網路

- [管理許可權](/zh-Hant/docs/opencode/official/05-security/permissions)
- [配置網路](/zh-Hant/docs/opencode/official/05-security/network)

安全頁面不是最後才看的附錄。只要 OpenCode 能讀寫儲存庫、執行命令、聯網或分享會話，就應該先定義許可權邊界。

### 整合

- [接入 GitHub](/zh-Hant/docs/opencode/official/06-integrations/github)
- [接入 GitLab](/zh-Hant/docs/opencode/official/06-integrations/gitlab)
- [瞭解生態系統](/zh-Hant/docs/opencode/official/06-integrations/ecosystem)
- [配置企業版](/zh-Hant/docs/opencode/official/06-integrations/enterprise)

整合類頁面適合已經有團隊流程的人讀。個人上手階段不需要一開始就接 GitHub/GitLab 自動化。

### SDK & 服務

- [使用 SDK](/zh-Hant/docs/opencode/official/07-sdk/sdk)
- [啟動伺服器](/zh-Hant/docs/opencode/official/07-sdk/server)
- [在 Web 中使用 OpenCode](/zh-Hant/docs/opencode/official/07-sdk/web)

SDK 和 server 說明 OpenCode 不只是終端工具，也能作為服務能力被嵌入系統。但這部分維護成本更高，先確認普通 TUI 工作流穩定，再進入這一層。

### 平臺與故障

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

平臺差異和故障排查最好按症狀查。Windows 使用者優先看 WSL；provider 不穩定或不想自己篩模型時，看 Zen；IDE/協議整合再看 ACP。

## 接下來去哪

<Cards>
  <Card title="從原理到實戰" description="理解這些官方功能為什麼這樣分層，以及真實專案裡怎麼長期使用。" href="/zh-Hant/docs/opencode/understanding" />
  <Card title="安裝、連線模型與第一次執行" description="已經準備動手時，從第一天安全閉環開始。" href="/zh-Hant/docs/opencode/understanding/02-install-first-run" />
  <Card title="安全、分享與團隊使用" description="準備接真實專案時，先補許可權、金鑰、分享和團隊邊界。" href="/zh-Hant/docs/opencode/understanding/08-security-share-team" />
  <Card title="OpenCode 中文教程" description="回到總入口，在官方查詢和理解路線之間切換。" href="/zh-Hant/docs/opencode" />
</Cards>
