ドキュメント コントローラー API

コントローラー API ドキュメント

Clash / Mihomo のコアはローカルの RESTful インターフェース（外部コントローラー）を公開しており、ダッシュボードやスクリプトはこれを通じてデータ取得や指令送信を行います。約30のエンドポイントを機能別にまとめ、リクエスト方法とレスポンスフィールドを紹介します。

リクエスト例

ダッシュボードやスクリプトからコアへ送るすべてのリクエストには、以下の形式で認証ヘッダーを付加する必要があります。

curl Shell
curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true \
  -d '{"path": "", "payload": ""}' -X PUT
  • ${secret} は設定ファイルで指定した secret キーです
  • ${controller-api} は設定ファイルで指定した external-controller のリスニングアドレスです
  • ?force=true はクエリパラメータで、一部のエンドポイントで必要です
  • '{"path": "", "payload": ""}' は更新するリソースデータです

リクエストにファイルパスを渡す必要があり、そのパスが mihomo の作業ディレクトリ外にある場合は、SAFE_PATHS 環境変数を手動で設定してセーフパスに追加する必要があります。書式は OS の PATH 変数と同じです（Windows はセミコロン区切り、その他はコロン区切り）。

ログ

GETWS/logs

リアルタイムログを取得します。

  • オプションパラメータ ?level=log_level、log_level は info/warning/error/debug から選択可能
  • オプションパラメータ ?format=structured を付けると構造化ログを出力（time/level/message/fields を含む）
  • 標準モードでは1行ごとに1つの JSON を送信：type ログレベル、payload ログ内容
  • 構造化モード：time（HH:MM:SS）、level、message、fields（追加フィールド配列）

トラフィック情報

GETWS/traffic

リアルタイムトラフィックを取得します。up/down の単位はバイト/秒、upTotal/downTotal の単位はバイトで、1秒ごとに送信されます。

  • up 現在のアップロード速度　down 現在のダウンロード速度
  • upTotal 累計アップロードバイト数　downTotal 累計ダウンロードバイト数

メモリ情報

GETWS/memory

リアルタイムのメモリ使用量（バイト）を取得します。1秒ごとに送信されます。

  • inuse 現在のメモリ使用量　oslimit システムメモリ制限（常に 0）

バージョン情報

GET/version

コアのバージョン情報を取得します。

  • meta Meta 版かどうか　version バージョン番号の文字列

キャッシュ

POST/cache/fakeip/flush

fakeip キャッシュをクリアし、HTTP 204 を返します。

POST/cache/dns/flush

DNS キャッシュをクリアし、HTTP 204 を返します。

実行時設定

GET/configs

現在の実行時設定を取得し、port、socks-port、mixed-port、mode、log-level、allow-lan、ipv6、tun などのフィールドを含む JSON オブジェクトを返します。

PUT/configs

基本設定を再読み込みします。パラメータ ?force=true を付与し、HTTP 204 を返します。

PATCH/configs

基本設定を部分的に更新します。例：'{"mixed-port": 7890}'、HTTP 204 を返します。

POST/configs/geo

GEO データベースを更新します。'{"path": "", "payload": ""}' を付与し、HTTP 204 を返します。

POST/restart

コアを再起動します。'{"path": "", "payload": ""}' を付与し、HTTP 204 を返します。

更新

POST/upgrade

コアを更新します。?channel=xxx で更新チャンネルを指定、?force=true で強制更新でき、{"status": "ok"} を返します。

POST/upgrade/ui

ダッシュボードを更新します（事前に設定で external-ui を指定する必要あり）。{"status": "ok"} を返します。

POST/upgrade/geo

GEO データベースを更新し、HTTP 204 を返します。

プロキシグループ

GET/group

全プロキシグループの情報を取得します。proxies 配列を返し、各項目の形式は /proxies/{name} と同じです。

GET/group/{group_name}

指定したプロキシグループの情報を取得します。形式は /proxies/{name} と同じです。

GET/group/{group_name}/delay

プロキシグループ内の全ノードの速度テストを行い、新しいレイテンシデータを返すとともに、該当する自動プロキシグループの現在の fixed 固定選択をクリアします。

  • パラメータ ?url=xxx&timeout=5000 を付与
  • オプション ?expected=xxx、期待する HTTP レスポンスステータスコード。範囲指定も可能（例：200/204、200-299）
  • ノード名をキー、レイテンシ（ミリ秒）を値とするオブジェクトを返します。例：{"ノードA": 120, "ノードB": 350}

プロキシ

GET/proxies

全プロキシ/プロキシグループの情報を取得します。名前をキーとする proxies オブジェクトを返し、共通フィールドは以下の通りです：

  • name/type（Shadowsocks、VMess、DIRECT、Selector、URLTest など）
  • udp/uot/xudp/tfo/mptcp/smux 対応フラグ
  • alive 現在の生存状態、history レイテンシ履歴（time+delay）、extra テストURLごとに分類した追加履歴
  • interface/routing-mark/provider-name/dialer-proxy
  • プロキシグループには追加で：now 現在の選択中ノード（LoadBalance にはこのフィールドなし）、all メンバー一覧、testUrl、hidden、icon、emptyFallback、expectedStatus（Selector にはなし）、fixed（URLTest/Fallback のみ）
GET/proxies/{name}

指定したプロキシ/プロキシグループの情報を取得します。フィールドは上記と同じです（通常のプロキシは共通フィールドのみ）。

PUT/proxies/{name}

そのプロキシグループの現在選択中のノードを切り替えます。'{"name":"日本"}' を付与し、HTTP 204 を返します。

DELETE/proxies/{name}

そのプロキシ/プロキシグループの fixed 固定選択をクリアします（Selector タイプは除く）。HTTP 204 を返します。

GET/proxies/{name}/delay

指定したプロキシの速度テストを行います。?url=xxx&timeout=5000（オプション ?expected=xxx）を付与し、{"delay": 120} を返します。

プロキシプロバイダー

GET/providers/proxies

全プロキシプロバイダーの情報を取得します。プロバイダー名をキーとする providers オブジェクトを返し、各プロバイダーにはメタ情報とプロキシ一覧が含まれます。

GET/providers/proxies/{name}

指定したプロキシプロバイダーの情報を取得します。設定情報と proxies プロキシ一覧を含みます。

PUT/providers/proxies/{name}

そのプロキシプロバイダーを更新し、HTTP 204 を返します。

GET/providers/proxies/{name}/healthcheck

そのプロキシプロバイダーのヘルスチェックを実行し、HTTP 204 を返します。

GET/providers/proxies/{name}/{proxy_name}

プロバイダー内の指定したプロキシの情報を取得します。フィールドは /proxies/{name} と同じです。

GET/providers/proxies/{name}/{proxy_name}/healthcheck

プロバイダー内の指定したプロキシの速度テストを行います。?url=xxx&timeout=5000 を付与し、{"delay": 120} を返します。

ルール

GET/rules

全ルールを取得します。rules 配列を返し、各項目には以下が含まれます：

  • index インデックス（0から開始）　type ルールタイプ　payload マッチ内容　proxy 対象のプロキシ/プロキシグループ
  • size ルール項目数（GEOIP/GEOSITE のみ有効、それ以外は -1）
  • オプション extra：disabled/hitCount/hitAt/missCount/missAt
PATCH/rules/disable

インデックスを指定してルールを一時的に無効化/有効化します（再起動後は無効）。'{"0": false,"1": true}' を付与し、HTTP 204 を返します。

ルールプロバイダー

GET/providers/rules

全ルールプロバイダーの情報を取得します。名前をキーとする providers オブジェクトを返します。

PUT/providers/rules/{name}

指定したルールプロバイダーを更新し、HTTP 204 を返します。

接続

GETWS/connections

アクティブな接続情報を取得します。オプションパラメータ ?interval=milliseconds（更新間隔、デフォルト1000ms）。

  • downloadTotal/uploadTotal 累計トラフィック　memory 現在のメモリ使用量
  • connections アクティブな接続の配列：id、metadata（送信元/宛先アドレス、プロトコル、プロセス名など）、upload/download、start、chains/providerChains プロキシチェーン、rule/rulePayload ヒットしたルール
DELETE/connections

全ての接続を切断し、HTTP 204 を返します。

DELETE/connections/{id}

指定した接続を切断し、HTTP 204 を返します。

DNS クエリ

GET/dns/query

指定した名前とタイプの DNS クエリ結果を取得します。?name=example.com&type=A を付与します。

  • Status DNS レスポンスコード　Question クエリ質問の配列
  • TC/RD/RA/AD/CD 各種 DNS フラグビット
  • オプション Answer/Authority/Additional：いずれもレコード配列で、各項目に name/type/TTL/data を含みます

ストレージ

GET/storage/{key}

指定した key のストレージ値を取得します。存在しない場合は null を返します。

PUT/storage/{key}

指定した key に値を書き込みます（正しい JSON である必要があり、最大 1MB）。'{"foo": "bar"}' を付与し、HTTP 204 を返します。

DELETE/storage/{key}

指定した key のストレージ値を削除し、HTTP 204 を返します。

DEBUG

/debug 系のエンドポイントを使うには、コア起動時のログレベルを debug に設定する必要があります。

PUT/debug/gc

GC を1回実行し、HTTP 204 を返します。

GET/debug/pprof

ブラウザで http://${controller-api}/debug/pprof を開くと、生の DEBUG 情報を確認できます：

  • allocs：関数呼び出しごとのメモリ割り当て状況（スタック上/ヒープ上のサイズと回数）。メモリリークや頻繁なメモリ確保などの問題を調査する際に使用します
  • heap：ヒープ上のメモリ使用の詳細。割り当てブロックのサイズ、数、アドレスを含み、サイズ順に並べることでメモリ使用量が多い箇所を特定できます

Graphviz をインストールすると、グラフィカルなレポートを表示できます：

Shell pprof
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs

ブラウザで http://${controller-api}/debug/pprof/heap?raw=true にアクセスするとレポートファイルをダウンロードできます。問題が発生した際は issue にアップロードすると調査に役立ちます。