OpenClaw Config Validation Failed：修復未知鍵值與無效設定

出現 「config validation failed」 或 「unknown config key」 警告？這表示你的 openclaw.json 中有 OpenClaw 無法識別的項目——通常是因為過時的教學、打字錯誤，或版本升級後設定名稱變更。

常見錯誤訊息

WARN  unknown config key: "model"

config validation failed: unrecognized key "telegramToken"

openclaw doctor: WARN unknown config keys detected

快速修復

openclaw doctor --fix

這會自動偵測並遷移已知的棄用鍵名，並移除真正無法識別的項目。

常見鍵名遷移對照

許多錯誤來自使用舊的設定鍵名。以下是對照表：

手動修復：編輯 openclaw.json

如果你偏好直接修復設定檔：

步驟 1：找到設定檔

openclaw config path

這會印出 openclaw.json 的路徑（通常是 ~/.openclaw/openclaw.json）。

步驟 2：驗證目前的設定

openclaw config validate

這會列出所有無效的鍵名及建議。

步驟 3：修復鍵名

# 移除無效的鍵名
openclaw config unset model

# 設定正確的鍵名
openclaw config set ai.model "claude-sonnet-4-6"

步驟 4：確認

openclaw config validate
# 應該顯示："Configuration is valid"

設定結構參考

有效的 openclaw.json 使用巢狀的點分隔群組：

{
  "ai": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  },
  "gateway": {
    "mode": "local",
    "port": 3001,
    "host": "localhost",
    "token": "your-gateway-token",
    "trustedProxies": ["127.0.0.1"]
  },
  "telegram": {
    "token": "123456:ABC-DEF..."
  }
}

頂層的鍵名如 model、port 或 telegramToken 是無效的——它們必須放在對應的群組下。

升級 OpenClaw 之後

主要版本升級有時會重新命名或重組設定鍵名。每次升級後：

# 步驟 1：檢查問題
openclaw doctor

# 步驟 2：自動遷移設定
openclaw doctor --fix

# 步驟 3：重新啟動
openclaw restart

設定重設（最後手段）

如果你的設定嚴重損壞：

# 備份目前的設定
cp $(openclaw config path) ~/openclaw-backup.json

# 重設為預設值
openclaw config reset

# 重新套用必要的設定
openclaw config set gateway.mode local
openclaw config set ai.apiKey "your-key"
openclaw config set telegram.token "your-bot-token"

告別設定煩惱

ClawTank 自動管理你的 OpenClaw 設定。不需要編輯 JSON、不需要鍵名遷移、不會有驗證錯誤——從第一天起就是正確的設定。