OpenClaw + LiteLLM 整合
OpenClaw 是一個自架的 AI 助理，可將聊天應用程式（WhatsApp、Telegram、Discord 等）連接到 LLM 提供者。透過將 OpenClaw 經由 LiteLLM Proxy 路由，您可從單一閘道存取 100+ 個提供者、成本追蹤、支出上限與自動故障切換。
您將設定的內容
Chat apps → OpenClaw Gateway → LiteLLM Proxy → LLM Providers (OpenAI, Anthropic, etc.)
先決條件
| Requirement | How to get it |
|---|---|
| Node.js 22+ | node --version — install from nodejs.org if needed |
| Python 3.10+ | python --version |
| At least one LLM API key | OpenAI, Anthropic, Gemini, etc. |
步驟 1：安裝 LiteLLM Proxy
uv tool install 'litellm[proxy]'
步驟 2：建立 LiteLLM 設定檔
建立一個包含您要使用之模型的設定檔 litellm_config.yaml。以下是使用 OpenAI 的範例：
model_list:
- model_name: gpt-5.6-terra
litellm_params:
model: openai/gpt-5.6-terra
api_key: os.environ/OPENAI_API_KEY
general_settings:
master_key: sk-your-secret-key # pick any value — this is YOUR proxy password
您可以從不同提供者加入任意多個模型：
model_list:
- model_name: gpt-5.6-terra
litellm_params:
model: openai/gpt-5.6-terra
api_key: os.environ/OPENAI_API_KEY
- model_name: claude-sonnet
litellm_params:
model: anthropic/claude-sonnet-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: gemini-flash
litellm_params:
model: gemini/gemini-3.8-flash
api_key: os.environ/GEMINI_API_KEY
general_settings:
master_key: sk-your-secret-key
如需所有選項，請參閱 LiteLLM proxy 設定文件。
步驟 3：啟動 proxy
請確保您的 API 金鑰已作為環境變數可用（透過 export、.env 檔案，或您管理密鑰的任何方式），然後啟動 proxy：
litellm --config litellm_config.yaml --port 4000
步驟 4：安裝 OpenClaw
# macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash
在 Windows 上，請使用 PowerShell：iwr -useb https://openclaw.ai/install.ps1 | iex
建議使用 WSL2，而非原生 Windows。
步驟 5：將 OpenClaw 連接到 LiteLLM
執行上線精靈：
openclaw onboard --install-daemon
出現提示時：
- 選擇 QuickStart 或 Manual 作為上線模式（兩者都可；Manual 可讓您在閘道設定上有更多選項）
- 將 LiteLLM 選為模型／驗證提供者
- 輸入您在步驟 2 中的 LiteLLM
master_key，並將 base URL 設為您的 proxy 位址（例如，http://localhost:4000） - 當系統詢問預設模型時，選擇 Enter model manually，並輸入您
litellm_config.yaml中的模型名稱（例如，litellm/gpt-5.6-terra）
您也可以在上線後設定或變更模型：
openclaw models set litellm/gpt-5.6-terra
針對腳本 / CI 環境，您可以完全跳過提示：
openclaw onboard --non-interactive --accept-risk \
--auth-choice litellm-api-key \
--litellm-api-key "sk-your-secret-key" \
--custom-base-url "http://localhost:4000" \
--install-daemon --skip-channels --skip-skills
步驟 6：驗證
檢查閘道是否健康：
openclaw health
接著傳送測試訊息：
openclaw dashboard # web UI
openclaw tui # terminal UI
openclaw agent --agent main -m "Hello, what model are you?" # one-shot CLI
如果您從模型收到回應，整合即已成功運作。
檢查目前啟用的是哪個模型：
openclaw models status
設定參考
完成上線後，OpenClaw 會將 LiteLLM provider 設定儲存在 ~/.openclaw/openclaw.json。相關區段大致如下：
{
"models": {
"providers": {
"litellm": {
"baseUrl": "http://localhost:4000",
"apiKey": "sk-your-secret-key",
"api": "openai-completions",
"models": [
{
"id": "gpt-5.6-terra",
"name": "GPT-5.6 Terra via LiteLLM"
}
]
}
}
},
"agents": {
"defaults": {
"model": { "primary": "litellm/gpt-5.6-terra" }
}
}
}
您可以直接編輯此檔案，以新增更多模型或變更 baseUrl。OpenClaw 會自動熱重載變更。
疑難排解
連線遭拒 / 無法連上 proxy
請確認 LiteLLM proxy 正在執行，且您 OpenClaw 設定中的 baseUrl 符合：
curl http://localhost:4000/health -H "Authorization: Bearer sk-your-secret-key"
模型錯誤或 "Invalid model name"
OpenClaw 中的模型名稱必須符合您 model_name 中的 litellm_config.yaml。請使用以下方式切換目前啟用的模型：
openclaw models set litellm/gpt-5.6-terra
重新安裝後的閘道配對問題
如果 CLI 在重新安裝後無法連線到閘道，請停止服務並重新安裝：
openclaw gateway stop
openclaw gateway install
