HTTPコントロールAPIとWebコンソール
[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false
Chuteは、ClashやSurgeのダッシュボードと同様の組み込みHTTPコントロールAPIとWebコンソールを提供します。APIはRESTエンドポイントを通じてエンジンステータス、トラフィック、接続、DNS、ポリシー制御、設定管理を公開します。
Surgeのhttp-api = <シークレット>@<ホスト>:<ポート>はexternal-http-controllerとexternal-http-secretとして読み込まれます。各部分を分けて書くこともできます: http-api-secret、http-api-ui、http-api-corsはそれぞれexternal-http-secret、external-http-ui、external-http-corsとして、http-api-web-dashboardもexternal-http-uiとして読み込まれ、設定はexternal-http-*キーで保存されます。http-api-tlsはサポートされておらず(コントローラーは平文HTTPで動作します)、通知が出るだけです。
external-http-controller(デフォルト: 無効)
external-http-controller = 127.0.0.1:9090
コンソールが配信中に常駐させるリクエストの上限はmacOSで 4 MB、iOS・tvOS・Androidで 1 MBです。
HTTPコントロールサーバーのアドレスとポート。ローカル限定にするには 127.0.0.1 を使います。ループバック以外のアドレス(例: 192.168.1.5:9090)にバインドする場合は external-http-secret の明示が必須です。指定がなければサーバーは起動を拒否し、何が足りないかをログに残します。
ワイルドカードアドレス(0.0.0.0、::、*)はこの検査ではループバック以外として扱われます。すべてのインターフェースで待ち受ける、つまりローカル限定の正反対だからです。受け付けられる書き方は 0.0.0.0:9090、*:9090(同じ意味)、IPv6なら [::]:9090 です — 裸の :::9090 は自動的に角括弧で囲まれます。解析できないアドレスは、コントローラーを黙って無効にする代わりに設定エラーとして報告されます。127.0.0.0/8 全体がループバックであり、127.0.0.1 だけではありません。
external-http-secret(デフォルト: 自動生成されたトークン)
external-http-secret = your-secret-token
API認証に使うBearerトークン。リクエストにはヘッダー Authorization: Bearer <secret> が必要です。トークンはこのヘッダーでのみ受け付けられ、クエリパラメータでは渡せません。比較は定数時間で行われます。認証失敗は 401 と {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}} を返します。データを扱うルートはすべて保護されます: /api/*、Clash互換エイリアス、そしてChute Androidだけが引き続き提供する旧来のルート(/status、/policies、/dns、/recordsなど)で、これらもトークンをこのヘッダーでしか受け付けません。Chute Android自身のリモートダッシュボードは、現在は/api/*だけを使います。Webコンソールのページと静的アセット(/、/assets/…、Chute Androidではさらに /ui)にトークンは不要です(external-http-ui = false ではそれ自体が無くなり、ページは 404 になります)。
このキーが無い場合、Chuteは認証なしで配信するのではなくトークンを生成します。 生成されたトークンはChuteの共有フォルダー内の control-token に所有者のみ読み取り可能な権限で書き出されます — 設定ファイルの隣ではなく、iOSとtvOSではApp Groupコンテナ、Androidではアプリのプライベートデータディレクトリです。再起動後も使い回され、各アプリが表示します(Webコンソールを開くを参照)。コントロールAPIは接続データベースを渡すことができ、その記録には実行中に見たすべての URL・ヘッダー・プロセス名が含まれます。認証なしが既定であってよい理由はありません。
それでも認証なしで配信したい場合は、設定で明示してください:
external-http-secret = none
これが受け付けられるのはループバックへのバインドのときだけです。ループバック以外では、none もキー無しも不十分で、コントローラーは起動を拒否し、何が必要かを伝えます。
アップグレード時の注意: 「
external-http-secretが無い=認証なし」に依存していた場合、ローカルのスクリプトは401を受け取るようになります。アプリから生成トークンを読み取るか、external-http-secret = noneと書いて従来の動作を明示的に選んでください。
external-http-ui(デフォルト: true)
external-http-ui = true
有効にすると、Chuteはコントローラーアドレスで組み込みWebコンソールを提供します。Webコンソールは概要、接続管理、DNS検査、トラフィック監視、ポリシー制御、設定編集を提供します。APIを有効にしたままUIを無効にするにはfalseに設定します。
Webコンソールを開く
コンソールはコントローラーのアドレスで提供されます。各アプリはアドレスとトークンを渡してくれます — 自動生成されたトークンも含めてで、そうでなければ読む手段がありません:
- Chute Mac: メニューバー → Webコンソールを開く、およびWebコンソールのトークンをコピー。接続の詳細ウィンドウにも リクエストと履歴 があり、コンソールを開きます — 開くのはホームで、その接続そのものではありません。
- Chute iOS: コントロールパネル → Webコンソールの行 → 開く、アドレスをコピー、アクセストークンをコピー。
- Chute tvOS: コントロールパネルにはWebコンソールアドレス という独立した行があり、ホストとポートを表示します。選択すると、リスナーが他のデバイスから到達可能ならQRコードが表示されます — サインイン用トークンは画面ではなくコードの中にだけ入っています。コントローラーがループバックにバインドされている場合は代わりに説明が表示されます。ループバックのコンソールはスマートフォンから開けないからです。
- Chute Android: コントロールパネル → Webコンソールのアドレス → 開く または アドレスをコピー、そしてタップでコピーできる 生成されたアクセストークン の行。トークンが自分で設定したシークレットの場合はどちらの行も現れず、そのシークレットが表示されることはありません。
これらが示すアドレスはトークンをクエリパラメータとして含みます。ページは読み込み時にそれを消費してアドレスバーから取り除くため、リンクを開くだけでサインインが完了し、32 桁の 16 進数を書き写す必要はありません。
external-http-cors(デフォルト: false)
external-http-cors = true
APIレスポンスにCORS(Cross-Origin Resource Sharing)ヘッダーを有効にします。Webコンソールやサードパーティツールが異なるオリジンからAPIにアクセスする必要がある場合に便利です。
APIエンドポイント:
| メソッド | エンドポイント | 説明 |
|---|---|---|
GET |
/api/status |
ランタイムステータス、ポート、稼働時間 |
GET |
/api/traffic |
グローバルおよびポリシーごとのトラフィックカウンター |
GET |
/api/connections |
現在のアクティブな接続 |
DELETE |
/api/connections/:id |
接続を閉じる |
GET |
/api/connections/history |
履歴接続レコード |
GET |
/api/connections/processes |
プロセスごとの接続統計 |
GET |
/api/connections/:id/request |
接続のキャプチャされたリクエストデータ |
GET |
/api/connections/:id/response |
接続のキャプチャされたレスポンスデータ |
GET |
/api/dns |
DNSキャッシュレコード |
DELETE |
/api/dns/cache |
DNSキャッシュを消去 |
DELETE |
/api/dns/records/:domain |
単一のDNSレコードを削除 |
GET |
/api/config |
現在の設定 |
PUT |
/api/config |
設定を再読み込み |
POST |
/api/config/validate |
設定を解析してエラーを報告する(読み込みはしない) |
GET |
/api/policies |
ポリシーグループと現在の選択。各項目にhiddenが付き、hidden=trueのグループではtrue |
PUT |
/api/policies/:group |
ポリシーグループの選択を変更 |
PUT |
/api/mode |
アウトバウンドモードを設定 |
GET |
/api/features |
機能スイッチの状態 |
PUT |
/api/features/mitm |
MitMを切り替え |
PUT |
/api/features/record-traffic |
トラフィック記録を切り替え |
GET |
/api/rules |
マッチャーが実際にたどるルール表、各ルールの出どころ、命中した書き換えルール |
POST |
/api/rules/match |
リクエストがどこへ送られるか(実際には送らない) |
GET |
/api/rules/user |
実行時に追加されたルール。モジュールと設定より先にマッチします |
PUT |
/api/rules/user |
実行時ルールを置き換える |
POST |
/api/rules/user |
実行時ルールの後ろにルールを追加する |
DELETE |
/api/rules/user |
実行時ルールをすべて削除する |
GET |
/api/logs |
最近のログエントリ |
GET |
/api/loglevel |
現在のログレベルと、書き出し中のセクション |
PUT |
/api/loglevel |
再起動せずにログレベルやセクションを変更 |
GET |
/api/health |
エンジンの健全性: 拒否数、世代、フットプリント、前回の終了 |
GET |
/api/events |
この実行で注目すべき出来事 |
GET |
/api/tailscale |
Tailscaleエンジンの現在の状態 |
GET |
/api/scripts |
オンデマンドで実行できるgenericスクリプトの一覧 |
POST |
/api/scripts/run |
genericスクリプトを名前で1つ実行 |
POST |
/api/diagnostics/ping |
ICMPまたはTCPによる到達性プローブ |
POST |
/api/diagnostics/dns-query |
実行中のリゾルバーでドメインを解決 |
POST |
/api/diagnostics/egress-probe |
アドレスを確認: Appleのエンジンではデバイス自身のアドレス。Androidでは、プロキシの出口ではなく、物理ネットワーク上でのデバイスの公開アドレス |
POST |
/api/diagnostics/internet-test |
直接インターネットテスト: プロキシを通さずにinternet-test-urlを取得 |
POST |
/api/diagnostics/url-test/:policy |
ポリシーのレイテンシテストを実行 |
POST |
/api/diagnostics/bundle |
秘匿処理済みの診断アーカイブを作成 |
GET |
/api/connections/export |
接続をHAR 1.2 として書き出し |
GET |
/api/rewrites |
すべての書き換え・モックレスポンスのファミリーとMitMホスト一覧 |
GET |
/api/rewrites/:family |
1つのファミリーのルール |
POST |
/api/rewrites/:family |
ルールを追加 |
DELETE |
/api/rewrites/:family/:id |
ルールを削除 |
DELETE |
/api/rewrites/:family |
ファミリーをクリア |
GET |
/api/mitm/hosts |
現在復号しているホスト |
POST |
/api/mitm/hosts |
ホストを追加 |
DELETE |
/api/mitm/hosts/:host |
ホストを削除 |
DELETE |
/api/mitm/hosts |
一覧をクリア |
GET |
/api/rules/providers |
ルールプロバイダーとルールセット、およびそれぞれの状態(読み込めなかった理由を含む) |
エンドポイントの注意点:
GET /api/featuresは各スイッチを設定どおりに報告します —record_traffic、mitm、mitm_h2、mitm_auto_quic_block、rewrite— そしてlicensedも報告します。effectiveは実際に動作しているものを示し、対象はrecord_traffic、mitm、rewrite、scripts、lan_proxyの5項目だけです。無料版では5つともfalseなので、スイッチがオンでもそのeffectiveの項目がfalseになることがあります。inactiveは、動作中の設定が求めているのにこのエディションでは動作しないものを示すオブジェクトです: カウントのscripts、scriptRules、dnsScripts、rewrites、mapLocalsと、フラグのmitm、bodyCapture、lanProxy、exitNode(Tailscaleでの広告。行うのはChute Macだけです)。ライセンスがある場合、またはエンジンが停止している場合は、カウントはすべて0、フラグはすべてfalseです。GET /api/connectionsはlimit(正の整数、デフォルトおよび最大は1000)とcursor(カーソルより大きいidを持つ接続のみを返す)を受け付けます。レスポンスのdataにはconnections、total、page_size、has_more、server_timeが含まれ、さらにページがある場合はnext_cursorも含まれます。since(秒。以前の応答のserver_time)を指定すると、その時点以降に変化した接続だけを返し、active_ids(現在開いているすべての接続のID)を追加します。以前の応答にあってここに無い接続は閉じています。server_timeより後のsinceは0として扱われるため、すべての接続が返されます。GET /api/connections/historyはlimit(デフォルト100、最大1000)とcursor/before(同義。両方を渡すと拒否されます)を受け付けます。GET /api/connections/:id/requestと.../responseは{"connection_id": <id>, "data": "<base64>"}を返します。2 MiBを超えるキャプチャは413を返します。Chute Proが無い場合はどちらも403を返し、request data is not availableまたはresponse data is not availableが付きます。以前のライセンスがある実行中に記録されたボディについても同様です。GET /api/configは、動作中の設定を書かれたとおりに、資格情報も含めて返します —http-auth、external-http-secret、ca-p12、ca-passphrase、WireGuardの鍵、そしてすべてのプロキシのパスワードです。つまり制御APIにアクセスできれば、これらすべてにアクセスできます。資格情報を<redacted>に置き換えるのは診断バンドルだけで、そのコピーは読み込み直せません:PUT /api/configに送った設定のどこかに<redacted>が残っていると、リクエストは400で拒否され、最初のそのような行を示すメッセージが返ります。代わりに元の設定を送信してください。GETとPUT /api/configは/api/configsとしても、またClashのエイリアス/configsとしても到達できます。PUT /api/configはJSON{"configuration": "<full text>"}、または生の設定テキストをリクエストボディとして受け付けます(上限1 MB)。成功するとエンジンが再読み込みされます — 実行されていなかった場合は起動します。PUT /api/policies/:groupは、ボディのキーpolicy、name、selected、selectのうち最初に存在するものから選択値を取ります。値はポリシー名でも、数値インデックスの文字列でも構いません。特殊なグループ名GLOBALはグローバル選択ポリシーを設定します。GET /api/policiesでは、すべてのポリシー、グループ、グループのメンバーがendpoint(現在たどり着くポリシー。グループを順にたどり、組み込みのPROXYはグローバルモードで選択されたポリシーまでたどります)とendpoint_ping(そのポリシーのレイテンシ)を持ちます。グループ自身のpingは測定されないため0で、グループやPROXYについて見るべき値はendpoint_pingです。PUT /api/modeはJSON数値を必要とします:{"mode": 0}—0はルール、1は直接接続、2はプロキシです。PUT /api/features/mitmとPUT /api/features/record-trafficは{"enabled": true}を取ります。GET /api/logsはsince(Unix秒)を受け付けます。インメモリバッファは最新の1000エントリを保持し、各エントリは{timestamp, wall_time, level, section, message}です —timestampとwall_timeは同じUnix秒の値を持ち、時計が進まないときはエントリの順序が厳密に保たれるよう少しだけ前に進められます。GET /api/healthはエンジンが何を保持しているか、直近で何を理由に拒否したか、そして前回の実行がどう終わったか(clean、unclean、suspected_memory— トラブルシューティングを参照)を返します。addressFamilyはChuteがIPv6の出口をどう判断しているかを示し —ipv6はhealthy、confirming、degradedのいずれか — それに対して行ったことの回数も含みます。AppleのエンジンではselfLoopがセルフループ防止の状況を報告します。どちらもアドレスは含みません。GET /api/eventsはメモリ上のリングを返します。?persisted=1はこの実行の保存済み履歴を読み、記録が無効ならavailable: falseを返します。[Tailscale]セクションが無い場合、GET /api/tailscaleはstate: "idle"を返します。これはエラーではなく正常な答えです。POST /api/diagnostics/*の各プローブはクエリ文字列でもJSONボディでも引数を受け取り、10 秒で打ち切られ、必ず 1 回だけ応答します。url-test/:policyは定義されていないポリシー名を拒否し、REJECTを計測したりはしません。GET /api/scriptsは有効なgenericスクリプトを{name, type}の形で一覧します。POST /api/scripts/runはボディまたはクエリ文字列からnameを取り、診断プローブと同じように打ち切られ、{name, timedOut, result}を返します —timedOutは、$doneを呼ばずに終わったスクリプトと最後まで走ったスクリプトを見分けます。有効なgenericスクリプトでない名前は404です。Chute Proが無い場合は403、script is not availableを返します。POST /api/rules/matchは接続を開かずにリクエストがどこへ行くかを答えます。host(または host とポートを取り出すためのurl。URL-REGEXルールはこのurlを書かれたとおりに照合します。実際のトラフィックでこのルールが見るのは平文のhttp://リクエストだけですが)、port(既定 443)、および任意でip、protocol、process、process_path、src_ip、src_port、in_port、in_type、in_user、in_name、network、ssid、bssid、from_tun、user_agentを受け取ります — 知らないフィールドは無視されず、受理可能な一覧とともに拒否されます。応答にはmatched(ルールの行、種別、指名するポリシー、そしてグループが現在指しているresolved_policy)、policy、need_resolve、そして算出の根拠となったrule_countとmatch_generationが含まれます。ドメインは 2 回マッチされる(名前で 1 回、アドレスが判明してからもう 1 回)ためpassesは 1 パスにつき 1 項目です。ipを渡さない場合は解決前のパスだけになり、応答はnoteでそう伝えます。explain=trueを加えると、同じくマッチし得た候補ルールを最大 50 件、展開しなかったルールセットの数とともに返します。POST /api/config/validateは設定を解析して捨てます。動作中のエンジンは何も取り込みません。{"configuration": "<full text>"}として送るか、生のテキストをそのまま送ってください。応答はvalid、error_count、advisory_count、rule_count、policy_count、および{line, severity, content, error}からなるerrorsの一覧です —severityは拒否された行と、留保付きで受理された行を区別し、contentは問題の行を書かれたとおりに(資格情報も含めて。壊れた[Proxy]行は、まさにパスワードを入れるフィールドで壊れていることが多いからです)、4096文字で切り詰めたものです。PUT /api/configの前に使ってください。あちらはデバッグ中の実行を再起動してしまいます。GET /api/loglevelは現在のlevel、nslog_level、ファイルに書き出し中のsections、そして設定可能なavailable_levels/available_sectionsを返します。PUT(またはPATCH)はlevel、sections、またはその両方を受け取ります。sectionsはセクション名の配列か文字列"all"で、空の配列は拒否されます — 記録を止めたい場合はlevelをnoneにしてください。この方法でレベルを変えても実行は再起動されません。それがこのAPIの意義です: ファイルに書いたloglevel = verboseは再読み込みが必要で、再読み込みは見ようとしていたものを失わせます。GET /api/rulesはrewrite_hitsも返します。この実行で命中した書き換え・モックレスポンスのルールとその回数です。そこに現れないルールは一度も命中していません — 「書き換えが効かない」の最も一般的な理由がこれです。この表が追跡するのは最大 512 種類のルールで、それを超えた分はrewrite_hit_dropped_rulesとして報告されます。rulesはマッチャーが実際にたどるすべてのルールを順番に並べます。Tailscaleの自動ルール、/api/rules/userで追加されたルール、モジュールのルール、設定の[Rule]セクションの順で、最後がFINALです。rule_regionsは各行の出どころを同じ添字で示します(front、user、module、configuration)。/api/rules/userは、エンジンの実行中に、リロードせず設定ファイルにも触れずに追加したルールを保持します。これらはTailscaleの自動ルールの後、モジュールのルールと設定の[Rule]セクションより前に、指定した順でマッチします。GETで一覧し、PUTで置き換え、POSTで既存のものの後ろに追加します。PUTとPOSTはどちらも{"rules": ["<rule line>", ...]}または単独の{"rule": "<rule line>"}を受け取り、ルールはファイルと同じ書き方で書きます。DELETEはすべて削除します。書き込みはすべてか無かです: 解析できない行やFINALがあると400で拒否され、ルールは元のままです。動作中の設定で定義されていないポリシーを指すルールも受け入れられ —REJECTでフェイルクローズします —warningsに名前が挙がります。close_reroutedはデフォルトでtrueで、変更されたルールが別の経路に回す接続だけを閉じます。falseにするとすべての接続が開いたままになります —DELETEでは?close_rerouted=falseとして渡します。どのメソッドも現在のrulesを返します。ルールはリロード後も保持され、エンジンが停止すると消えます。このパスではPATCHは受け付けられません。POST /api/rewrites/:familyは{"rule": "<configuration line>"}を受け取ります。設定ファイルに書くのと同じ一行です。解析できない行は400で拒否され、決して命中しないルールとして保存されることはありません。:familyはurl-rewrite、header-rewrite、body-rewrite、mockのいずれかです。この方法で追加したルールは実行中のエンジンにのみ存在し、設定ファイルには書き戻されません。GET /api/connections/export?format=harはHAR 1.2 ドキュメントを、POST /api/diagnostics/bundleは zip を返します。どちらもファイルなので、他のエンドポイントと違い{"ok": ..., "data": ...}のエンベロープには包まれません。exportはsource(既定はcurrent、ほかにhistory)、limit(既定 100、最大 300)、ids、および取得済みペイロードを含めるbodies=1を受け付けます。各エントリにはHARに対応するフィールドが無い情報 — 選ばれたポリシー、命中したルール、発動した書き換え — が_klオブジェクトとして付きます。- チェーンされた接続の
GET /api/connectionsとGET /api/connections/historyのレコードはchainPathを持ちます。この端末から出口までの経路で、例えばAirport/HK-01 → Landingです。単一のポリシーを使った接続では空で、HAR 書き出しでは_kl.chainになります。GET /api/trafficのポリシー別カウンターでは、上流もチェーン接続のために運んだバイト数を数えます。全体の合計には一度だけ数えられます。
例 — ステータスを読み取り、ポリシーグループを切り替える:
curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:9090/api/status
{"ok":true,"data":{"running":true,"outbound_mode":0,"mitm":false, ...}}
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"policy": "ProxyB"}' http://127.0.0.1:9090/api/policies/MainGroup
{"ok":true,"data":{"outbound_mode":0,"selectable_groups":[...], ...}}
例 — リクエストを送る前に、それがどこへ行くかを尋ねます:
curl -X POST -H "Authorization: Bearer your-secret-token" \
-d '{"url": "https://api.example.com/v1/orders", "explain": true}' \
http://127.0.0.1:9090/api/rules/match
{"ok":true,"data":{"policy":"MainGroup","matched":{"rule":"DOMAIN-SUFFIX,example.com,MainGroup", ...}, ...}}
再現している最中に、実行を再起動せずログを 1 つのサブシステムに絞ります:
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
http://127.0.0.1:9090/api/loglevel
注意: この機能はデフォルトで無効です。全てのレスポンスは、成功時には
{"ok": true, "data": {...}}、エラー時には{"ok": false, "error": {"code": "...", "message": "..."}}のエンベロープを使用します。リクエストボディの上限は1 MBです。
PUTエンドポイントはPATCHも受け付けます。サードパーティのダッシュボード向けに、Clash互換のエイリアスパスが利用可能です:/version、/traffic、/connections、/configs、/proxies、/rules— パスには到達できますが、レスポンスはClashのスキーマではなくChute自身のエンベロープとフィールド名を使用するため(/versionは{"name", "run_id", "egress_probe"}を返し、egress_probeはAppleエンジンではnetwork_address、Androidエンジンではegress_ipです)、Clashダッシュボードはそのままでは動作しません。
本ページは英語版からの翻訳です。内容に相違がある場合は、英語版が優先されます。