02 · 安裝、連線模型與第一次執行

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

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

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

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。

2. 安裝 OpenCode

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

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

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

brew install anomalyco/tap/opencode

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

npm install -g opencode-ai

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

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

安裝後先查幫助或版本：

opencode --help
opencode --version

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

which opencode
echo $PATH

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

4. 連線模型 provider

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

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

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

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

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

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

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

/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，最小驗證應該發生在真實專案裡。

cd /path/to/project
opencode

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

opencode /path/to/project

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

/init

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

6. 第一輪只做只讀任務

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

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

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

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

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

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

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

合格結果應該滿足四點：

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

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

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

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

/undo

/redo

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

9. run 先用於只讀檢查

OpenCode 也支援非互動任務：

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，讓它只讀解釋專案結構，再完成一個限定單檔案的低風險修改。

接下來去哪

官方資料

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