Kilobat 說明文件

安裝

CLI 免費且開放原始碼。用 Homebrew 安裝：

這會安裝 kilobat 和簡短的別名 kb。下面每個範例兩個都能用。

或者下載 Mac App，它也在 Kilobat.app/Contents/Helpers/kilobat 附有 CLI。

Mac App Store 上的 Kilobat Lite

Kilobat Lite 是即將在 Mac App Store 推出的免費版本。它在 Apple 的 App 沙盒中執行，保留在沙盒裡能正常運作的功能：健康檢查、速度測試、Wi-Fi 雷達和附近的網路、「為什麼連不上？」以及保持喚醒。各 App 的流量、規則和網路過濾器、DNS 變更、闔上螢幕輔助程式和 CLI 需要沙盒不允許的權限，所以只有本網站提供的 Kilobat App 才有。兩者可以同時安裝。

為你的 shell 開啟 Tab 自動補齊：

# zsh
echo 'source <(kilobat completion zsh)' >> ~/.zshrc
# fish
kilobat completion fish > ~/.config/fish/completions/kilobat.fish

快速入門

單獨執行 kilobat 會打開互動式選單：用方向鍵或 j/k 移動，Enter 打開，按數字直接跳到該項，q 結束。

kilobat status --watch     # live traffic by app; q quit, s sort, f filter, / search
kilobat diagnose           # what is slowing your connection
kilobat speedtest          # speed and latency under load
kilobat profile travel     # switch to the Travel profile
kilobat block com.example.App

執行 kilobat <command> --help 取得任何指令的說明。

指令

監控

診斷

Wi-Fi

喚醒與代理程式

控制

安裝與設定

進階

腳本與 JSON

透過管線傳遞時，輸出會自動改成 JSON，腳本不必去解析給人看的版面。想明確指定時，加上 --json。

kilobat diagnose | jq .health            # "good", "degraded", "poor" or "unknown"
kilobat status --watch --json             # one JSON object per line, every second
kilobat report --summary --days 7 --json  # daily totals and top apps
kilobat report compare --total 40GB --period last-month --csv  # beside your provider's figure

設定 NO_COLOR 可以關閉顏色。更改 DNS 需要管理者核准。

AI 代理程式與 MCP

Claude Code、Codex、Cursor、Gemini CLI、Claude Desktop、Windsurf、Cline、Zed 和任何 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_wifi、scan_wifi、suggest_wifi_channel、get_usage_report、compare_usage、get_app_bandwidth、get_access_policy、get_network_history、list_sessions、benchmark_dns、check_url、list_connections、list_devices、trace_route、get_route_history、compare_speed_tests、get_exit_path（只有在代理程式傳入 public_ip 時，才會向 Cloudflare 查詢你的公用 IP）、list_networks、list_rules、list_approvals、list_blocked_connections、run_stutter_test（只會傳送 ping）、get_nearby_radios 和 create_support_report（給業者的報告，由代理程式轉交給你）。它們回傳的 JSON 和 CLI 相同。run_speedtest 會使用流量，run_lan_test 會在你自己的網路上傳輸五秒資料並先詢問，keep_awake 和 release_awake 會在設定的時間內暫緩閒置睡眠，不更改任何設定；keep_awake 搭配 lid_closed 則在你允許後，連闔上螢幕時也讓 Mac 繼續執行，並會先詢問你。變更類工具（set_profile、set_app_rule、set_new_app_mode、decide_approval、block_destination、set_budget、set_app_quota、set_network_cost、set_updater_pause、set_dns（同時會清除快取），以及 set_airdrop_visibility（會打開 AirDrop 設定））都標記為變更，其描述也會要求代理程式先詢問你。

連不上的時候

kilobat why <host>（MCP：diagnose_connection）會從這台 Mac 逐層檢查一台主機，不經過 curl 或 nc，所以嚴格的設定檔不會擋住檢查本身。它會分別嘗試 IPv4 和 IPv6，所以當網路的 IPv6 壞掉（這是代理程式卡住或不停重新連線的常見原因）時，也能得到明確的答案。它會指出使用的介面，例如 Wi-Fi、手機熱點或 VPN，有多個介面時會逐一嘗試。它會回報系統或其 PAC 檔選用的代理伺服器；搭配 --app 時，還會回報該 App 環境中的 HTTPS_PROXY，但不含密碼。開著 VPN 或代理伺服器時，它會比較直連路徑和通道。私有名稱送到 VPN 自己的解析器時，會說明是哪一個，以及它有沒有回應。在容器、虛擬機器或遠端機器中執行的程式碼有自己的網路：傳入 --context，報告最後會附上一個要在那裡執行的指令。當代管服務從自己的伺服器發出請求時（例如 Warp 對自訂推論端點的做法），--context provider 會說明目標是否為私有位址（localhost、LAN 或 Tailscale 位址），因此對方連不到，即使從 Mac 連得上。

請給它失敗的確切 URL，包含查詢參數：它會請求那個 URL，但所有輸出都會把查詢參數值顯示為 [redacted]，所以簽署過的下載連結不會外洩。它會用 App 的方式送出請求：透過 App 的 HTTPS_PROXY、系統代理伺服器，或用 --proxy <url> 指定 App 在自己設定中填寫的代理伺服器位址。當代理伺服器能用而直連不行時（很多公司網路都是如此），它會說明這一點，而不是回報失敗；當直連可行，但透過 App 的代理伺服器發出的請求失敗時，它會說網路沒問題，是 App 的路徑有問題。對於它無法讀取或無法經過的設定，例如 LM Studio 下載 huggingface.co 時用的 Hugging Face 代理開關，會另外附上一則註記，引用使用者回報的情況，判定結果則改為說明網路連得到主機，而不是 App 的請求能成功。Kilobat 絕不更改其他 App 的設定。拒絕 HEAD 的伺服器會收到一次只取一個位元組的 GET，絕不會真的下載。它最多跟隨五次重新導向，指出失敗的是哪一跳，並對重新導向最終抵達的主機檢查 IPv4 和 IPv6。搭配 --app 時，它會列出 App 連到該主機或其代理伺服器的開啟中連線，說明它們是否用了和這次檢查不同的 IP 版本或伺服器，並在幾秒後再看一次：沒了動靜的傳輸會回報為「沒有動靜」，絕不會說成「已完成」。報告會記錄 App 的名稱和版本、送出的方法、走的路徑；搭配 --failed-at 時，還會把 App 失敗的時間和檢查執行的時間並列。檢查通過，代表這個請求此刻能從這台 Mac 經由那條路徑成功；它看不到已經在進行的傳輸狀況如何，那部分請用 kilobat bandwidth <app> 觀察。

連接代理程式

沒有額外資訊時，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，就能看到發生了什麼。

為什麼各家速度測試結果不一樣

Kilobat 的速度測試一次只對 Cloudflare 最近的資料中心建立一條 HTTPS 連線，每個方向 8 秒、最多 80 MB，並在傳輸前和傳輸期間 ping 1.1.1.1。Ookla 的 Speedtest、fast.com 和 macOS 的 networkQuality 會同時開多條連線，並自行挑選伺服器，所以在高速或遠距離的線路上，數字通常比較高。在「速度」分頁的測試按鈕旁選擇 4 條連線，或執行 kilobat speedtest --parallel，就能看出這在你的連線上差多少。每次儲存的測試都會保留 Cloudflare 資料中心、連線數、連結資訊（Wi-Fi 頻段、頻道、訊號和連結速率，或乙太網路）、經過的 VPN，以及這台 Mac 同時傳輸了多少其他流量。「歷史記錄」›「速度測試比較」、kilobat speed-compare 和 MCP 的 compare_speed_tests 會把兩次測試並排，列出差異，並說明每項差異如何影響結果。它們列出的是差異，不是原因：網路上的其他裝置也在搶頻寬，而 Kilobat 看不到它們。

VPN 與公用 IP

「健康狀態」›「流量從哪裡出去」、Wi-Fi 選單和 kilobat ip 會顯示預設路由使用的介面，以及那是不是 VPN，資訊來自這台 Mac 的路由表和 macOS 列為已連線的 VPN。VPN 已連線但預設路由仍在 Wi-Fi 上時（例如沒有設定出口節點的 Tailscale），會顯示為「分流」：只有部分目的地會經過它。打開「設定」›「網路」›「查詢公用 IP」，就能看到網站看到的位址：在網路變化時及每 30 分鐘向 Cloudflare 查詢一次，並以 Kilobat 內建的 DB-IP 資料顯示它註冊的國家。這個功能預設關閉，因為 Cloudflare 會看到這個請求；kilobat ip --public 則只查詢一次。註冊國家不等於你或伺服器所在的地方，而且無論是它還是 VPN，都無法證明連線是私密或匿名的。「設定」›「選單列」›「VPN」會在蝙蝠旁顯示「開啟」、「分流」或「關閉」（開啟查詢時附國碼），「歷史記錄」也會列出 VPN 何時開啟或關閉，以及公用 IP 何時改變。

路由歷史記錄

「工具」›「DNS 與 LAN」›「追蹤 3 次」或 kilobat trace <host> --rounds 3 會追蹤一條路由三次，每一跳送三個探測封包，並儲存每次追蹤。「歷史記錄」›「已儲存的路由」會把對某台主機的所有已儲存追蹤逐跳彙整，像 mtr 一樣：封包遺失、最佳、平均、最差和最後一次延遲、哪幾跳換了路由器，以及持續延遲從哪裡開始。某一跳不回應、但後面幾跳都有回應，代表那台路由器在限制探測封包的速率，而不是封包遺失。只測本機網路的話，kilobat lan-test <device> 會對執行 iperf3 -s 的裝置跑五秒 iperf3；iperf3 請自行安裝，Kilobat 從不安裝任何東西。

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 上的技能，或閱讀它們的原始碼和參考資料。

Mac App

1. 下載磁碟映像檔，把 Kilobat 拖進「應用程式」，然後從那裡打開。
2. 即時流量、Wi-Fi 選擇器、速度測試、保持喚醒和「為什麼連不上？」都免費，整個 CLI 也是。Pro 在 App 中加入規則與「詢問」、預算、Wi-Fi 健康狀態、連線地圖、雷達和歷史記錄。要解鎖 Pro，請開始 7 天免費試用，或把授權碼貼到「設定」中。
3. 在「設定」中選擇要顯示的選單列項目。按住 Command 鍵並拖移選單列項目，可以移動它的位置。

被詢問時請允許取用定位，Kilobat 才能顯示 Wi-Fi 名稱並掃描附近的網路。你的位置不會傳送到任何地方。

各 App 的頻寬

每個 App 的列都會顯示最近一分鐘的流量，上傳在線上方，下載在線下方。按一下就能看到這個 App 的回聲：一句話說明它傳輸了什麼，接著是最近五分鐘的即時波形；有 Pro 的話，還能按小時、日、週或月查看歷史。標記會顯示 Mac 加入其他網路或代理程式執行用到這個 App 的時間點，圖塊則顯示承載流量的網路、與這個 App 前四個期間相比如何，以及它佔全部流量的比例。圖表下方是 App 開啟中的連線，附每條連線的傳輸量和國家；如果 App 附有 Internet Access Policy，也會列出開發者宣告的連線。

和路由器或電信業者對帳

當路由器、ISP 或電信業者顯示的總量和 Kilobat 不同時，打開「歷史記錄」›「與路由器或電信業者比較」，或執行 kilobat report compare。依對方顯示的方式輸入數字、單位，以及它計算的是下載、上傳還是兩者，再輸入相同的期間和涵蓋的網路。Kilobat 會以相同單位顯示自己的總量和差異，也會用另一種單位制解讀那個數字，因為很多業者寫的 GB 其實是 1,073,741,824 位元組（GiB），而不是 1,000,000,000。

一條時間軸會顯示 Kilobat 實際記錄到的時數和空缺：Mac 睡眠的時間（自 Kilobat 1.3 起記錄）、關機、離線或 Kilobat 沒在執行的時間、連在其他網路的時間，以及歷史記錄開始之前的時間。下方列出造成差異的可能原因，最可能的排在最前面。Kilobat 只看得到這台 Mac，看不到路由器或業者算進去的手機、電視和其他電腦。它不計入本機網路和 AirDrop 流量，因為這些流量從不經過網際網路；沒有任何 App 認領的封包標頭則計為未歸屬。業者可能用另一個時區計算日期，或延遲入帳用量。Kilobat 不會判定哪個數字才對。可以把比較結果匯出為 CSV 或 JSON，包含期間、網路、記錄時數和每段空缺，提供給你的業者。

卡頓測試

通話、遊戲串流和遠端桌面可能會卡頓，速度和封包遺失卻看起來正常，因為幾百毫秒的 ping 突波會被平均值吃掉。「健康狀態」中的卡頓測試會每 50 ms ping 一次你的路由器（或網際網路），持續 20 秒，並畫出每一次回應，突波以玫瑰色標示，附上中位數、p95、p99 和最差的 ping。它會告訴你突波是否以固定間隔重複出現（通常指向 AirDrop/AWDL 掃描），還是隨機出現（指向網路繁忙、干擾或訊號弱）。很多路由器每秒只回應大約十個 ping；Kilobat 認得這種模式，不會把它算成封包遺失。有 Pro 的話，開啟低延遲後比較會在暫停 AirDrop/AWDL 的情況下重跑測試，並告訴你有沒有幫助。

低延遲暫停會關閉 AirDrop、Sidecar 和通用控制 15 分鐘、1 或 2 小時，或直到你的遊戲或通話 App 結束，最長 4 小時。時間到、App 結束、Kilobat 結束或網路改變時，它一定會還原；若 Mac 當機，則會在下次啟動時還原。macOS 會要求管理者核准。「健康狀態」的「附近」面板也會顯示 AirDrop 的無線電是否在運作、誰在使用它、你的 AirDrop 可見度，以及（在你要求時）與 Wi-Fi 共用 2.4 GHz 頻段的藍牙裝置。

Wi-Fi 選單會在網路下方列出你的藍牙裝置：按一下即可連接或中斷連接。2.4 GHz 標籤會標出與 Wi-Fi 共用頻段的已連接耳機、鍵盤和滑鼠，並附上切換到已知 5 GHz 網路的捷徑。再下面是 AirDrop，包括它的可見度、正在使用這個連結的項目，以及低延遲暫停。只有在你選擇「顯示藍牙裝置」後才會出現藍牙，所以 macOS 也只會在那時要求取用權限。

代理伺服器和 VPN

Kilobat 可以和代理 App（Clash Verge、ClashX、mihomo、Mihomo Party、FlClash、Surge、sing-box、Stash、V2Ray、Xray、Shadowsocks）及 VPN 一起使用。它只讀取資訊，絕不轉送流量，也不更改它們的設定。

• 流量算在正確的 App 上。透過本機代理伺服器傳送流量的 App 會計入它自己的流量，轉送流量的代理核心或 VPN 通道則標為「承載其他 App 的流量」，不會重複計算。
• 每個 App 走了哪條路線。使用相容 Clash 的 API（Clash Verge、ClashX、mihomo、Mihomo Party、FlClash、sing-box 的 clash_api）時，App 的那一列會顯示它經過的節點，例如「透過 HK-01 · 2 個直接連線」，提示中會列出每個主機、節點和規則。Kilobat 會從該 App 自己的設定讀取 API 位址和密鑰，而且絕不顯示密鑰。
• 「健康狀態」›「流量從哪裡出去」中的問題：
  • 系統代理伺服器指向沒有在執行的 App，這會讓所有瀏覽器都無法上網；
  • DNS 或 IPv6 繞過了 VPN；
  • 代理伺服器和 VPN 同時在接管流量；
  • 全域模式；
  • 阻擋功能看不到系統代理伺服器後方的 App。macOS 過濾器永遠看不到連到 127.0.0.1 的連線，所以請打開代理伺服器的 TUN 模式，或在代理伺服器的規則中阻擋該 App。
• 為什麼連不上？會加入「代理 App」這一層，顯示代理伺服器的模式及其目前節點的回應速度，並在問題出在失效節點時告訴你。

在終端機中：kilobat proxy、kilobat proxy routes --app Telegram、kilobat proxy test 和 kilobat vpn。如果 Kilobat 自己找不到某個代理核心，請傳入 --controller 127.0.0.1:9090 --secret …。AI 代理程式可以透過 get_proxy_status、test_proxy_nodes 和 check_vpn 取得相同資訊。

小工具

把 Kilobat 加入桌面或通知中心：在桌面上按右鍵，選擇「編輯小工具」，然後搜尋 Kilobat。網路狀態用蝙蝠表示連線的健康狀態，並顯示網際網路和路由器的 ping；中型尺寸還會加上最近 30 分鐘的延遲、你最近一次的速度測試和一個「測試」按鈕。今日流量按小時顯示今天的網際網路流量（下載和上傳）；使用 Pro 時還會顯示你的預算。速度測試顯示你最近一次的結果，按一下就能執行新的測試（在計量網路上為 10 MB）。小工具不會顯示任何網路名稱或位址，有變化時就會更新，Kilobat 沒有執行時會註明數據是多久以前的。

通話報告

每次通話後，Kilobat 都會告訴你通話是否卡頓以及原因。當 Zoom、Microsoft Teams、FaceTime、Slack、Webex、Discord、Skype、WhatsApp、Telegram、Signal 或瀏覽器使用麥克風超過十秒時，它就會察覺到通話。它絕不會聽到通話內容：它只看得到哪個 App 在使用麥克風，而這點 macOS 本來就會顯示。在通話結束前，它每秒會 ping 一次網際網路和你的路由器，記下最忙的其他 App，並每五秒檢查一次 Mac 的 CPU、記憶體、溫度和 GPU。

連續兩秒以上 ping 遺失，或 ping 比該通話平常慢 200 ms，就算是一次卡頓。每次卡頓都會標出原因：當時有其他 App 在上傳或下載、Wi-Fi（路由器也同時停頓時）、AirDrop 掃描，或發生在路由器之外。此外，卡片也會說明 Mac 本身何時吃力：CPU 滿載（以及是哪個 App 造成的）、記憶體不足、Mac 因過熱而自行降速，或 GPU 滿載。卡片會顯示在「健康狀態」›「通話」中，也會以通知出現。沒有 Pro 時，它會顯示通話卡頓了幾次；Kilobat Pro 會指出原因，並告訴你可以試試什麼。可以在「設定」›「網路」›「每次通話後報告」中關閉。在終端機中，kilobat calls 會列出這些卡片，AI 代理程式可以透過 get_call_reports 取得它們。

直播疊加層

在直播中顯示即時 ping。打開「設定」›「網路」›「直播疊加層」，然後在 OBS、Streamlabs 或任何直播 App 中把 http://localhost:7171/ 加入為瀏覽器來源（640 × 80 就很夠了）。一個小膠囊會顯示 ping、抖動、封包遺失和最近一分鐘的曲線。開頭的小蝙蝠在曲線良好時是微笑的藍色，變慢時轉為紫色，很差時則是皺眉的玫瑰色。可以在 URL 中更改：?show=ping,jitter,loss,graph,speed、theme=dark、light 或 clear，以及 size=s、m 或 l。使用 Pro 時，brand=0 會隱藏文字標誌，face=0 會用一個簡單的圓點取代小蝙蝠。開啟期間，Kilobat 每秒會 ping 1.1.1.1 一次；頁面在 127.0.0.1 上提供，所以只有這台 Mac 能打開。沒有 App 時，kilobat overlay 會提供同一個頁面，直到按下 Ctrl-C。

給業者的報告

連線很差時，你的業者或 IT 支援部門會要證據。在「健康狀態」中，報告按鈕會根據 Kilobat 在這個網路上過去 24 小時或 7 天的記錄產生一份報告。內容包括斷線、路由器端及更遠處的延遲、ping 封包遺失、與你的方案相比的速度測試，如果你加入了出問題的網站，還會附上對它的檢查。每項發現都說明量了什麼、在哪裡量，絕不說是誰的錯。可以拷貝成文字貼到客服聊天，或儲存、分享為 PDF。報告不會包含你的網路名稱、任何本機 IP 和硬體位址、裝置名稱，以及哪些 App 用過這個網路。在終端機中執行 kilobat support-report --host github.com，或執行 --html --output report.html 取得網頁版。

分享卡片

在選單列圖像上按右鍵，選擇「分享與輸出」，就能產生一張可以發布的方形圖片：每週回聲（你傳輸的資料量、最忙的一天和最耗流量的 App）、最近一次的速度測試，或「這個地點」（為你正在工作的咖啡廳、共同工作空間、飯店或圖書館產生的 Wi-Fi 報告）。「這個地點」會顯示地點名稱（可以輸入，或從 Apple 地圖搜尋中選取），以及這個網路上最近一次速度測試的下載、上傳和 ping、是否足以進行視訊通話、在負載下的表現，以及 Wi-Fi 頻段。從搜尋中選取地點後，卡片會附上一張附近街區的小地圖，並用圓點標出位置；關閉「顯示地圖」即可拿掉。可以加入「有插座」、「安靜」或「營業到很晚」等標籤，以及一行備註。Kilobat 會在這台 Mac 上為該網路記住它們。可以拷貝卡片、儲存，或分享到 Nomad List、Google 地圖評論或共同工作空間的聊天群組。任何卡片都不會顯示網路名稱或地址。地圖顯示的是你選取的地點，而不是你所在的位置，除非你選擇「使用我的位置」，這也是「這個地點」唯一會要求定位權限的時候。

其他 App 可以用 kilobat:// 連結（1.3.4 起）在正確的位置打開 Kilobat：kilobat://open/speed 會打開一個標籤頁（overview、connections、health、radar、speed、history、tools 或 settings），kilobat://share/speed、kilobat://share/week 或 kilobat://share/place 會打開分享卡片，kilobat://speedtest 會執行速度測試。可以在「終端機」中用 open kilobat://open/history 執行，或在啟動器中綁定到某個按鍵。Raycast 延伸功能的 Open in Kilobat 動作就是使用這些連結，Kilobat 的捷徑動作則可以在「捷徑」App 中執行檢查、速度測試、保持喚醒和報告。

它連到哪裡

「連線」會在地球上顯示每條開啟中的連線，連向其位址註冊的國家，最忙碌的國家列在清單中，連線端點則在下方。按一下國家即可篩選。國家資料來自 App 內建的 DB-IP 免費資料庫，所以不會有任何位址離開你的 Mac。這是註冊國家：CDN 或 VPN 的位址顯示的是擁有者的國家，而不是伺服器所在的地方。

阻擋與過濾

監控不需要開啟過濾。要強制執行規則，請在 Kilobat 中打開過濾設定，並在 macOS 詢問時核准延伸功能和內容過濾器。在目前的 macOS 上，延伸功能位於「系統設定」→「一般」→「登入項目與延伸功能」→「網路延伸功能」。

過濾只影響新的連線；既有的連線可能會持續到重新連線為止。如果某條規則中斷了重要的事情，請切換到「不受限」，或在「設定」中關閉過濾。

新 App：允許、詢問或阻擋

App 列表上方的膠囊按鈕決定「旅行」和「工作」如何處理沒有規則的 App。允許讓它們連線。詢問會攔住 App 的第一批連線，並打開一個視窗，顯示簽署者、路徑和它想連去哪裡；允許或阻擋一次，Kilobat 就會儲存規則。沒有回應的連線會在一分鐘後放棄，App 會再問一次。阻擋只讓你允許過的 App 連線。打開允許 Apple 軟體，macOS 服務和 Apple 的 App 就能直接通過、不必詢問。你的阻擋列表和連線規則在每種模式下都有效；Kilobat 沒在執行時，新 App 會被允許，而不是被攔住。

熱點與流量費用

macOS 會把某些連線標為計量，例如 iPhone 熱點，但不是每個 Android 熱點都會，透過 USB 或乙太網路連接的手機網路也不會。每個網路都有流量費用設定：自動依照 macOS，計量或不計量則由你決定。可以在 Wi-Fi 選單、預算選單、「健康狀態」分頁或「設定」中設定，或用 kilobat networks cost metered。在計量網路上，Kilobat 會切換到「旅行」（除非你為該網路選了其他設定檔），離開時換回原本的設定檔，並略過排程的速度測試。kilobat conditions --json 和 MCP 伺服器會同時回報 metered 和 macOS 的判斷（osMetered）。Kilobat 必須能分辨網路，你才能設定它的費用，所以 Wi-Fi 需要定位權限才能看到網路名稱。

在計量網路上暫停更新程式

在計量網路上，網路過濾器也會暫停那些自行下載更新的輔助程式：Google Updater（以及較舊的 Keystone 代理程式）、Microsoft AutoUpdate、macOS 軟體更新（softwareupdated）、App Store 下載（appstored、appstoreagent、storedownloadd）、Sparkle 的下載服務，以及 Sparkle 和 Squirrel 的安裝程式（Autoupdate、Updater.app、ShipIt）。它們是被一般的過濾規則阻擋的，被阻擋連線的記錄會寫「已在計量網路上暫停更新程式」，App 本身照常運作。網路不再計量後，更新就會繼續。其他 App、它們的暫存資料夾或系統設定都不會被更改，所以沒有東西需要還原。這個功能預設開啟；可以在「設定」中或用 kilobat updaters off 關閉。已經適用於某條連線的規則（例如目的地規則或暫時允許）會優先，所以「允許 30 分鐘」可以讓一次更新通過。「不受限」不會暫停任何東西。

「健康狀態」分頁、kilobat updaters 和 MCP 工具 get_updaters 會顯示涵蓋了哪些更新程式、在這個網路上仍溜過去的更新位元組數（更新程式自己的位元組，以及替它連線的 nsurlsessiond 等系統下載，其位元組也包含其他下載），以及哪些已安裝的 App 是從自己的程序內更新。大多數以 Sparkle 或 Electron 打造的 App 會在 App 內下載更新，只把安裝交給輔助程式，所以不阻擋 App 本身就無法暫停。過濾器擋的是新連線，所以網路變成計量時已在進行的下載仍可完成。Kilobat 自己的排程更新檢查也會等到不計量的網路；手動「檢查更新項目」仍然可用。

流量預算與 App 配額

每個網路都有自己的預算。預設會一直累計，直到你手動重設。可以設定為每天、每週（自選星期幾），或每月在方案續約那天重新計算；在 31 日續約的方案，遇到較短的月份會在當月最後一天開始。設有週期的預算會計算該網路的用量歷史，所以重新啟動後仍會接續。Kilobat 預設在每個週期達到 80% 和 100% 時各通知一次，也可以加上 50%。

App 可以有自己的配額：每個週期對它全部的流量或只對上傳設限，可針對單一網路或所有網路。可以在 App 的頻寬面板中設定，或用 kilobat quota com.getdropbox.dropbox 2 --upload。開啟過濾時，預算用完會停止新連線，配額用完則停止該 App 的新連線。暫時允許或連線規則仍可通過。Kilobat 每秒取樣一次流量，所以預算和配額都是近似值：App 可能會稍微超過一點才停下。

計入什麼：網際網路、本機網路和 VPN

預算、配額和已用流量只計算網際網路流量。連到本機網路（印表機、NAS、其他電腦、路由器的管理頁面）、AirDrop 及其他附近裝置連結（AWDL）的流量會分開顯示，例如「本機網路：2.1 GB，不計入」，在游標停留在預算卡片的已用數字上時，以及在每個 App 的頻寬面板中都看得到。Mac 的總量來自 Wi-Fi 和乙太網路的計數器，所以包含沒有任何 App 認領的部分：封包標頭和確認封包（App 的位元組數不含這些，通常會多出 5–10%）、在兩次取樣之間開始又結束的程序、網際網路共享，或 macOS 自己執行的 VPN。同一個提示會把這部分顯示為「未對應到 App」；它絕不會被算到某個 App 頭上。

使用 VPN 時，App 的流量會經過通道，再由 VPN 透過 Wi-Fi 或乙太網路送出去。Kilobat 只在流量離開 Mac 的地方計算一次，和你的電信業者一樣，並把 App 的部分標為「經由 VPN」。使用代理伺服器時（系統代理伺服器、HTTPS_PROXY 或本機代理 App），App 是和這台 Mac 上的代理伺服器通訊，由代理伺服器建立網際網路連線，所以位元組會顯示在代理伺服器底下；Kilobat 無法分辨背後是哪個 App。TUN 模式的代理伺服器對 Kilobat 來說就是 VPN：每個 App 自己的連線會標為「經由 VPN」，代理伺服器的對外流量則顯示在代理伺服器底下。位於私有位址的公司代理伺服器算作本機網路。

系統下載

App 會把部分下載交給 macOS：nsurlsessiond（Music、Podcast 等 App 的背景傳輸）、mobileassetd（Apple Intelligence 和 Siri 模型、語音、字體）、softwareupdated、appstored 和 appstoreagent、cloudd 和 bird（iCloud）、fileproviderd 和內容快取。App 列表會把它們歸為「系統下載」，並說明各自的用途。開啟過濾時，過濾器看得到每條連線是替哪個 App 建立的，所以列表會寫「替 Music」，阻擋記錄則寫「com.apple.Music via nsurlsessiond」。沒有開啟過濾時，nettop 只看得到服務，所以 Kilobat 無法得知下載是替哪個 App。

既不是 App 也不屬於 macOS 的程序，例如 node、python、deno、bun，或你的個人專屬資料夾或 Homebrew 中的 Go 執行檔，展開它的列時會顯示執行檔路徑，讓陌生的代理程式或工具一眼就能認出來。

在「設定」中打開異常上傳，當某個 App 在一小時內上傳了平常的五倍、且至少 50 MB 時就會通知你，每個 App 每天最多一次。它只會通知。暫時規則和會到期的連線規則都列在「設定檔」底下，附剩餘時間，你可以提早結束。

阻擋網域和 IP

在 App 的開啟中連線上按右鍵，就能只對這個 App 或對所有 App 阻擋該主機。阻擋列表接受網域（包含子網域，*.example.com 也可以）、IP 位址和 CIDR 網段，也能搭配匯入的 hosts 列表。在終端機中：kilobat block-host ads.example.com。

送出 Pro，換來 Pro

每個 Pro 授權都有自己的推薦連結 kilobat.app/r/ 和一組短代碼。你可以在「設定」的「Kilobat Pro」區塊或分享卡片下方找到它，旁邊有「拷貝連結」和「分享」。不需要帳號：代碼來自你的授權，不會洩露你的授權碼。

朋友打開你的連結再打開 Kilobat，就能獲得 30 天 Pro 試用，而不是 7 天。每台 Mac 只能使用一個推薦連結，而且只能用一次。朋友透過你的連結後在 App 中或網站上購買 Pro，你的授權就多一台 Mac。每滿三位朋友，你就能獲得一份免費 Pro 授權：一組顯示在「設定」中的一次性代碼，結帳時輸入，可以自己用，也可以送給任何人。

購買會在 14 天退款期結束後計入；在此之前，「設定」會顯示為等待中。已退款的購買、免費授權，以及透過你自己的連結購買都不計入。

隱私權

流量歷史、網路名稱和規則都留在你的 Mac 上。沒有帳號，也沒有遙測。診斷會連到測試服務，授權啟用和更新檢查會連到各自的服務。請閱讀隱私權聲明。