前言

如果你最近混程式圈，應該聽過 OpenCode 這名字。這個開源 AI coding agent 在 GitHub 上已經突破了 17 萬顆星，被譽為「終端機裡最強的人工智慧程式助手」。

簡單來說，OpenCode 讓你用自然語言跟 AI 對話，它就能幫你讀程式碼、寫功能、修 bug、做 code review——而且一切發生在你熟悉的終端機介面裡。

對於 Windows 使用者來說，OpenCode 的安裝方式有幾種選擇，官方也建議使用 WSL（Windows Subsystem for Linux）來獲得最佳體驗。但這篇文章就是要從零開始，帶你一步步把 OpenCode 裝好、設定好、跑起來。

不管你是完全沒碰過 terminal 的小白，還是想嘗試新工具的開發者，這篇都會讓你一次上手。

- 廣告 -

什麼是 OpenCode？為什麼值得裝？

在深入安裝之前，先簡單認識一下 OpenCode 到底是什麼。

OpenCode 是一個開源的 AI coding agent，由 Anomaly Co 開發。它提供三種使用方式：

  • TUI（Terminal User Interface）：在終端機裡用文字介面跟 AI 互動，這也是這篇文章的重點
  • Desktop App：桌面應用程式，適合不想碰 terminal 的用戶
  • IDE Extension：作為 IDE 擴充功能使用

它的核心特色是「雙 Agent 架構」：

  • build agent（預設）：擁有完整存取權，可以讀寫檔案、執行 bash 指令，適合開發工作
  • plan agent：唯讀模式，不會修改檔案，適合探索陌生程式碼或做規劃

還有內建的 general subagent，可以用 @general 呼叫，處理複雜的多步驟任務。

為什麼 Windows 使用者值得裝？因為 OpenCode 支援的 LLM provider 超多——OpenAI、Anthropic、OpenRouter、Ollama、Google Vertex AI……總共 30 多家。你可以自由選擇用哪家的模型，甚至本地跑的 Ollama 也支援。

安裝前的準備

在開始安裝之前，你需要準備兩樣東西：

1. 一個現代化的終端機模擬器

OpenCode 在終端機裡運作，所以你需要一個支援良好的終端機。官方推薦的有：

  • Windows Terminal（Windows 預設，推薦新手使用）
  • WezTerm：跨平台，功能強大
  • Alacritty：跨平台，速度快

如果你還沒裝過 Windows Terminal，去 Microsoft Store 搜尋「Windows Terminal」就能免費安裝。這是目前 Windows 上最推薦的終端機。

2. 一個 LLM 的 API Key

OpenCode 本身是開源的，但背後需要呼叫 LLM（大型語言模型）來產生回應。你需要至少一個 LLM provider 的 API Key。

幾個比較實用的選擇：

  • OpenRouter（推薦新手）：一個 API 同時使用多家模型，註冊就送一些免費額度
  • OpenAI：需要 gpt-4 或更新的模型，API Key 在 platform.openai.com 申請
  • Anthropic：Claude 系列的提供者，API Key 在 console.anthropic.com 申請
  • Ollama（免費）：在本地電腦跑開源模型，完全免費但需要較好的硬體

對於新手，我最推薦用 OpenRouter。它的優點是：

  • 註冊就送 $5 免費額度
  • 一個 API Key 可以用多家模型（Claude、GPT、Gemini 等）
  • 費用按 token 計費，用多少付多少
  • 設定簡單，只需要設一個環境變數

安裝方法一：WSL（官方推薦）

官方建議 Windows 使用者使用 WSL（Windows Subsystem for Linux），因為它能提供最佳效能和完整的功能相容性。

步驟 1：安裝 WSL

以管理員身分開啟 PowerShell，輸入：

wsl --install

安裝完成後重啟電腦。重啟後會自動安裝 Ubuntu 發行版，設定你的 Linux 使用者名稱和密碼。

如果你想要選特定的發行版（比如 Ubuntu 24.04），可以輸入：

wsl --install -d Ubuntu-24.04

步驟 2：在 WSL 裡安裝 OpenCode

進入 WSL 後，使用 OpenCode 官方的安裝腳本：

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

這個腳本會自動下載並安裝 OpenCode 到合適的位置。安裝完成後，輸入：

opencode --version

如果看到版本號碼，代表安裝成功。

步驟 3：設定 API Key

如果你用的是 OpenRouter，在 WSL 終端機輸入：

export OPENROUTER_API_KEY=你的_api_key

如果要永久生效，把這行加到 ~/.bashrc：

echo 'export OPENROUTER_API_KEY=你的_api_key' >> ~/.bashrc
source ~/.bashrc

如果你用的是 Anthropic 的 Claude，就設 ANTHROPIC_API_KEY；OpenAI 的就設 OPENAI_API_KEY。

步驟 4：開始使用

輸入以下指令啟動 OpenCode：

opencode

就會進入 OpenCode 的 TUI 介面。現在你可以跟 AI 對話了！

安裝方法二：Scoop（Windows 原生）

如果你不想用 WSL，也可以用 Scoop 在原生 Windows 上安裝 OpenCode。

步驟 1：安裝 Scoop

以管理員身分開啟 PowerShell，輸入：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://get.scoop.sh | iex

步驟 2：安裝 OpenCode

scoop bucket add extras
scoop install extras/opencode

步驟 3：設定 API Key

在 PowerShell 裡設定環境變數（永久生效）：

[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "你的_api_key", "User")

然後重新開啟 PowerShell 讓設定生效。

步驟 4：開始使用

opencode

安裝方法三：npm / bun / pnpm（Node.js 使用者）

如果你電腦上已經裝了 Node.js 或 Bun，也可以用套件管理器安裝：

# npm
npm install -g opencode-ai

# bun
bun install -g opencode-ai

# pnpm
pnpm add -g opencode-ai

安裝完成後一樣需要設定 API Key，然後輸入 opencode 啟動。

桌面版（Desktop App）

如果你完全不想碰 terminal，OpenCode 也提供了桌面應用程式：

  • Windows：到 GitHub Releases 下載 opencode-desktop-windows-x64.exe
  • macOS：下載 .dmg 檔案
  • Linux：提供 .deb、.rpm 或 .AppImage

桌面版跟 TUI 版功能基本一致，只是介面更友善。

第一次使用 OpenCode

安裝完成後，讓我們來試試看 OpenCode 能做什麼。

基礎對話

啟動 OpenCode 後，你會看到一個終端機介面。直接在提示符號後輸入你的問題：

Give me a quick summary of the codebase.

OpenCode 會分析目前目錄下的程式碼，給你一個概覽。

用 @ 附加檔案

OpenCode 支援用 @ 來附加檔案。比如你想讓它幫你檢查某個檔案：

How is auth handled in @config.yaml?

它會自動讀取 config.yaml 的內容，並根據內容回答你的問題。

切換 Agent

在 TUI 裡按 Tab 鍵可以在 build 和 plan agent 之間切換。

  • build agent：可以修改檔案、執行指令，適合寫程式
  • plan agent：唯讀模式，適合分析程式碼

常用快捷鍵

在 TUI 介面中，這些快捷鍵很實用：

  • Enter：送出訊息（有時需要按兩次）
  • Tab：切換 agent（build / plan）
  • Ctrl + P：開啟命令面板
  • Ctrl + X M：切換模型
  • Ctrl + X N：建立新對話
  • Ctrl + C：離開 OpenCode

用 opencode run 做一次性任務

如果你只想讓 OpenCode 做一件簡單的事，可以用 run 指令：

opencode run "Add retry logic to the API calls"

這會執行完就離開，不需要進入 TUI 介面。

常見問題

Q：安裝後輸入 opencode 沒反應？

確認 API Key 已經正確設定：

echo $OPENROUTER_API_KEY

如果輸出是空的，代表環境變數沒設好。重新設定後重啟終端機。

Q：WSL 和原生 Windows 裝哪一個比較好？

WSL 的優勢：

  • 效能更好（OpenCode 是基於 Linux 開發的）
  • 功能完整（所有功能都支援）
  • 跟 macOS / Linux 開發環境一致

原生 Windows 的優勢：

  • 不需要裝 WSL
  • 直接用 PowerShell 操作
  • 適合純 Windows 開發者

如果你是初學者，建議先用 WSL 版，體驗最好。

Q：可以免費用嗎？

OpenCode 本身是免費開源的。費用來自你使用的 LLM provider：

  • Ollama：完全免費（本地模型）
  • OpenRouter：註冊送 $5，之後按用量計費
  • OpenAI / Anthropic：按 token 計費，一般開發者每月幾美元就夠了

Q：Windows 10 可以用嗎？

可以。只要你的 Windows 10 版本夠新（建議 20H2 以上），WSL 就能正常運作。

小結

這篇帶你從零開始，在 Windows 上安裝和設定 OpenCode。不管你是用 WSL、Scoop 還是 npm，核心步驟都是：

  1. 安裝 OpenCode
  2. 設定 API Key
  3. 啟動 opencode 開始使用

OpenCode 的學習曲線其實很低——只要你會打字、會輸入自然語言，就能用它來寫程式。對於 Windows 開發者來說，這是一個非常值得嘗試的工具。

下一篇文章我會寫一篇進階的「OpenCode 必設設定，效能直接翻倍」，介紹 config.jsonc 裡的各種進階設定，敬請期待！

- 廣告 -

💡 小提醒：OpenCode 更新很快，建議定期用 opencode update 或 brew upgrade 保持最新版本。如果安裝時遇到問題，也可以到 OpenCode Discord 社群尋求協助。