---
title: "02 · 安裝、連線模型與第一次執行"
description: "從安裝 OpenCode 到連線 provider、啟動 TUI，並完成第一輪只讀和低風險寫入。"
verifiedAt: "2026-05-09"
---

第一次使用 OpenCode，不要急著讓它重構專案。它進入真實儲存庫後會讀檔案、改檔案、跑命令、調外部模型——任何一項失控都可能毀掉一上午的工作。所以你的目標只有一個：確認這臺機器上的 OpenCode 能被你約束住，並完成一輪可控任務。

> [!NOTE]
> **這一篇用 15 分鐘換什麼**：不是“裝上就算完”，而是拿到一個可復現的上手閉環。命令能跑、provider 能連、專案能讀、改動能控、失敗能定位，才算真正完成第一次執行。

## 先給結論：第一天只跑安全閉環

第一天不要研究所有配置，也不要把 MCP、Plugin、Agent、Skill 一次性全開。先跑完這條鏈路：

```mermaid
flowchart LR
  Terminal["現代終端"] --> Install["安裝 opencode"]
  Install --> Check["opencode --help"]
  Check --> Provider["/connect 或 auth login"]
  Provider --> Project["進入真實 Git 儲存庫"]
  Project --> Init["/init 生成 AGENTS.md 初稿"]
  Init --> Read["只讀解釋專案"]
  Read --> Write["限定單檔案寫入"]
  Write --> Review["檢查 diff / 撤銷能力"]

  style Check fill:#dbeafe,stroke:#3b82f6
  style Read fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Write fill:#fef3c7,stroke:#f59e0b
  style Review fill:#fee2e2,stroke:#ef4444
```

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

## 1. 安裝前先準備兩樣東西

OpenCode 是 coding agent（編碼代理），不是普通聊天網頁。它會進入你的終端、讀取專案檔案、呼叫模型供應商、執行 shell 命令。安裝前至少準備：

- **現代終端**：OpenCode 預設在終端裡跑出一套 TUI（terminal UI，文本介面），需要終端支援高色彩、滑鼠捕獲、複雜字元佈局，普通系統自帶終端常會錯位。官方推薦 WezTerm、Alacritty、Ghostty、Kitty，任選一個。
- **模型供應商 API key**：OpenCode 自己**不內建模型**，每次提問都要發給你選的 provider（Anthropic、OpenAI、Google、xAI 等）的 API；離線不能用，必須先有可用的 key。

> [!IMPORTANT]
> 金鑰只進入 OpenCode 的憑據系統，不寫進專案檔案、不進 Git。第一次連線 provider 用 `/connect` 或 `opencode auth login`。專案配置裡只寫"用哪個 provider 哪個 model"的策略，不寫真實 API key——一旦寫進專案檔案，下一次 `git commit` 很可能把它推上公開倉。

## 2. 安裝 OpenCode

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

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

macOS / Linux 使用者也可以用官方 Homebrew tap，比官方 brew formula 更新更快：

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

如果你已經裝了 Node.js，可以用 npm 全域性安裝：

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

Windows 可以直接裝（官方還提供 chocolatey、scoop、mise、docker 多種選擇，詳見 [Windows 使用說明](/zh-Hant/docs/opencode/official/08-platform/windows-wsl)），但 coding agent 重度依賴 shell、Git、語言工具鏈、檔案系統和許可權——多數開源專案預設假設的是 Linux 開發環境，Windows native 容易在路徑分隔符、行尾符、許可權模型上踩坑。**第一次學習強烈建議優先裝 WSL 再裝 OpenCode**，比一邊學新工具一邊修 Windows 相容問題省心得多。

## 3. 先驗證命令，不要直接改專案

安裝後先查幫助或版本：

```bash
opencode --help
opencode --version
```

如果命令不存在，先檢查 PATH，不要馬上換安裝方式：

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

常見原因通常是 shell 沒重新整理、Node 全域性 bin 不在 PATH、Homebrew 路徑沒載入，或者終端開的是舊 session。

> [!TIP]
> 先排環境，再排 OpenCode。安裝失敗很多時候不是 OpenCode 本身壞了，而是當前 shell 找不到新裝的執行檔。

## 4. 連線模型 provider

連線 provider 有兩條路徑，新手任選一條：

**路徑 A：先在 OS 終端用 CLI 配（推薦）**

```bash
opencode auth login    # 走交互向导：选 provider、粘贴 API key、保存到本机
opencode auth list     # 验证已保存的 provider
```

`auth login` 在你的普通 shell（zsh / bash / PowerShell）裡跑，跑完就退出。這是新手最穩的方式——不必先理解 TUI。

**路徑 B：先啟動 TUI 再用 `/connect`**

```bash
cd /path/to/project    # 进入任意项目目录
opencode               # 启动 OpenCode TUI（界面进入"已切换"的全屏交互模式）
```

進入 TUI 後，在輸入框裡直接打：

```text
/connect
```

OpenCode 會彈出 provider 選擇選單，引導你完成認證。

---

兩條路徑分工：

- `auth login`（OS shell）：第一次配憑據 + 後續 `auth list` 複查 + 自動化 / CI 場景。
- `/connect`（TUI 裡）：已經在用 OpenCode 時隨時加 provider，不用退出會話。
- 環境變數或 `.env`：已經有統一憑據管理（如 1Password CLI、direnv、內部 secret manager）的人。
- 專案配置 `opencode.json`：只寫團隊模型策略，**絕對不寫真實 API key**。

如果 provider 連線失敗，先查 API key、賬單狀態、網路代理、provider 可用性和模型許可權，不要直接認定 OpenCode 壞了。

## 5. 進入真實 Git 儲存庫

不要在桌面空目錄裡測試。OpenCode 是 coding agent，最小驗證應該發生在真實專案裡。

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

也可以直接指定專案路徑：

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

第一次進入專案後，執行：

```text
/init
```

`/init` 會分析專案並生成 `AGENTS.md` 初稿。它適合寫專案結構、編碼約定、測試命令、常見邊界和禁止修改範圍。

> [!WARNING]
> `/init` 生成的是初稿，不是最終規範。提交前要人工看一遍，尤其是包管理器、測試命令、部署命令、生成物目錄和敏感目錄。

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

第一次任務不要讓 OpenCode 改檔案。先驗證它能不能正確讀專案。

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

這條提示詞同時做三件事：明確“不要修改檔案”，驗證它是否讀到真實目錄結構，並要求它暴露不確定性。

如果它第一輪就開始改檔案，先停下來檢查模式、提示詞和許可權，不要繼續進入複雜任務。

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

只讀任務穩定後，再做一個低風險寫入。不要選“重構整個專案”，選 README、文件或測試說明這類單檔案任務。

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

合格結果應該滿足四點：

- 只改你指定的一個檔案。
- 能說明為什麼這樣改。
- 會建議合理的檢查命令。
- 不會自作主張 commit、push 或部署。

如果 OpenCode 改了無關檔案，先讓它解釋 diff，不要直接繼續下一輪。必要時用 Git 回復當前檔案，再收緊許可權或提示詞。

## 8. 知道怎麼撤銷，才繼續擴大任務

OpenCode 支援撤銷和重做**當前會話產生的本地檔案修改**：

```text
/undo
```

```text
/redo
```

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

> [!CAUTION]
> `/undo` 只能撤回當前會話改過的本地檔案 + 重新顯示你上一條 prompt——它**不會**回復已經 `git commit` / `git push` 的內容、不會撤銷已經跑過的資料庫遷移、不會撤銷已經發出的外部服務呼叫。所以"能撤銷"≠ 可以隨便改：資料庫遷移、外部服務、釋出部署、刪除檔案和批次格式化，都要先看計劃和影響範圍。

## 9. `run` 先用於只讀檢查

OpenCode 也支援非互動任務：

```bash
opencode run "Explain the structure of this repository. Do not edit files."
```

`run` 適合指令碼、簡單自動化或 CI 裡的只讀檢查。第一次上手仍建議先用 TUI，因為 TUI 更容易觀察模型行為、工具呼叫、許可權提示和上下文壓縮。

`run` 命令有一個 `--dangerously-skip-permissions` flag——它會自動批准所有非顯式拒絕的許可權請求（官方原文："dangerous!"）。第一次學習時**永遠不要**用這個 flag，哪怕只是想"跑得快一點"。沒有許可權提示的 agent 在真實儲存庫裡就是無監督，刪錯檔案、跑壞資料庫都來不及看見。

## 10. 常見卡點按層級排

- `opencode` 找不到：查 `which opencode`、PATH、終端是否重開。
- TUI 顯示異常：換現代終端，檢查字型、快捷鍵和終端能力。
- provider 連線失敗：查 API key、賬單、網路、代理、provider 許可權。
- 讀不到專案：確認當前目錄、Git 儲存庫、檔案許可權和忽略規則。
- 一上來亂改檔案：收緊提示詞、模式和 permission。
- Windows 路徑或 shell 異常：優先切到 WSL 環境再試。

排障順序不要反過來。先確認本機命令、路徑、provider，再看 OpenCode 配置。

## 本章自檢

過關前先回答這些問題：

- 第一次啟動 OpenCode 前，需要準備哪兩類東西？
- 為什麼第一輪任務應該只讀，而不是直接讓它改程式碼？
- `/connect`、`opencode auth login`、專案配置分別適合什麼場景？
- 第一輪低風險寫入為什麼只改單檔案？
- 如果它改了無關檔案，你應該先看什麼？

過關標準：你能在一個真實 Git 儲存庫裡啟動 OpenCode，連線 provider，讓它只讀解釋專案結構，再完成一個限定單檔案的低風險修改。

## 接下來去哪

<Cards>
  <Card title="終端 TUI 工作流" description="繼續學習 `@` 檔案引用、`!` shell 命令、`/` 斜槓命令和會話控制。" href="/zh-Hant/docs/opencode/understanding/03-terminal-workflow" />
  <Card title="CLI 入口" description="查 `run`、`auth`、`models`、`serve`、`mcp` 等命令的邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/cli" />
  <Card title="入門官方整理" description="回到官方路徑版，按安裝、provider、初始化、低風險寫入完整複查。" href="/zh-Hant/docs/opencode/official/00-getting-started" />
  <Card title="配置與規則" description="跑通第一輪後，再把專案約束沉澱到 rules、commands 和 AGENTS.md。" href="/zh-Hant/docs/opencode/understanding/04-config-rules-commands" />
</Cards>

## 官方資料

- OpenCode 入門：[https://opencode.ai/docs](https://opencode.ai/docs)
- OpenCode CLI：[https://opencode.ai/docs/cli](https://opencode.ai/docs/cli)
- Windows 使用說明：[https://opencode.ai/docs/windows-wsl](https://opencode.ai/docs/windows-wsl)
- 配置說明：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
