OpenClawモデルマネージャー：モデルルーティング用JSONの手動編集をやめましょう

以前、JSONファイル内でモデルIDを誤って入力してしまったことがあります。そうすると、それを利用しているエージェントが何もしなくなってしまったのです。エラーも発生せず、クラッシュもしませんでした。私がもっと面白そうなバグを探している間、そのエージェントは存在しないモデルと通信し続けていたのです。このアプリは、そんな事態を二度と起こさないためのものです。

このツールの対象者

OpenClawを使用して、複数のエージェントやローカル/有料モデルを組み合わせて運用し、月に一度以上モデルの割り当てを変更される方であれば、このツールを最大限に活用していただけます。もし特定のモデルを設定したきり二度と変更しない場合は、手動での編集で十分であり、本ツールは必要ありません。

また、本ツールは以下のような深刻な問題も防ぎます。openclaw.jsonが半分しか書かれていなかったり形式が不正だったりするとゲートウェイ全体がクラッシュループを起こす可能性がありますが、アトミックな書き込み処理およびバックアップ機能によりそのような事態は防がれます。また、手動でsystemdのオーバーライド設定を行うとAPIキーがps出力に漏れ出す危険性もありますが、Coding Helperスイッチャーではそうした事態が起こらないように設計されています。

2026年8月版での変更点：

• APIモデルを追加ダイアログから、クラウドプロバイダーを一度の編集で登録可能になりました。プロバイダーブロックおよびカタログエントリがまとめて書き込まれ、APIキーは設定ファイルではなくゲートウェイの環境変数ファイルに保存されます。
• カタログ行上でコンテキストウィンドウの値を編集できるようになりました。
• カタログ行には、各モデルについてプロバイダーが実際に公開している情報が表示されるようになりました。
• 私の二台目のPC上にある推論サーバーは、これまでLM Studioを使用していましたが、現在は同じポートでllama.cppベースになっています。アプリケーション側では設定ファイルからプロバイダーのベースURLを読み込んでいるため、コードの変更は一切不要でした。

最終的に得られるもの

まずはスクリーンショットをご覧ください。これらは一時的な HOME ディレクトリ内で、ダミーの設定を用いて動作させたサンドボックス環境から撮影したものです。実際のアプリケーションでありながら、偽のデータが使われており、私のAPIキーなどは一切使用されていません。

このメインウィンドウによって、以前はJSONをgrepして調べていた疑問――どのモデルがどこで動作しており、そのコストはいくらか？――に即座に答えることができます。各エージェント、システム全体のデフォルト設定、サブエージェント用の上書き設定、定期実行ジョブ、さらには別のメールエージェントが使用しているモデルまでも一覧に載っています。各項目には色付きのバッジが付いており、「ローカル」（このPC）、「リモート」（別のPC）、「クラウド」（請求書に記載されるサービス）といった区別が可能です。アプリケーション側から見れば、ローカルもリモートもいずれもOpenAI互換のサーバーに過ぎません。アプリが気にするのは、それぞれが /v1/models で何を返してくるかだけです。スクリーンショット撮影時、このPCではLM Studioが動作していました。現在はどのモデルも実行されておらず、別のPC上でllama.cppベースのサーバーが稼働中です。

なぜこの仕組みが存在するのか

OpenClawとは、私が自宅で運用しているマルチエージェントシステムです。複数のAIエージェントが存在し、それぞれが特定のモデルを利用しています。中には無料でローカルに設置できるモデルもあれば、クラウド上にあり課金が発生するモデルもあります。すべてのルーティング設定は ~/.openclaw/openclaw.json という1つのファイル内に記述されており、そこにはモデルのカタログや各エージェントの優先・フォールバック用モデルの割り当て、プロバイダー設定、そしてゲートウェイ自体の認証トークンなどが含まれます。しかし手動でこのファイルを編集すると、主に2つの問題が生じていました。

1つ目は、編集ミスによってシステムが壊れてしまうことです。特に不正な内容が保存されると最悪の事態となります。ちょっとした間違いでゲートウェイがクラッシュを繰り返すようになり（この不具合の対処法については ゲートウェイが壊れたときに私がどうするか で説明しています）。

2つ目は、ルーティング設定の変更作業が非常に煩雑だったことです。もしゲートウェイがコーディングタスクを Claude Code CLI に割り当てるようになっている場合、ゲートウェイの systemd ユニット内にある ANTHROPIC_* という環境変数によって、リクエストがどこに送信され、誰に課金されるかが決まります。無料のローカルモデル、安価な DeepSeek、そして有料の Anthropic モデルを使い分けるためには、毎回手動で systemd の設定ファイルを書き換える必要がありました。これはまさに夜中の11時に私がミスしやすい種類の作業です。本アプリ内の「Coding Helper」パネルを使えば、こうした作業を自動で行ってくれます。私自身は2026年9月以降、Claude Codeを自前のゲートウェイ経由で利用していないため、その設定ファイルは現在私のマシンにはインストールされていません。ただし、この切り替え機能自体はダウンロードパッケージに含まれており、下記の通り正常に動作します。

保存パスについて

私が信頼できる必要がある部分は、「保存」ボタンをクリックした際に起こる処理です。その手順は以下の通りです。

重要な工程は二つあります。まず、モデル選択用のドロップダウンには設定ファイルに記載されているIDのみが表示されるため、存在しないモデル名を指定してしまうことは不可能です（下記の例参照）。また、openclaw.jsonにはゲートウェイ用の認証トークンが含まれており、chmod 600で保護されているため、原子的な書き込み処理が必須となります。つまり、一時ファイルに元のファイルのパーミッションを設定した上で内容を書き込み、fsyncを実行してから元のファイル名へとリネームするのです。保存中にクラッシュが起きても元のファイルは無傷のままとなります。

不適切な保存内容も、単純なリネーム操作で元に戻すことが可能です。バックアップ更新後にはディスク上に6つのコピーが存在し、最新版が.bak、それ以前の5つが.bak.1から.bak.5となります。新たな保存ごとに最も古いバックアップが削除される仕組みです。

実際に存在しないモデルを指定した場合の挙動は次の通りです。ドロップダウンには設定ファイルに記載されているIDのみが表示されるため、本来存在しないモデル名が入力されることはありません。例えば「[Default]」という項目で、プロバイダー側から削除されたモデル名が指定されていた場合でも、アプリは現在選択されているモデルを維持したまま、そのような不正な内容を保存せずに適切なメッセージを表示します（ここでのエージェント名やモデル名は仮の例です）。

"[Default]" primary for worker points at vllm/old-model, which doesn't exist on its provider — keeping the agent's current model. Fix the Model Defaults slot.

以下は実際の保存処理における変更内容です。例として設定ファイル内のworkerエージェントをDeepSeek flashへと切り替えた場合の差分です。私はアプリ自体が持つ保存機能を利用し、一時的なホームディレクトリ内にあるサンプル設定ファイルに対して処理を行いました。

--- openclaw.json.bak
+++ openclaw.json
@@ -36,7 +36,7 @@
         "id": "worker",
         "name": "Worker",
-        "model": "vllm/example-local-model"
+        "model": "deepseek/deepseek-v4-flash"
       }

一点注意すべき点として、最初の保存処理では2スペース分のインデントでファイル全体が書き換えられるため、例えば"input": ["text"]のように1行で記述されていた配列も複数行に分割されます。ただしデータ内容自体は同一です。最初の保存以降はこの程度の小さな差分しか生じなくなります。

コーディングヘルパーのドロップイン機能

これは、ゲートウェイがClaude CodeのCLIを起動する環境向けのオプション機能です。この処理は別途行われるため、openclaw.jsonには一切触れません。アプリケーション側ではsystemd用のドロップイン設定ファイルを作成し、ゲートウェイがClaude Codeプロセスを起動する前にその環境変数を上書きします。

4つのモードが1つのドロップダウンで選べます：LM Studio（無料でローカル利用可）、DeepSeekのAnthropic互換エンドポイントを利用するモード（低コスト）、Anthropic Cloud（デフォルト設定：ドロップイン機能は一切使われず、何も上書きされません）、そしてオフ（ドロップダウンには「無効化」と表示）。この「オフ」モードではCLIがhttp://127.0.0.1:9/blockedを参照するため、すべてのリクエストが即座に失敗します。また、ワンクリックで実際にテストも可能で、LM StudioまたはDeepSeekに対してAnthropic形式のpingリクエストを送信し、どのモデルが応答したかを確認できます。こうした実際の動作確認こそが、設定画面だけでは分からない情報を提供してくれるのです。

APIキーをunitファイルに記載しない方法

DeepSeekモードではAPIキーが必要となりますが、systemdのunitファイルにそのキーを書き込むのは好ましくありません。なぜなら、そこに記載された内容はディスク上にもsystemctl showの出力結果にも平文のまま残ってしまうからです。そのため、ドロップイン設定ファイルにはキー自体を記載せず、代わりに次のように記述します：

ExecStart=/usr/bin/bash -c 'export ANTHROPIC_API_KEY="$$DEEPSEEK_API_KEY"; exec <gateway cmd>'

ここでのコツは$$の利用です。Unitファイル内では$$を使うことで、単なる$記号として解釈させることができます。これを使わない場合、systemdがコマンドラインを構築する際に変数を展開してしまい、実際のAPIキーがプロセスの引数としてpsから読み取れる状態になってしまいます。しかし二重ドル記号を使うことで、bashは$DEEPSEEK_API_KEYという文字列そのままを受け取り、実行時にゲートウェイ側のEnvironmentFile（OpenClawのホームディレクトリにあるgateway.systemd.envファイルで、chmod 600により保護されています）からその値を展開します。こうしてAPIキーはunitファイルやsystemctl showの出力結果、あるいはプロセス一覧にも一切現れず、あくまでそのプロセス専用のbash環境内にのみ存在することになります。Zipファイル内のexamples/フォルダには、CHANGE_MEというプレースホルダを使ったこの仕組みの例が記載されています。

2026年8月版に搭載されたAdd API Modelダイアログも、逆方向から同じルールを適用しています。クラウドプロバイダーを手動で追加する場合、openclaw.json内の2箇所を合致させる必要があります。すなわちmodels.providers.<id>という接続設定ブロックと、agents.defaults.modelsというカタログエントリです。どちらか一方でも誤っていると、モデルがどこからも選択できなくなってしまい、その理由を示すエラーメッセージも表示されません。

このダイアログでは両方の設定が一度に書き込まれます。入力したAPIキーは同じくgateway.systemd.envファイルに保存されます。この際、まずファイルのバックアップが作成され、0600という権限設定も維持されます。また同じ変数が複数回定義されている場合でも重複分は無視されるため、古い記述が優先されることもありません。openclaw.jsonには単に"${YOUR_KEY_VAR}"という文字列のみが記載されます。保存前には「Test」ボタンを押すことで実際にエンドポイントへリクエストを送信できます。これによりベースURLやプロトコル、APIキー、モデルIDがすべて正しく設定されているかどうかを事前に確認できるのです。そうしないと、数週間後にそのプロバイダーが実際には利用不可だったことに気付く羽目になるからです。

セットアップ

zipファイルに同梱されているREADMEより：

# 1. Install GTK4 + libadwaita + PyGObject from your distro's packages
#    (one dnf/apt line; README-SETUP.md has the exact package names)

# 2. Install the app and its launcher
install -Dm755 openclaw-model-manager ~/.local/bin/openclaw-model-manager
# .desktop file goes to ~/.local/share/applications/

# 3. If you don't already have an OpenClaw config:
cp examples/openclaw.json.example ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/openclaw.json
# then replace every CHANGE_ME placeholder inside it

# 4. Optional: API keys go in two files in the same directory as
#    openclaw.json: .env and gateway.systemd.env (both chmod 600;
#    examples/ has a template for each)

PyGObject以外にpipでインストールする必要はありません。その他のすべてはPython 3.11以降の標準ライブラリで、tomllibも含まれています。全体としては、実行可能なスクリプト1つ（4,181行、約190KB）、.desktop形式のランチャー、README、MITライセンス、そして4つの設定例から構成されています。zipファイルのサイズは56KBです。

注意点

• クラウドモードとは「ドロップイン機能が使えない」という意味です。 何も上書きされないため、デバイス上で既に設定されていた内容はそのまま動作し続けます。選択したモードで有効なキーが存在しない場合アプリは警告を出しますが、念のためご確認ください。
• ドロップイン機能は意図的に本物のAnthropic用キーを隠します。 ローカルモードでは、ゲートウェイが生成するすべてのプロセスに対して ANTHROPIC_API_KEY=lm-studio が設定されます。私の環境では、対話用の claude CLIエイリアスが静かにLM Studioへとリルートされていました。Claude Codeは「正常に動作している」ように見えましたが、実際の応答はローカルモデルから返っていました。もしClaudeの返答内容がおかしくなった場合は、モデルのせいだと決めつける前に systemctl --user cat openclaw-gateway.service を実行してドロップイン設定がないか確認してください。
• openclaw update でゲートウェイの ExecStart が変更された後は、一度だけDeepSeekモードを再選択してください。 そうすることで新しいコマンドが正しく適用されます。アプリはユニット設定ファイルから本来の ExecStart 値を読み取り、自身のラッパー機能（index.js の存在および $$DEEPSEEK_API_KEY がないこと）を検知するため、二重にラップされることはありません。ただし、再度チェック対象として認識されていないコマンドについては自動修正されません。
• reasoning: true がローカルモデル用の安全なデフォルト設定です。 reasoning_content を出力するモデルでも、reasoning: false に設定されているとゲートウェイからは動作停止状態と見なされます。約390秒間応答がなくなった後でプロセスが強制終了されます。非推論型モデルではこの設定を有効にしても問題ありませんので、モデル追加ダイアログでもデフォルトで有効になっています。この点で実際に多くのデバッグ時間を費やしました。
• plugins.allow に値が設定されている場合、それは厳格な許可リストとなります。 プラグインエントリで enabled: true を指定しても、その id が allow にも含まれていなければ無効です。アプリはこの仕様を正しく認識しており、意図的に plugins.* の書き込みを行わないように設計されています。したがって、プラグインに不具合が生じても、その原因を示してくれるのはこのアプリではありません。エージェントスタックの解説記事でも同様の落とし穴が紹介されています。
• ゲートウェイは自動的に openclaw.json を書き換えます（IDの整合性調整や openclaw update 時など）。アプリはファイルの更新時刻を記録しており、外部からの変更内容を上書きする前に警告を出します。また保存前のバックアップ機能により、ディスク上にあった元の内容も保持されます。
• 公開されているコンテキストウィンドウの値は、あくまでサーバー側の主張に過ぎません。 実際には十分な処理能力がないにもかかわらず、サーバー側が「50万トークン対応」と謳っているケースもあります。ゲートウェイはその情報を鵜呑みにするため、長いプロンプトを送った際にモデルの不具合のように見える失敗が起きるのです。そのためカタログ画面では contextWindow の値を実際の数値に修正できるようになっています。
• モデルIDは provider/raw-id という形式です。 スラッシュが含まれない単純なIDの場合、ローカル推論エンドポイント経由で解決されます。一方で一部のサーバーではより長い raw id（publisher/repo/file-stem 形式）を使用しているため、短縮せずにプロバイダー側が提示する通りの値をそのまま貼り付けてください。これはエラーではなく命名規則に過ぎますので、存在しないプロバイダーフィールドを探し回る前に知識として覚えておくと良いでしょう。

関連記事：このアプリが設定を編集する エージェントスタック、すべての処理にDeepSeekを利用する方法、そしてゲートウェイが不調になった際の私の対処法 についてもご覧ください。

ダウンロード

• Download OpenClaw Model Manager source (zip) 56 KB

個人利用は無料です。役に立ったら、コーヒーをおごってもらえると嬉しいです。