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ダッシュボードはそのままでは動作しません。

S. Smart Rabbit LLC © All Rights Reserved            updated 2026-11-19 16:07:28

本ページは英語版からの翻訳です。内容に相違がある場合は、英語版が優先されます。

results matching ""

    No results matching ""