---
title: "入門"
description: "彙總 OpenCode 入門路徑，按 CLI、TUI、分享和 IDE 入口建立第一條可執行閉環。"
verifiedAt: "2026-05-09"
---

OpenCode 入門不是把所有安裝命令背一遍，而是在一臺真實開發機器上跑通第一條安全閉環：能啟動、能連線模型、能讀專案、能受控修改、能撤銷、知道下一步該配置什麼。

<img
  src="/images/opencode/tui-screenshot.png"
  alt="使用 opencode 主題的 OpenCode TUI"
  width="1824"
  height="1488"
  loading="eager"
/>

> [!NOTE]
> **這一篇用 15 分鐘換什麼**：不是“裝上就算完”，而是拿到一條可復現的第一天路徑。跑完以後，你應該能在真實 Git 儲存庫裡讓 OpenCode 完成一次只讀分析和一次限定範圍的低風險修改。

## 先跑通安全閉環

第一次使用 OpenCode，不要先研究 plugin、MCP、LSP 或團隊治理。先按下面順序確認基礎能力。

```mermaid
flowchart LR
    Terminal["現代終端"] --> Install["安裝 opencode"]
    Install --> Provider["連線 provider"]
    Provider --> Project["進入真實 Git 儲存庫"]
    Project --> Init["/init 生成 AGENTS.md 初稿"]
    Init --> ReadOnly["第一輪只讀分析"]
    ReadOnly --> WriteSmall["第一輪限定寫入"]
    WriteSmall --> Undo["確認 /undo 和 /redo"]
    Undo --> Next["進入個性化配置"]

    style Terminal fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
    style ReadOnly fill:#dcfce7,stroke:#22c55e
    style WriteSmall fill:#fef3c7,stroke:#f59e0b
    style Undo fill:#fee2e2,stroke:#ef4444
```

這條路徑故意保守。Coding agent 會讀取檔案、修改檔案、執行命令和呼叫外部模型。先證明它能被約束，再擴大任務範圍。

## 1. 準備終端和模型金鑰

要在終端裡使用 OpenCode，你至少需要兩樣東西：

- **現代終端**：TUI 顯示、快捷鍵、拖放圖片、互動輸入都依賴終端能力。
- **LLM provider API key**：OpenCode 是 agent 執行時，推理仍由模型 provider 提供。

官方文件列出的現代終端包括 WezTerm、Alacritty、Ghostty 和 Kitty。macOS 或 Linux 使用者如果已經在用 Ghostty、WezTerm 或 iTerm2，通常可以直接開始。

> [!IMPORTANT]
> **金鑰只進入憑據系統，不進入專案檔案**：第一次上手用 `/connect` 或 `opencode auth login` 連線 provider。專案裡的 `AGENTS.md`、rules、commands 和配置檔案只寫工作流約束，不寫真實 API key。

## 2. 安裝 OpenCode

官方最直接的安裝方式是安裝指令碼：

```bash
curl -fsSL https://opencode.ai/install | bash
```

如果你偏好包管理器，可以選更符合當前機器的方式。

- **macOS / Linux**：`brew install anomalyco/tap/opencode` 或安裝指令碼。
- **Node.js 環境**：`npm install -g opencode-ai`。
- **Windows**：優先 WSL，再考慮 Chocolatey、Scoop、npm、Mise、Docker 或 release binary。
- **Arch Linux**：`sudo pacman -S opencode` 或 AUR 的 `opencode-bin`。

Homebrew 使用者優先使用 OpenCode 官方 tap：

```bash
brew install anomalyco/tap/opencode
```

Node.js 使用者最常用 npm：

```bash
npm install -g opencode-ai
```

Windows 可以直接裝，但 coding agent 對 shell、Git、語言工具鏈和檔案許可權依賴很重。第一次學習建議用 WSL，這樣更接近多數開源專案預設假設的 Linux 開發環境。

安裝後先驗證命令，不要馬上進入專案改程式碼：

```bash
opencode --help
```

如果命令找不到，先查 PATH 和安裝位置：

```bash
which opencode
echo $PATH
```

## 3. 連線模型 provider

啟動 TUI 後輸入：

```txt
/connect
```

第一次可以選擇 OpenCode Zen，按照頁面提示前往 `opencode.ai/auth` 登入、新增賬單資訊並複製 API key。OpenCode 也支援其他 provider，後續可以在 provider 目錄裡選擇。

如果你更喜歡 CLI 管理憑據，也可以使用：

```bash
opencode auth login
opencode auth list
```

兩種方式的區別很簡單：

- `/connect` 適合第一次在 TUI 裡跑通。
- `opencode auth login` 適合在終端裡管理和複查 provider 憑據。
- `.env` 或環境變數適合已經有統一憑據管理的人。

> [!WARNING]
> **不要把 provider 連線失敗當成 OpenCode 壞了**：先確認 API key、賬單狀態、網路代理、provider 可用性，再排查 OpenCode 配置。

## 4. 在真實專案裡初始化

配置好 provider 後，進入你真正要處理的專案目錄。

```bash
cd /path/to/project
opencode
```

然後執行：

```txt
/init
```

OpenCode 會分析專案並生成專案根目錄的 `AGENTS.md` 初稿。這個檔案應該提交到 Git，因為它是團隊共享專案上下文的入口，適合寫專案結構、包管理器、測試命令、編碼約定、禁止修改範圍和釋出邊界。

> [!IMPORTANT]
> **`/init` 不是最終規範**：它生成的是初稿。提交前必須人工檢查，尤其是測試命令、部署命令、敏感目錄、生成物目錄和“哪些檔案不能改”。

## 5. 第一輪只做只讀任務

第一次任務不要讓 OpenCode 改檔案。先驗證它能不能正確理解儲存庫。

```txt
先快速阅读这个仓库的目录结构，不要修改文件。
请按这四点输出：
1. 项目的技术栈和入口文件。
2. 主要模块分别做什么。
3. 你会优先阅读哪些文件来理解项目。
4. 你现在还不确定、需要我确认的问题。
```

這條提示詞同時做三件事：

- 限制動作：明確“不要修改檔案”。
- 驗證上下文：看它是否真的讀到了專案結構。
- 暴露不確定性：要求它說出不知道的地方。

需要引用具體檔案時，按 `@` 模糊搜尋檔案：

```txt
How is authentication handled in @packages/functions/src/api/index.ts
```

如果第一輪只讀任務就開始改檔案，先停下來檢查模式、提示詞和許可權，不要繼續擴大任務範圍。

## 6. 第一輪寫入只改單檔案

只讀任務穩定後，再做一個低風險寫入。優先選擇 README、文件或測試說明，不要上來重構核心模組。

```txt
只修改 README.md 中的安装说明，把命令整理成 macOS、Linux、Windows 三段。
不要修改其他文件。
改完后先解释 diff，再告诉我建议运行什么检查命令。
```

合格結果應該滿足四點：

- 只改你指定的檔案。
- 能解釋具體 diff。
- 能給出合理的驗證命令。
- 不會自作主張 commit、push 或部署。

如果任務稍複雜，先按 **Tab** 切到 Plan mode，讓 OpenCode 只給計劃；計劃確認後再按 **Tab** 回到 Build mode 執行。這個動作比“事後回復一堆無關檔案”成本低得多。

## 7. 會撤銷，才算能繼續

OpenCode 支援撤銷和重做當前會話產生的修改：

```txt
/undo
```

```txt
/redo
```

第一次低風險寫入後，至少確認你知道這兩個命令的用途。真正進入大範圍修改前，還要配合 Git diff 檢視檔案邊界。

> [!TIP]
> **能撤銷不等於可以隨便改**：`/undo` 適合修正當前會話裡的不滿意結果。涉及資料庫遷移、外部服務、釋出部署、刪除檔案和批次格式化時，仍然要先看計劃和影響範圍。

## 8. 分享預設手動觸發

OpenCode 會話可以透過 `/share` 生成分享連結：

```txt
/share
```

對話預設不會自動分享。分享前要確認當前會話裡沒有金鑰、賬號、客戶資料、內部路徑、未公開儲存庫資訊或商業策略。敏感專案寧願不分享，也不要事後補救。

## 9. 繼續做個性化配置

跑通第一輪以後，再進入個性化配置：

- 主題和 keybinds：讓 TUI 更順手。
- rules 和 `AGENTS.md`：沉澱專案規則。
- commands：把重複提示詞變成 slash command。
- formatters：把格式化交給確定性工具。
- agents、skills、plugins、MCP：把複雜能力拆到更清晰的邊界裡。

不要把這些配置一次性全開。每次只加一種能力，並用真實任務驗證它是否減少了重複溝通或降低了出錯機率。

## 接下來去哪

<Cards>
  <Card title="CLI 入口" description="查 `run`、`auth`、`serve`、`mcp`、`session`、`plugin` 等命令邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/cli" />
  <Card title="TUI 工作流" description="學習 `@` 檔案引用、shell 命令、模式切換、會話管理和快捷鍵。" href="/zh-Hant/docs/opencode/official/00-getting-started/tui" />
  <Card title="OpenCode Zen" description="第一次不知道選什麼模型時，先理解 Zen 的 provider、模型 ID 和計費邊界。" href="/zh-Hant/docs/opencode/official/08-platform/zen" />
  <Card title="Rules" description="把專案約束寫進 `AGENTS.md` 和 rules，避免每次從零提醒 agent。" href="/zh-Hant/docs/opencode/official/02-agents-skills/rules" />
</Cards>

## 官方資料

- OpenCode 入門：[https://opencode.ai/docs](https://opencode.ai/docs)
- OpenCode CLI：[https://opencode.ai/docs/cli](https://opencode.ai/docs/cli)
- Windows / WSL：[https://opencode.ai/docs/windows-wsl](https://opencode.ai/docs/windows-wsl)
- OpenCode Zen：[https://opencode.ai/docs/zen](https://opencode.ai/docs/zen)
