OpenCode 開源 AI Coding Agent 教材

一、什麼是 OpenCode

OpenCode 的定位是 AI 編碼代理。一般聊天式 AI 偏向回答問題；OpenCode 則更重視在程式專案中的實際工作流程，例如：

讀取專案中的多個檔案後再回答問題。
依照需求提出修改方案，並直接產生程式碼。
協助進行 refactor、錯誤追查、測試補強與文件整理。
配合終端機與 Git 工作流程執行較完整的開發任務。

可把 OpenCode 想成「會看專案上下文的程式開發助手」，而不是只能單輪問答的聊天視窗。

二、OpenCode 的主要特色

多介面

Terminal、桌面端、IDE

可在終端機中互動，也可使用桌面應用程式或編輯器整合，適合不同開發習慣。

模型彈性

可接多家 LLM 供應商

可搭配不同 provider / model，不必被單一服務綁定，便於比較成本、速度與品質。

開源

流程透明、易於擴充

由於是開源工具，社群文件、擴充與整合方式較容易追蹤，適合教學與研究觀察。

上下文工作

以專案為單位操作

能根據當前專案結構理解檔案關聯，比單純把片段程式碼貼到聊天視窗更完整。

三、安裝方式

OpenCode 官方提供多種安裝方法，常見方式如下：

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

npm install -g opencode-ai
bun install -g opencode-ai
pnpm install -g opencode-ai
yarn global add opencode-ai

brew install anomalyco/tap/opencode
# 或
brew install opencode

若使用 Windows，通常建議先準備 WSL 環境，再於 Linux 子系統中安裝與使用。

本次更新時，這台維護網站的電腦執行 opencode --version 顯示 command not found，表示若要在本機實作範例，需先完成安裝。

四、OpenRouter 設定方法

如果想讓 OpenCode 透過 OpenRouter 使用 Claude、GPT、Gemini 或其他支援的模型，可以依照下列流程設定：

前往 OpenRouter 控制台建立 API Key。
啟動 opencode 後，於 TUI 中執行 /connect。
搜尋並選擇 OpenRouter。
貼上剛建立的 API Key。
再執行 /models 選擇要使用的模型。

opencode
/connect
/models

依照 OpenCode 官方提供商文件，OpenRouter 預設已預先載入許多模型，因此通常只要完成 API Key 連接後，就可以直接在 /models 中挑選模型。

1. 最基本的操作流程

# 先啟動 OpenCode
opencode

# 在 OpenCode 介面中輸入
/connect

# 搜尋 OpenRouter，貼上 API Key 後再輸入
/models

2. 指定 OpenRouter 模型

如果已經完成連線，也可以直接在命令列指定 provider/model：

opencode --model openrouter/anthropic/claude-sonnet-4
opencode run "請解釋目前專案的 Flask 路由結構" --model openrouter/anthropic/claude-sonnet-4

3. 在設定檔中加入更多 OpenRouter 模型

若預設列表中沒有想用的模型，可在 opencode.json 中擴充：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}

4. 自訂模型選項

OpenCode 官方文件也示範可在 OpenRouter 模型下指定更細的 provider 選項：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": {
            "provider": {
              "order": ["baseten"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

5. 驗證是否設定成功

執行 opencode 後，確認 /models 中可看到 OpenRouter 模型。
若安裝了 CLI，可執行 opencode auth list 檢查是否已有 provider 憑證。
若能成功執行一個簡單任務，通常表示連線設定已完成。

opencode auth list
opencode run "Respond with exactly: OPENROUTER_OK" --model openrouter/anthropic/claude-sonnet-4

若出現 provider 驗證失敗、模型不存在、或權限不足，通常要檢查三件事：API Key 是否正確、OpenRouter 帳號是否可用該模型、以及 provider/model 名稱是否寫對。

五、Codex 設定外部 API（OpenAI 相容供應商）

如果想讓 Codex CLI 連到外部 API，而不是只使用預設 OpenAI 端點，可以在 ~/.codex/config.toml 中加入自訂 provider。依 OpenAI Codex 官方文件，這類供應商要以 [model_providers] 定義，並指定 base_url、wire_api、驗證方式與模型名稱。

官方文件特別提醒：model_provider、model_providers、base_url 這類 provider 設定應放在使用者層級的 ~/.codex/config.toml，不要只放在專案內的 .codex/config.toml。

1. 基本設定步驟

先準備外部 API 供應商的 endpoint、可用模型名稱與 API Key。
在終端機設定環境變數，例如 AZURE_OPENAI_API_KEY。
編輯 ~/.codex/config.toml，新增自訂 provider。
指定 model_provider 與 model。
重新啟動 codex 後測試是否可正常回應。

2. Azure / OpenAI 相容 API 範例

以下是 OpenAI Codex 官方文件中的典型寫法，適合拿來連接 Azure OpenAI 或其他 OpenAI 相容端點：

# ~/.codex/config.toml
model_provider = "azure"
model = "gpt-5"

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"
env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"

若供應商不是 Azure，但同樣提供 OpenAI 相容 API，也可以用類似方式調整：

# ~/.codex/config.toml
model_provider = "myproxy"
model = "gpt-5"

[model_providers.myproxy]
name = "My OpenAI-Compatible Provider"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "MY_LLM_API_KEY"
env_key_instructions = "Set MY_LLM_API_KEY in your shell environment"

3. 環境變數設定範例

# zsh / bash
export AZURE_OPENAI_API_KEY="YOUR_KEY_HERE"

# 若要永久生效，可加入 ~/.zshrc 後重新載入
source ~/.zshrc

不要把 API Key 直接硬寫進 config.toml。Codex 官方範例也是以 env_key 搭配環境變數管理金鑰。

4. 另一種情況：透過代理但仍使用 OpenAI 驗證

若外部端點其實是 OpenAI 帳號後面的代理層，官方文件建議改用 requires_openai_auth = true。這種模式下，Codex 會走 OpenAI 驗證流程，且會忽略 env_key。

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

5. 驗證是否設定成功

重新啟動 codex 後，確認已使用新的 model_provider 與模型。
先執行簡單任務，確認外部端點可正常回應。
若失敗，優先檢查 base_url、模型名稱、API Key 環境變數與 query parameter 是否正確。

codex

# 或用單次任務快速測試
codex exec "Respond with exactly: CODEX_EXTERNAL_API_OK"

重點可以記成四件事：設定使用者層級 config、指定 model_provider、用 env_key 管理金鑰、確認外部端點支援 responses API。

六、使用前準備

準備一個現代終端機環境。
準備要使用的模型供應商 API 金鑰。
進入專案資料夾後再啟動 OpenCode，讓它能讀取目前專案結構。
若是團隊作業，建議搭配 Git 分支與 commit 紀錄。

cd /path/to/project
opencode

第一次在專案中使用時，可建立專案規則與說明檔，例如需求摘要、程式規範、目錄用途與測試方式，讓 AI 代理更容易理解工作上下文。

七、兩種常見使用模式

模式	指令	用途
TUI 互動模式	`opencode`	適合逐步對話、反覆追問、邊看結果邊修正需求。
CLI 單次任務	`opencode run "你的任務"`	適合快速執行單一明確工作，例如解釋函式、重構某段程式、檢查錯誤。

opencode
opencode run "Explain how closures work in JavaScript"

如果任務範圍明確，run 模式通常更容易重現與記錄；若需求會持續修正，TUI 模式更方便。

八、實用指令整理

指令	說明
`opencode`	啟動終端機互動介面。
`opencode [project]`	直接在指定專案路徑開啟。
`opencode run "..."`	執行單次任務後結束。
`opencode -c`	延續上一個 session。
`opencode -s <session_id>`	繼續特定 session。
`opencode --model provider/model`	指定要使用的模型。
`opencode session list`	列出既有工作階段。
`opencode stats`	查看使用量或成本統計。

opencode run "請解釋 app.py 中 MQTT callback 的執行流程"
opencode run "重構這個 Python 函式，保留功能但提升可讀性"
opencode --model openrouter/anthropic/claude-sonnet-4
opencode session list
opencode stats

九、在 IoT / Web 課程中的應用情境

程式理解

閱讀既有專題

請 OpenCode 解釋 Raspberry Pi GPIO、Flask route、MQTT publisher/subscriber 或 SQL 查詢流程。

除錯

分析錯誤訊息

可把 Traceback、伺服器 log 或錯誤輸出交給 OpenCode，請它協助定位問題來源與修正方向。

原型開發

快速建立初版功能

例如建立 Flask API、感測資料上傳端點、Node-RED 對接流程或資料庫 CRUD 範例。

重構與整理

改善可讀性

協助把太長的函式拆分、補上註解、整理目錄與 README，使專題更容易維護。

opencode run "閱讀目前專案，說明 sensor.py、app.py 與 templates/index.html 的關係"

opencode run "幫我把這個 Flask + MQTT 專案整理成適合期末專題展示的結構"

opencode run "分析為什麼 ESP32 送到 Flask API 的 JSON 會出現 400 Bad Request"

十、與一般聊天式 AI 的差異

面向	一般聊天式 AI	OpenCode
主要介面	瀏覽器聊天視窗	終端機、桌面端、IDE
上下文來源	以貼上的內容為主	可直接在專案目錄中工作
工作形式	偏向問答	偏向開發任務與程式流程
適合情境	概念說明、快速提問	專案理解、改碼、除錯、重構
風險	容易脫離實際專案上下文	若未審查輸出，可能直接把錯誤帶入專案

十一、建議使用流程

先自己理解需求，再把需求寫成明確任務。
在專案根目錄啟動 OpenCode。
先要求它「解釋現況」，再要求它「提出修改方案」。
修改完成後，人工檢查 diff、重新執行測試或手動驗證。
重要專題一定要保留 Git commit 紀錄，避免 AI 產生的錯誤覆蓋正確版本。

一個實用習慣是：先問 OpenCode「你打算改哪些檔案、原因是什麼」，確認方向正確後，再讓它實作。

十二、風險與注意事項

AI 產生的程式碼可能可以執行，但不一定符合需求、效能或安全性。
不可直接把 API 金鑰、密碼、token 等敏感資訊交給不可信任的公開環境。
對硬體控制、資料刪除、資料庫寫入類功能，必須先在安全範圍內測試。
不要因為 AI 能寫出程式，就跳過基礎語法、資料流與錯誤處理的理解。
若終端機出現 command not found: opencode，通常表示尚未安裝或 PATH 未設定正確。

在課程作業或專題中使用 AI 工具時，建議清楚標示哪些部分由自己設計、哪些部分使用 AI 協助產生，再由自己驗證與修改。

十三、課堂練習建議

請 OpenCode 解釋一個現有 Flask 專案的路由流程。
請 OpenCode 為 Pico W 或 ESP32 上傳感測資料的 API 生成 JSON 格式範例。
請 OpenCode 協助把單一 Python 腳本拆成 main.py、utils.py、config.py。
請 OpenCode 分析一段 MQTT 收不到資料的除錯案例。
比較「自己撰寫版本」與「AI 改寫版本」的可讀性與可維護性。

十四、延伸閱讀

OpenCode 官方網站：https://opencode.ai
OpenCode 官方文件：https://opencode.ai/docs
OpenAI Codex 文件：https://developers.openai.com/codex
Codex Authentication：https://developers.openai.com/codex/auth
Codex Sample Configuration：https://developers.openai.com/codex/config-sample
建議搭配 Git、Python 虛擬環境、測試流程一起使用。

回到教材首頁