Hermes Agent 與 OpenClaw 都可以連到 OpenAI 相容 API。LiteLLM 可以把 Azure AI Foundry 中部署的模型轉成同一套 OpenAI 相容介面，讓兩個 Agent 共用相同 Endpoint：
Ben
Hermes Agent ─┐
├─> LiteLLM Proxy（127.0.0.1:4000）─> Azure AI Foundry 模型
OpenClaw ─────┘
這種架構有幾個好處：
設定前先分清楚以下三個名稱：
Azure 模型名稱
Azure Deployment Name
azure/<deployment-name> 必須使用這個名稱。LiteLLM Model Name
例如：
model_name: my-azure-model
litellm_params:
model: azure/my-foundry-deployment
這表示：
my-azure-model
my-foundry-deployment
進入 Microsoft Foundry Portal：
建立或選擇既有 Project／Foundry Resource。不同時期的 Portal 介面名稱可能略有差異，例如：
核心概念相同：需要有一個可部署模型、管理 Endpoint 與 Credentials 的 Azure Resource。
在 Foundry Portal 中：
請記住 Deployment Name。後面 LiteLLM 使用的是它，而不只是畫面上的模型名稱。
介面名稱可能隨 Portal 版本調整，通常可以從以下位置找到：
常見 Endpoint 形式包括：
https://<RESOURCE_NAME>.cognitiveservices.azure.com/
或：
https://<RESOURCE_NAME>.openai.azure.com/
請複製 Portal 實際顯示的 Endpoint，不要自行猜測網域。
通常可以從以下位置取得：
KEY 1 或 KEY 2。有些 Foundry 介面也會在 Deployment 的 Consume 頁面顯示 Endpoint 與 Credential 使用方式。
安全注意事項：
Azure API Version 會依模型、Resource 類型及功能而不同。不要直接複製別人的版本號。
應以以下來源為準：
本文以下使用：
2025-03-01-preview
可使用一般 Python 安裝：
python3 -m pip install --user 'litellm[proxy]'
如果系統有使用 pipx，也可以隔離安裝：
pipx install 'litellm[proxy]'
確認 LiteLLM 執行檔：
litellm --version
npm install -g pm2
確認安裝：
pm2 -v
PM2 原本是 Node.js Process Manager，但也可以管理 Python CLI 程序。
mkdir -p "$HOME/.config/litellm"
chmod 700 "$HOME/.config/litellm"
建立：
$HOME/.config/litellm/secrets.env
內容：
AZURE_API_BASE="https://<RESOURCE_NAME>.cognitiveservices.azure.com/"
AZURE_API_KEY="<AZURE_API_KEY>"
AZURE_API_VERSION="<AZURE_API_VERSION>"
LITELLM_MASTER_KEY="<GENERATE_A_SEPARATE_RANDOM_KEY>"
限制權限：
chmod 600 "$HOME/.config/litellm/secrets.env"
LITELLM_MASTER_KEY 應與 Azure API Key 完全不同。可以產生一個隨機值：
python3 -c 'import secrets; print("sk-litellm-" + secrets.token_urlsafe(32))'
建立：
$HOME/.config/litellm/config.yaml
範例：
model_list:
- model_name: my-azure-model
litellm_params:
# azure/ 後方必須是 Azure Deployment Name
model: azure/my-foundry-deployment
api_base: os.environ/AZURE_API_BASE
api_key: os.environ/AZURE_API_KEY
api_version: os.environ/AZURE_API_VERSION
model_info:
base_model: my-azure-model
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
litellm_settings:
drop_params: true
若有多個 Azure Deployment，可以繼續加入：
model_list:
- model_name: model-a
litellm_params:
model: azure/deployment-a
api_base: os.environ/AZURE_API_BASE
api_key: os.environ/AZURE_API_KEY
api_version: os.environ/AZURE_API_VERSION
- model_name: model-b
litellm_params:
model: azure/deployment-b
api_base: os.environ/AZURE_API_BASE
api_key: os.environ/AZURE_API_KEY
api_version: os.environ/AZURE_API_VERSION
如果不同 Deployment 需要不同 API Version，可以直接在各模型區塊分別指定，或使用不同環境變數。
載入環境變數：
set -a
source "$HOME/.config/litellm/secrets.env"
set +a
啟動：
litellm \
--config "$HOME/.config/litellm/config.yaml" \
--host 127.0.0.1 \
--port 4000
使用 127.0.0.1 可以避免 Proxy 直接暴露在區域網路或公網。
另開一個 Terminal，確認模型清單：
set -a
source "$HOME/.config/litellm/secrets.env"
set +a
curl -sS http://127.0.0.1:4000/v1/models \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
測試 Chat Completions：
curl -sS http://127.0.0.1:4000/v1/chat/completions \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "my-azure-model",
"messages": [
{"role": "user", "content": "Reply with exactly OK"}
],
"max_completion_tokens": 32
}'
如果回傳 OK，代表這條路徑已通：
curl -> LiteLLM -> Azure AI Foundry Deployment
先載入 Secret：
set -a
source "$HOME/.config/litellm/secrets.env"
set +a
再執行：
LITELLM_BIN="$(command -v litellm)"
PYTHON_BIN="$(command -v python3)"
pm2 start "$LITELLM_BIN" \
--name litellm \
--interpreter "$PYTHON_BIN" \
-- \
--config "$HOME/.config/litellm/config.yaml" \
--host 127.0.0.1 \
--port 4000
重點：
command -v litellm：避免硬編碼某位使用者的 Home 路徑。--interpreter：指定 Python 執行。--：分隔 PM2 與 LiteLLM 的參數。$HOME：取代 /Users/<username>，適合公開文章及跨使用者使用。--host 127.0.0.1：只允許本機 Client 連線。查看狀態：
pm2 status
查看 Log：
pm2 logs litellm
只看最近 100 行：
pm2 logs litellm --lines 100
重啟：
pm2 restart litellm
如果更改了程序環境變數，可重新載入 Secret 後更新環境：
set -a
source "$HOME/.config/litellm/secrets.env"
set +a
pm2 restart litellm --update-env
停止：
pm2 stop litellm
移除 PM2 程序：
pm2 delete litellm
pm2 startup
PM2 會輸出一條需要執行的系統指令。執行畫面提供的命令後，再執行：
pm2 save
注意：pm2 startup 輸出的命令通常包含本機使用者名稱與 Home 路徑。Medium 文章可以說明「執行 PM2 顯示的命令」，不要把自己電腦的完整輸出直接貼上網。
Hermes 支援任何實作 /v1/chat/completions 的 OpenAI 相容 Endpoint。最不容易因版本更新而失效的方法，是使用 Hermes 的互動式設定：
hermes model
實際選單流程如下：
在 Select provider 畫面選擇：
custom (direct API)
雖然清單裡也有 Azure Foundry，但本文的架構是讓 Hermes 連到本機 LiteLLM，而不是讓 Hermes 直接連 Azure，因此這裡應選 custom。
在提示中輸入 LiteLLM Base URL：
API base URL [e.g. https://api.example.com/v1]:
http://127.0.0.1:4000/v1
在 API key [optional] 輸入 LiteLLM 的 LITELLM_MASTER_KEY，不是 Azure API Key。
在 Select API compatibility mode 選擇：
1. Auto-detect [current]
也可以直接選擇 LiteLLM 在本文中提供標準 OpenAI 相容的 /chat/completions，較不容易因 URL heuristics 或版本差異選錯 API。
Hermes 會呼叫 LiteLLM 的 /v1/models，列出可用模型，例如：
Available models:
1. gpt-5.2-chat
2. gpt-5.4-pro
3. gpt-5.4
4. gpt-5.5
5. gpt-5.6-sol
選擇需要的模型。這裡顯示的名稱，就是 LiteLLM config.yaml 中設定的 model_name。
設定後可測試：
hermes chat \
--provider custom \
-m my-azure-model \
-q "Reply with exactly OK"
在 Hermes 互動式 Session 中，也可以用 /model 再切換 Provider 或模型：
/model
一般使用者不需要手動編輯 ~/.hermes/config.yaml；hermes model 會自行保存 Custom Endpoint、API compatibility mode 與所選模型。
也可以把 LiteLLM 設成 Hermes 的 Fallback Provider。建議不要手動修改 fallback_providers YAML，而是直接使用 Hermes 內建的互動式管理指令：
hermes fallback
或明確使用新增指令：
hermes fallback add
hermes fallback add 會開啟相同的 Provider Picker。若要把 LiteLLM 加入 Fallback Chain，實際操作同樣是：
選擇：
custom (direct API)
API Base URL 輸入：
http://127.0.0.1:4000/v1
API Key 輸入 LiteLLM 的 LITELLM_MASTER_KEY。
API compatibility mode 選擇：
1. Auto-detect [current]
從 LiteLLM 回傳的 Available models 選擇要作為 Fallback 的模型。
完成驗證並儲存。
查看目前的 Fallback Chain：
hermes fallback list
也可以使用簡寫：
hermes fallback ls
移除某個 Fallback：
hermes fallback remove
或：
hermes fallback rm
清除整條 Fallback Chain：
hermes fallback clear
hermes fallback 會重用 hermes model 的 Provider Picker，因此 Provider 清單、Credential 提示與連線驗證方式相同。設定完成後，Hermes 會自行將結果保存到 ~/.hermes/config.yaml 的 fallback_providers，一般使用者不需要手動編輯 YAML。
Hermes 更新模型、Provider 或 Fallback 設定後，CLI 應退出並重新開啟；Gateway 則可重啟：
hermes gateway restart
Hermes 官方文件：
OpenClaw 也可以將 LiteLLM 設為 OpenAI 相容 Provider。
主要設定檔通常位於：
~/.openclaw/openclaw.json
概念設定如下：
{
"models": {
"providers": {
"litellm": {
"baseUrl": "http://127.0.0.1:4000/v1",
"apiKey": "<YOUR_LITELLM_MASTER_KEY>",
"api": "openai-completions",
"models": [
{
"id": "my-azure-model",
"name": "My Azure Foundry Model",
"contextWindow": 128000,
"maxTokens": 16384
}
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "litellm/my-azure-model"
}
}
}
}
注意：
baseUrl 指向 LiteLLM，不是直接指向 Azure。apiKey 使用 LiteLLM Master Key，不是 Azure API Key。models[].id 必須等於 LiteLLM Config 中的 model_name。primary 使用 <provider-name>/<model-id> 格式。contextWindow 與 maxTokens 應依實際模型規格設定，不要直接照抄範例數字。修改後檢查模型狀態：
openclaw models status
openclaw models list
設定預設模型也可使用：
openclaw models set litellm/my-azure-model
若 OpenClaw Gateway 正在背景執行，修改後重啟：
openclaw gateway restart
安全提醒：若 OpenClaw 版本或部署方式要求把 Key 寫入 JSON，請確保：
chmod 600 "$HOME/.openclaw/openclaw.json"
假設已在 Foundry 新增 Deployment deployment-b，只需在 LiteLLM Config 增加：
- model_name: model-b
litellm_params:
model: azure/deployment-b
api_base: os.environ/AZURE_API_BASE
api_key: os.environ/AZURE_API_KEY
api_version: os.environ/AZURE_API_VERSION
重啟 LiteLLM：
pm2 restart litellm
確認模型出現在清單：
curl -sS http://127.0.0.1:4000/v1/models \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
接著：
hermes model，或切換至新的 Custom model。models.providers.litellm.models，然後重啟 Gateway。可能原因：
Authorization: Bearer ...。最常見原因：
model: azure/... 後方填了模型名稱，而不是 Deployment Name。pm2 restart litellm --update-env
pm2 logs litellm --lines 100
確認 LiteLLM 與 Interpreter：
command -v litellm
command -v python3
python3 -m pip show litellm
若 LiteLLM 安裝在特定 Virtual Environment，PM2 必須使用同一個 Environment 的 Python 與 LiteLLM 路徑。
先分層測試：
curl 測 LiteLLM。這樣比較容易確認問題發生在 Azure、LiteLLM，還是 Agent 設定。
Azure AI Foundry
└─ Model Deployment
└─ Azure Endpoint + Credential
LiteLLM Proxy
├─ 對外提供 OpenAI 相容 API
├─ 使用 model_name 隱藏 Azure Deployment 細節
└─ 由 PM2 常駐於 127.0.0.1:4000
↓
┌─────────┴─────────┐
│ │
Hermes Agent OpenClaw
Custom Endpoint OpenAI-compatible Provider
完成後可以得到：
看影片追技術