入門

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

先跑通安全閉環

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

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，通常可以直接開始。

2. 安裝 OpenCode

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

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：

brew install anomalyco/tap/opencode

Node.js 使用者最常用 npm：

npm install -g opencode-ai

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

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

opencode --help

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

which opencode
echo $PATH

3. 連線模型 provider

啟動 TUI 後輸入：

/connect

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

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

opencode auth login
opencode auth list

兩種方式的區別很簡單：

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

4. 在真實專案裡初始化

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

cd /path/to/project
opencode

然後執行：

/init

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

5. 第一輪只做只讀任務

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

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

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

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

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

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

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

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

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

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

合格結果應該滿足四點：

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

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

7. 會撤銷，才算能繼續

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

/undo

/redo

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

8. 分享預設手動觸發

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

/share

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

9. 繼續做個性化配置

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

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

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

接下來去哪

官方資料

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