AI 代理程式與 MCP

Claude Code、Codex、Cursor、Gemini CLI、Claude Desktop、Windsurf、Cline、Zed、Hermes Agent、OpenClaw、OpenCode、GitHub Copilot CLI以及其他 MCP 用戶端的逐步設定說明，請參閱在 AI 代理程式中設定 Kilobat。

把這段提示交給 Claude Code、Codex 或 Cursor 之類的代理程式：

MCP 伺服器

kilobat mcp 透過 stdio 使用 Model Context Protocol。加入 Claude Code：

claude mcp add kilobat -- kilobat mcp

或加入任何讀取 mcpServers 設定的用戶端：

{ "mcpServers": { "kilobat": { "command": "kilobat", "args": ["mcp"] } } }

唯讀工具：get_status、diagnose_network、diagnose_connection、get_conditions、get_updaters、get_uploads、get_data_pack、get_wifi、scan_wifi、suggest_wifi_channel、get_usage_report、compare_usage、get_app_bandwidth、get_access_policy、get_network_history、list_sessions、agent_network_log（AI 代理程式及其命令連接過的每個主機）、benchmark_dns、check_url、list_connections、list_devices、trace_route、get_route_history、compare_speed_tests、get_exit_path（僅當代理程式傳入 public_ip 時向 Cloudflare 查詢你的公網 IP）、check_vpn_leaks（洩漏測試，會查詢外部服務）、list_networks、get_fastest_dns（App 背景靜默測試得出的各網路最快 DNS）、list_rules、list_approvals、list_blocked_connections、explain_verdict（與主機或 App 符合的每條規則及決定結果的規則）、check_host_reputation（主機是否在惡意軟體、網路釣魚、詐騙或追蹤器列表中，在此 Mac 上檢查）、get_protection_status、run_stutter_test 和 get_game_ping（只傳送 ping）、get_nearby_radios、get_captive_portal（Wi-Fi 登入頁面，與 kilobat portal --json 相同）、service_status（查詢指定服務或正在執行的 App 的公開狀態頁面）以及 create_support_report（交由代理程式轉給你的供應商報告）。它們傳回與 CLI 相同的 JSON。run_speedtest 消耗資料，run_lan_test 在你自己的網路上傳輸五秒資料並先詢問，keep_awake 和 release_awake 在設定時間內阻止閒置睡眠而不更改設定；允許後，帶 lid_closed 的 keep_awake 也會在闔上螢幕時讓 Mac 保持運作，並先詢問你。變更類工具（set_profile、set_app_rule、set_new_app_mode、decide_approval、block_destination、set_budget、set_data_pack、set_app_quota、set_network_cost、set_updater_pause、set_kill_switch、set_protection（還會告知代理程式絕不能為完成自身要求而關閉防護）、hold_upload（暫緩另一個 App 的上傳）、set_dns（還會清空快取）、set_fastest_dns、set_dns_fallback 和 set_airdrop_visibility（開啟 AirDrop 設定））標記為變更，其說明會要求代理程式先詢問你。

連接代理程式

沒有額外資訊時，Kilobat 是依代理程式的流量和 CPU 判斷，所以一個安靜的代理程式可能已經完成，也可能正在等你。代理程式的 hook 會告訴 Kilobat 一次執行屬於哪個專案、什麼時候在等你、什麼時候完成。每個 hook 都執行 kilobat agent-event，它不輸出任何內容、立即返回，且一律以 0 結束，所以不會弄壞代理程式。App 沒在執行時，事件會先存進一個小檔案，等 App 打開時再讀取。Kilobat 只讀取工作階段 ID、資料夾和簡短的狀態文字，絕不讀取提示或回覆。請把這些內容合併進你已有的 hook。

Claude Code，寫在 ~/.claude/settings.json。每個 hook 都會從 stdin 收到含工作階段 ID 和資料夾的 JSON，由 --stdin-json 讀取。權限或輸入提示代表「等待中」；Stop 代表背景工作完成後即「完成」；達到速率限制則代表等待重置。

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "StopFailure": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }]
  }
}

Codex，最簡單的做法：在 ~/.codex/config.toml 加上 notify。Codex 每一輪結束後會傳入一個 JSON 參數，由 --json-arg 讀取。它只會回報「完成」，而且 Codex 只執行一個 notify 程式。

notify = ["kilobat", "agent-event", "done", "--agent", "codex", "--json-arg"]

若也要回報「等待中」，請改用 ~/.codex/hooks.json 中的 Codex hook，並用 /hooks 信任它們：

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }],
    "PermissionRequest": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent codex --stdin-json" }] }]
  }
}

Gemini CLI，寫在 ~/.gemini/settings.json。Gemini CLI 以 node 執行，所以 Kilobat 無法把它的流量對應到該次執行，但狀態仍會傳過來。

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }],
    "BeforeAgent": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }],
    "AfterAgent": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent gemini --stdin-json" }] }]
  }
}

Cline（CLI、SDK 和 Kanban）：安裝 Kilobat 的外掛，它只會在 Cline 的外掛存放區加入一個檔案，不更改其他設定。cline plugin uninstall kilobat 可以移除它。

cline plugin install https://kilobat.app/agents/cline/kilobat.ts

它會回報執行中、完成、失敗（Cline 保持開啟時）、已取消、達到速率限制（Cline 自己的重試用完後），以及 Cline 向你提問時的等待中。它會等子代理程式和隊友都結束，才把一次執行算作完成。外掛看不到 Cline 的核准提示，所以這部分由流量和 CPU 偵測負責。

其他任何代理程式都能從自己的 hook 呼叫 kilobat agent-event start|working|waiting|done|failed --agent <name> --session <id> --cwd <folder>。手動試的時候加上 --verbose，就能看到發生了什麼。

代理程式網路日誌

當 Claude Code、Codex、Cursor、Gemini CLI、Aider、Windsurf、Claude Desktop、ChatGPT 或其他代理程式執行時，Kilobat 會記錄它和它啟動的程序連過的每台主機：npm、pip、uv、curl、git、brew、MCP 伺服器，中間隔著 shell 也一樣。每個工作階段從代理程式的程序啟動開始，到它和它啟動的一切都結束為止，依建立連線的程序列出主機，傳送量最多的排在最前面，並附上連接埠和通訊協定、首次和最後出現時間、傳送和接收的位元組數、連線數，以及代理程式執行時所在的專案檔案夾。它在「歷史記錄」›「代理程式網路日誌」，代理程式執行時，選單會顯示一行，例如「Claude Code · 14 台主機 · 已傳送 2.1 MB」。「拷貝為 Markdown」會把工作階段的表格放到剪貼板，方便用在問題回報或審查。

標記只說明哪些值得再看一眼，從不代表出了問題：首次（這台 Mac 上之前沒有代理程式連過那台主機；registry.npmjs.org、pypi.org、github.com 等知名套件庫，以及代理程式自身的服務，永遠不會被當成新的）、未加密 HTTP（連接埠 80）、大量上傳（傳送超過 10 MB 到代理程式自身服務以外的單一主機，所以 Claude Code 把上下文傳給 Anthropic 不會被標記）、僅位址（不知道主機名稱）和分享或通道（一份簡短清單，包括貼上網站、transfer.sh 等檔案分享服務、ngrok 和 trycloudflare.com 等通道，以及 webhook.site 等請求擷取服務）。「只顯示已標記」只會顯示這些。

運作方式：Kilobat 本來就會每秒讀取 macOS 的逐條連線網路統計（與 nettop 相同），以及每條連線所屬的程序。它會從執行檔、直譯器執行的套件（node …/@openai/codex、python3 -m aider）或 App 本身的執行檔辨識代理程式，並追蹤每個代理程式的程序樹：樹中的程序一 fork，核心就會通知它，所以就算只跑十分之一秒的 curl，也能在執行時歸位，而被改掛到 launchd 底下的程序仍屬於該代理程式。最近的代理程式優先，所以在 Cursor 終端機裡執行的 Claude Code 算是 Claude Code 的。主機名稱來自 Kilobat 的網路過濾器（開啟時，即 App 要求的名稱）；或用你 Mac 的解析器查詢知名開發者主機，以及代理程式 curl 或 git URL 中的主機，再比對位址；或來自反向 DNS，這會加上標示，因為那是伺服器的名稱，不是 App 要求的名稱。如果都沒有，該列會顯示位址。

無法看到的內容：macOS 服務代程序產生的流量（DNS 查詢經過 mDNSResponder，下載經過 nsurlsessiond）、Docker 容器和虛擬機器（其流量透過 Docker 或虛擬機器本身的程序離開），以及在編輯器延伸功能主機中執行的 AI 代理程式，例如 VS Code 中的 Cline 或 Copilot，它們無法與編輯器區分。在 Cursor 和 Windsurf 中，在其終端機輸入的命令計入該 App。在兩次一秒取樣之間開啟又關閉的連線仍計入工作階段位元組數，但沒有主機。核心的 fork 通知被處理前就啟動並結束的程序可能被遺漏。記錄由 Kilobat Pro 建立，僅保存在此 Mac 的 ~/Library/Application Support/Kilobat/agent-network-log.json 中，保留 30 天，絕不會傳送到其他地方；「清除」提供過去一小時、今天或全部選項。

開啟防護後，被 Kilobat 拒絕的連線也會出現在工作階段中，標記為「已阻擋」並註明列表或代理程式守衛規則，即使它們沒有傳輸任何位元組。

在終端機中，kilobat agent-log 會輸出最近一次工作階段；由代理程式執行時，則輸出它自己的工作階段；--all、--since 2h、--agent claude、--flagged 和 --json 可以縮小範圍。讀取免費，kilobat agent-log --watch 不需要 App 或 Pro 就能在終端機中即時記錄，不儲存任何內容。代理程式可呼叫唯讀 MCP 工具 agent_network_log，不帶參數時會傳回它自己的工作階段，讓代理程式能查看它執行的安裝連到了哪裡。

清除歷史記錄或忘記網站

在「設定 › 資料與隱私權」中，忘記網站會從遭阻擋的嘗試、AI 代理程式網路記錄、代理程式執行和保持喚醒工作階段的目的地以及防護通知記錄中移除主機。選擇包含子網域還會移除 www.example.com 等名稱。「清除網站歷史記錄」會移除過去一小時、午夜以來或全部相同記錄。遭阻擋的嘗試和 AI 代理程式網路記錄也有各自的清除選單；主機列的快捷選單提供「忘記」。清除歷史記錄會保留規則和防護設定。之後的活動仍可再次記錄。

在終端機中使用 kilobat history forget example.com --subdomains --json 或 kilobat history clear --hour（也可使用 --today 和 --all）。App 執行時，命令會要求 App 刪除即時記錄；App 關閉時則編輯儲存的歷史記錄。MCP clear_history 執行相同操作，但只在你要求 AI 代理程式刪除歷史記錄時執行。刪除無法復原；結果會統計從各歷史記錄中移除的項目。

App 在最前面時

閱讀或簡報時，茶杯選單裡的「App 在最前面時」只會在你選的 App 位於最前面時讓 Mac 保持喚醒，一切換到別的 App 就讓它恢復睡眠。茶杯選單裡的「保持螢幕開啟」決定螢幕是否也保持開啟，和 Kilobat 保持喚醒的其他情況一樣。Kilobat 依照 macOS 本身的 App 切換事件運作：它不輪詢、不移動滑鼠，也不偽造活動，所以無法讓你在監控軟體上看起來像在線。它會在 App 結束、你關掉它，或使用電池且電量降到 20%（或你為闔上螢幕執行設定的下限）時結束，而且絕不會在闔上螢幕時撐住 Mac。它有自己獨立的保持狀態，所以切換或結束 App 絕不會結束喚醒工作階段或代理程式執行。在終端機中：kilobat awake --while-frontmost Keynote --display。

插電時

打開「插電時保持喚醒」（「設定」›「喚醒與代理程式」），或茶杯選單裡的「插電時」，接上電源轉接器後，Mac 就會保持喚醒直到你拔掉為止，狀態列會顯示「插電時保持喚醒」。「保持螢幕開啟」決定螢幕是否也保持開啟。關掉之後，它會維持關閉直到你下次插電，即使 Kilobat 重新啟動也一樣。Kilobat 透過 macOS 本身的電源來源通知得知插拔，不需要輪詢。拔掉電源只會結束因插電而開始的工作階段：你自己開始的工作階段、正在等的下載、最前面的 App、代理程式執行或從終端機發起的保持都會繼續。它絕不會在闔上螢幕時讓 Mac 繼續執行。在終端機中：kilobat settings awake-on-power on，螢幕則用 kilobat settings keep-screen-on on；kilobat conditions --json 會將它回報為 awakeOnPower。

闔上螢幕時繼續執行

闔上螢幕會讓 Mac 睡眠，即使 Kilobat 正讓它保持喚醒也一樣，除非你在「設定」›「喚醒與代理程式」中允許闔上螢幕時執行。這會安裝一個以 root 身分執行的小型輔助程式；macOS 會要求你在「系統設定」›「一般」›「登入項目」中允許它。開啟後，執行中的代理程式會讓 Mac 在闔上螢幕時繼續運作；在茶杯選單中勾選「闔上螢幕時也保持」的喚醒工作階段也是如此。等待你操作的代理程式，只有在打開「代理程式等待時保持喚醒」時才會撐住，而且最多 30 分鐘。

闔上放在包包裡的 Mac 可能過熱、把電池耗光，所以輔助程式本身會在以下情況讓 Mac 睡眠：電量降到你設定的下限（預設 20%）、Mac 過熱、你選擇只在接電時執行而電源被拔掉、超過你設定的最長時間（最多 8 小時），以及 Kilobat 結束後一分鐘。如果輔助程式或 Mac 在保持期間重新啟動，它會先把設定還原。Kilobat 會顯示每次保持是如何結束的，例如「讓 Mac 睡眠：電量剩 20%」。

在終端機中，kilobat awake --lid-closed 會向 App 要求同樣的保持，無法做到時會說明原因；指令結束時保持也隨之結束。代理程式使用 keep_awake 搭配 lid_closed，其描述會要求它們先向你確認。kilobat conditions --json 會回報 lidClosedAllowed 和目前的 lidHold。

代理程式技能

九個代理程式技能（Agent Skills）教程式碼代理程式用 Kilobat 排解 Mac 的網路問題，並讓長時間的執行不中斷。它們會解讀 Kilobat 的量測結果、說明哪些地方不確定，並在更改設定前先詢問。請一起安裝；kilobat 技能會把代理程式導向最合適的那一個。

npx skills add seifip/kilobat-skills

請用上面的 Homebrew 指令另外安裝 Kilobat CLI，或連接它的 MCP 伺服器。CLI 需要 macOS 14 或以上版本；用 Homebrew 從原始碼建置需要 Xcode 16 或以上版本。請參閱 skills.sh 上的技能，或閱讀它們的原始碼和參考資料。

Siri 與捷徑

向 Siri 詢問連線情況，Kilobat 會根據自身檢查用一兩句話回答，並附上數字卡片。依 Siri 的要求在問題中說出 App 名稱：「使用 Kilobat 查看網速為什麼慢？」會執行新的檢查並指出原因：「Wi-Fi 正常；供應商線路自晚上 9:05 起遺失了 4% 的封包。詳情在供應商報告中。」其他問題包括：「使用 Kilobat 查看連線是否正常？」「使用 Kilobat 查看通話為什麼卡住？」（上次通話報告）、「使用 Kilobat 查看 Slack 是否故障？」（Kilobat 可讀取狀態頁面的任何服務，或詢問「使用 Kilobat 查看 App 是否故障？」以檢查正在使用的 App）、「使用 Kilobat 查看什麼在使用網路？」「使用 Kilobat 查看用了多少流量？」「使用 Kilobat 查看是否可以開始通話？」「使用 Kilobat 查看 VPN 是否洩漏？」以及「使用 Kilobat 測試速度」。相同問題也可在 Spotlight 中使用，每項都是捷徑 App 中的動作，可將答案傳給下一步：網路狀態及其健康狀況、原因、延遲和封包遺失；通話報告；服務及其是否回報故障；今天使用的資料量。捷徑的「使用模型」動作可將這些結果交給 Apple Intelligence。沒有 Kilobat Pro 時，Siri 會說明問題和線路測量值、通話卡住的次數以及服務是否故障；Pro 會補充原因和應對方法。現成捷徑基於相同動作建立。