OpenClaw 串接 AIXHUB

安裝官方標準 OpenClaw 套件、合併 AIXHUB 供應端、驗證路由，並安全復原原本設定。

本指南只適用於官方維護的標準 OpenClaw 專案。其他同名專案可能使用不同命令與設定格式，請勿混用其說明或檔案。

OpenClaw 平台支援狀態
平台	狀態
Windows	有限支援
macOS	支援
Linux	支援

完成目標

完成本指南後，你會得到以下結果：

安裝官方標準 OpenClaw npm 套件，並確認目前版本。
合併 AIXHUB 供應端前，先備份既有使用者設定。
以不回顯方式提供 OpenClaw 專用 AIXHUB 金鑰，且不把真實值存進 JSON。
將 aixhub/panel-model-id 設為主要模型。
完成一筆不呼叫工具的文字請求，並與 AIXHUB 用量記錄核對。
保留明確方式，可復原先前的供應端與主要模型。

系統需求

macOS 或 Linux，並具備受支援的 Node.js 版本，且 npm 可從 PATH 執行。
Windows 請使用 WSL，並在同一個 WSL 發行版本內執行安裝、設定及所有 OpenClaw 命令。本指南對原生 Windows 的支援有限。
AIXHUB 帳號、一組專用 AIXHUB API 金鑰，以及從模型路由複製的 OpenAI Responses 相容模型 ID。本指南使用 panel-model-id。
能維持有效 JSON 語法的文字編輯器。

使用者設定檔是 ~/.openclaw/openclaw.json。Windows 的 ~ 是 WSL 內的 Linux 家目錄，不是 %USERPROFILE%。編輯前先備份既有檔案；合併本指南設定時，必須保留不相關的供應端、代理與其他設定。

安裝

安裝或升級官方標準 OpenClaw npm 套件：

npm install -g openclaw@latest

在同一個作業系統環境開啟新的終端機，確認可執行檔與版本：

openclaw --version

若遇到 npm 權限或 PATH 錯誤，請先排除安裝問題，再編輯供應端設定。若已安裝的程式無法辨識標準 OpenClaw 命令，請先從 PATH 移除不相關的套件或可執行檔。

AIXHUB 設定

備份目前設定

建立使用者目錄，並在變更既有設定前建立具有唯一名稱的時間戳備份：

if ! mkdir -p "$HOME/.openclaw"; then
  printf 'Cannot prepare ~/.openclaw. Stop before editing openclaw.json.\n' >&2
  false
elif [ -f "$HOME/.openclaw/openclaw.json" ]; then
  backup=""
  if backup="$(mktemp "$HOME/.openclaw/openclaw.json.backup.$(date +%Y%m%d%H%M%S).XXXXXX")" && cp "$HOME/.openclaw/openclaw.json" "$backup"; then
    printf 'Backup created: %s\n' "$backup"
  else
    [ -z "$backup" ] || rm -f "$backup"
    printf 'Backup failed. Stop before editing openclaw.json.\n' >&2
    false
  fi
else
  printf 'No existing openclaw.json; no backup was needed.\n'
fi

相同命令可用於 Bash、zsh 與 WSL。若原本有舊檔案，只有看到 Backup created: 後才能繼續，並請記錄本次操作顯示的完整路徑。若沒有舊檔案，No existing openclaw.json; no backup was needed. 代表成功；確認沒有外部或生成設定提供這些欄位後，請把下方三個原始狀態都記為 absent。若看到 Cannot prepare ~/.openclaw. Stop before editing openclaw.json. 或 Backup failed. Stop before editing openclaw.json.，必須立即停止，不可編輯設定檔。失敗分支會以非零結果結束該區塊，但不會關閉互動式 Shell；複製失敗時也會清除暫時建立的空白或不完整檔案。mktemp 會在時間戳後加入唯一字尾，所以重複執行會建立新檔案，不會覆寫最初備份。備份可能含有其他供應端的憑證，路徑與內容都必須保持私密。

合併前，請檢查目前 JSON，並在私密紀錄中記錄以下三個原始狀態：

JSON 路徑	變更前要記錄的內容
`models.mode`	完整原值，或 `absent`
`models.providers.aixhub`	完整原始物件，或 `absent`
`agents.defaults.model.primary`	完整原值，或 `absent`

若 models.providers.aixhub 原本已存在，請明確判斷是否確實要覆寫。完整原始物件必須保留在受保護的私密紀錄與時間戳備份中；不要假設它是本指南建立，也不要假設之後可以刪除。

為目前終端機設定金鑰

請使用實際用來啟動 OpenClaw 的 Shell 區塊。每種方式都不會回顯金鑰，也不會把真實值寫入 Shell 歷程。

Bash 與 Windows WSL

read -r -s -p "AIXHUB API key: " AIXHUB_KEY
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

zsh

read -r -s "AIXHUB_KEY?AIXHUB API key: "
printf '\n'
export AIXHUB_API_KEY="$AIXHUB_KEY"
unset AIXHUB_KEY

此變數只存在於目前 Shell 及其啟動的程式。若要持續使用，建議由秘密管理工具注入 AIXHUB_API_KEY。若本機政策允許使用 Shell 設定檔，請直接以文字編輯器編輯僅限目前使用者存取的檔案，並限制其權限；不要執行會把真實金鑰寫入 Shell 歷程的命令。

合併供應端設定

將以下物件合併到 ~/.openclaw/openclaw.json。此範例是本供應端所需的完整有效設定；若既有檔案還有其他設定，必須保留。

{
  "models": {
    "mode": "merge",
    "providers": {
      "aixhub": {
        "baseUrl": "https://api.aixhub.org/v1",
        "apiKey": "${AIXHUB_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "panel-model-id",
            "name": "AIXHUB model"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "aixhub/panel-model-id"
      }
    }
  }
}

屬性名稱有大小寫之分。OpenClaw 使用 baseUrl，不是 OpenCode 的 baseURL，也不是 Codex CLI 的 base_url。apiKey、api、models 與 primary 必須維持上方拼字。Base URL 只能包含一個 /v1，且 api 必須是 openai-responses。

供應端 models 陣列中的模型 ID，必須與 aixhub/panel-model-id 的後半段一致。不要自行加入猜測的 contextWindow、maxTokens 或能力欄位；這個最小路由不需要它們。

啟動 OpenClaw 前先驗證合併後的檔案：

node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")); console.log("JSON OK")' "$HOME/.openclaw/openclaw.json"

若檔案已定義 models，請將 mode 與 providers.aixhub 合併到該物件。若已定義 agents，請先記錄原本的主要模型，再只合併 defaults.model.primary。不要取代不相關物件。

首次使用

在已設定 AIXHUB_API_KEY 的同一個 Shell 執行內建診斷：

openclaw doctor

送出請求前，先排除 JSON 或供應端載入錯誤。請用 openclaw --help 確認目前版本實際提供的命令；若缺少以下預期命令，請先排除套件或版本不符。

列出可用模型。只有清單未顯示已選用 aixhub/panel-model-id 時，才執行 models set，因為 set 會把模型選擇寫入設定檔：

openclaw models list
openclaw models set aixhub/panel-model-id

確認模型後，執行一次本機代理回合：

openclaw agent --local --session-key aixhub-verification --message "Do not call tools, access files, or run commands. Reply with OK only."

--local 可避免第一次測試就要求已設定 Gateway。--session-key aixhub-verification 會提供代理選擇條件，並讓驗證回合使用獨立工作階段。此命令會直接送出範圍明確的請求；不要執行裸 openclaw CLI 後等待手動輸入。

驗證

成功時應看到以下文字輸出：

OK

接著開啟 AIXHUB 用量，尋找使用 panel-model-id 的新 OpenAI Responses 請求。核對時間是否與測試一致，並確認 aixhub-verification 代理回合使用 aixhub 供應端，而非其他已合併供應端或官方帳號。

OpenClaw 未呼叫工具並回傳 OK，且 AIXHUB 留下相符的 Responses 請求與模型記錄。

疑難排解

設定未載入或 JSON 無效

確認檔案位於實際執行 OpenClaw 環境中的 ~/.openclaw/openclaw.json。Windows 使用者必須編輯 WSL Linux 家目錄裡的檔案。重新執行 JSON 驗證與 openclaw doctor，再重做本機代理回合。合併時保留外層 models 與 agents 物件，不要重複建立。

401 或驗證失敗

從輸入 AIXHUB_API_KEY 的同一個 Shell 執行代理回合。JSON 值必須完整保留為 ${AIXHUB_API_KEY}；不要改用官方 OpenAI 登入資料、AIXHUB 控制台密碼，或顯示出來的金鑰。以不回顯方式重新輸入有效的專用金鑰，再重做本機代理回合。

404 或端點錯誤

baseUrl 必須剛好是 https://api.aixhub.org/v1，api 必須剛好是 openai-responses。缺少 /v1、重複成 /v1/v1，或大小寫錯誤，都可能造成路由錯誤。

model not found

從模型路由重新複製完整模型 ID，同時更新供應端陣列中的 id 與 primary: "aixhub/panel-model-id" 的後半段。aixhub/ 前綴只放在 primary，不要放進供應端模型 id。

文字成功但工具失敗

文字回應成功且用量有相符記錄，代表供應端路由可用。請分別檢查工具權限、結構描述、引數與本機 OpenClaw 設定；不要為了修正工具層錯誤而變更 Base URL 或金鑰。在文字路由保持穩定前，維持停用工具。

用量沒有相符請求

使用 openclaw models list 檢查 aixhub-verification 工作階段所選模型。因為 models.mode 是 merge，其他供應端仍然可用，代理層設定也可能改選其他模型。必要時執行 openclaw models set aixhub/panel-model-id；請注意此命令會寫入設定檔，之後再重做本機代理回合。若收到 403、429、502 或 503，請繼續參考錯誤代碼。

升級與復原

升級前先備份設定，再安裝最新套件並確認版本：

npm install -g openclaw@latest
openclaw --version

升級後執行 openclaw doctor、確認驗證工作階段的模型，並在啟用工具前重做本機代理回合。

若有備份，先關閉 OpenClaw，再從本次操作開始時顯示並記錄的精確時間戳路徑，完整還原整份設定。不要只看最新檔名猜測要使用哪一份備份。以本次記錄的備份取代目前檔案，會同時還原三個原始狀態；繼續前請先驗證還原後的 JSON。

若沒有可用備份，請依照私密原始狀態紀錄處理。紀錄中若有原值或物件，請分別還原 models.mode 的精確原值、完整 models.providers.aixhub 原始物件，以及 agents.defaults.model.primary 的精確原值。只有原始狀態明確記為 absent 時，才能刪除對應欄位。若任一原始狀態未知，請停止操作；取得可信的原始設定副本前，不要猜測、刪除供應端或變更主要模型。

關閉暫時終端機即可清除 AIXHUB_API_KEY。從新的 Shell 執行 openclaw models list，確認工作階段已復原的模型，再以本機代理回合完成不呼叫工具的測試，之後才授予工具權限。

安全注意事項

真實金鑰不可放進 openclaw.json；${AIXHUB_API_KEY} 是環境變數參照，可以保留在檔案中。
為 OpenClaw 建立專用 AIXHUB 金鑰，才能獨立輪替或撤銷，不影響其他用戶端。
不要顯示環境變數、把金鑰貼進提示內容、提交到版本控制，或放進螢幕擷取畫面與支援記錄。
限制 openclaw.json 及每一份時間戳備份只有目前使用者能讀取，因為其他供應端項目可能含有敏感值。復原觀察期結束且已驗證設定後，請依本機安全政策清理不再需要的備份。
在 Windows 上，設定檔與秘密管理方式都要位於實際執行 OpenClaw 的同一個 WSL 發行版本。
先用不呼叫工具的請求驗證供應端；啟用工具前，逐次檢視其權限與引數。
若金鑰出現在 Shell 歷程、儲存庫、修補內容或共用記錄，請立即輪替。

官方資料

OpenClaw 模型供應端

最後核對：2026-07-14

OpenClaw 串接 AIXHUB

本頁目錄