openclaw-model-switch

OpenClaw モデルの切り替え

openclaw.json を安全に編集して、OpenClaw インスタンスのモデル設定を切り替えるか修復します。

編集する前に診断してください。 OpenClaw でモデルが失敗する原因は、通常、モデル ID ではありません。キーのルーティング（環境変数による乗っ取り）、プロバイダープラグインの制限、またはエンドポイントとモデルの不一致です。まずこれらを確認せずにモデル ID を変更すると、5 分で済む修正が 2 時間のデバッグ作業になりかねません。検出コマンドを含む問題の全リストは references/troubleshooting-model-config.md にあります。エラーが発生したら、すぐに読んでください。

ステップ 1 — 実際の設定ファイルを見つける

ハードコードされたパスを前提にしないでください。候補となる場所（すべて確認し、存在するものはすべて編集してください）：

1. ~/.openclaw/openclaw.json — ほとんどのインストール環境でゲートウェイが使用する実際の設定
2. ~/.kimi/kimi-claw/openclaw.json — 一部のインストール環境で同期される Kimi Claw のミラー
3. ~/.kimi_openclaw/openclaw.json — 以前のデスクトップ用パス

ゲートウェイが実際にどのファイルを読み込むかを確認します。openclaw gateway status を実行すると、 Config (service): <path> が表示されます。複数のファイルがある場合は、ミラーとして扱ってください。すべて同じ内容に編集してください。そうしないと、次の同期で修正内容が上書きされます。

ステップ 2 — 設定を変更する前に、エンドポイントとモデルをテストする

リレーのモデル一覧を決して信用しないでください（new-api 形式のリレーでは、GET /v1/models の一覧が不完全なことがよくあります。一覧にないモデルでも正常に応答する場合があります）。唯一信頼できるのは、ボットを実行するホストから実際に補完リクエストを送ることです。

curl -sS -o /tmp/probe.json -w "HTTP %{http_code}\n" \
  -X POST "<baseUrl>/v1/messages" \
  -H "Authorization: Bearer <apiKey>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"<model-id>","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

期待される結果は、HTTP 200 と、レスポンス本文に含まれる content 配列です。別の場所で動作すると確認済みのトークンで 401 Invalid token が返る場合 → 通信に使うキーが乗っ取られています（トラブルシューティングのリファレンスの問題 #1 を参照）。503 No available channel が返る場合 → このネットワークからは、このトークン／グループでモデルを利用できません（問題 #3）。利用可能なモデルを選ぶか、リレーを修正してください。むやみに切り替えないでください。

ステップ 3 — モデルを切り替える

python3 scripts/switch-model.py <model-id> --restart
# target a specific provider instead of the guessed one:
python3 scripts/switch-model.py k3 --provider kimi-relay --restart
# explicit config path (skips discovery):
python3 scripts/switch-model.py k3 --config ~/.openclaw/openclaw.json --restart

このスクリプトは、候補となるすべての設定ファイルを検出して <config-dir>/config-backups/ にバックアップし、既知のモデル定義を追加して、agents.defaults.model.primary を設定し、ミラーファイルを同期したうえで、--restart を指定してゲートウェイを再起動します。

ステップ 4 — エンドツーエンドで検証する（必須）

ゲートウェイを再起動しただけでは、何も証明できません。実際にエージェントを 1 回実行し、結果のメタデータを確認してください。

openclaw agent --local --json --agent main --session-id verify-$(date +%s) -m "ping"

成功時は、"result": "success"、"fallbackUsed": false が表示され、ゲートウェイのログに agent model: <provider>/<model> (thinking=...) が出力されます。fallbackUsed: true のまま "result": "success" となっている場合は、指定したモデルが失敗し、フォールバックによって実行が完了しています。設定はまだ誤っています。

よくある失敗 → トラブルシューティングのリファレンスを読む

症状	最も可能性の高い問題
LLM error new_api_error: Invalid token が出るが、curl ではトークンが動作する	問題 #1 — 環境変数 KIMI_API_KEY がプロバイダーの通信キーを乗っ取っている
Thinking level "max" is not supported ... Use one of: off, on	問題 #2 — kimi-provider プラグインが二段階の思考レベルをハードコードしている。カスタムプロバイダーを使って回避する
Thinking level ... Use one of: off, minimal, low, medium, high	問題 #2 の別パターン — anthropic-messages のベースプロファイルが原因。params.canonicalModelId で制限を解除する
503 No available channel for model X under group default	問題 #3 — このグループ／ネットワークではモデルを利用できない。一覧にあることと利用可能であることは別
編集を保存してゲートウェイも再起動したのに、何も変わらない	問題 #5 — 間違ったファイルを編集した／ミラーが同期されていない

安全に関するルール

• 必ずバックアップを取ってから編集してください（スクリプトは自動で行います。手動で編集する場合は、まず config-backups/ にコピーしてください）
• 既存の apiKey、headers、プラグイン設定、env ブロックを保持してください。変更するフィールドだけを再入力してください
• 手動編集後は JSON を検証してください：python3 -m json.tool openclaw.json > /dev/null
• API キーを含む設定ファイルをバージョン管理にコミットしないでください
• 変更後は必ずステップ 4 の検証をやり直してください。失敗した場合は、別のことを試す前に最新のバックアップを復元してください

リソース

• scripts/switch-model.py — 設定の検出、バックアップ、ミラー同期、再起動に対応したモデル切り替えツール
• references/kimi-models.md — 既知のモデル仕様（k3、k2p6、kimi-k2.7-code）と設定スニペット
• references/troubleshooting-model-config.md — 落とし穴の一覧：環境変数キーの乗っ取り、プラグインのバイナリに関する誤解、canonicalModelId、リレーの利用可否、設定の検出。エラーが発生した場合はお読みください。