---
title: "Mac 網路 CLI、MCP 與代理程式技能 | Kilobat 說明文件"
url: "https://kilobat.app/zh-hant/docs.html"
description: "安裝 macOS 版 Kilobat。探索網路診斷 CLI、MCP 伺服器，以及處理 Wi-Fi、DNS、延遲和頻寬的 AI 代理程式技能。"
---

# Kilobat 說明文件

從選單列、終端機或 AI 代理程式使用 Kilobat 所需的一切。

## 安裝

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

```
brew install seifip/kilobat/kilobat
```

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

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

[下載 Mac 版 ↓](https://kilobat.app/downloads/Kilobat-1.5.0.dmg) [下載免費 CLI ↓](https://kilobat.app/downloads/kilobat-cli-1.5.0-universal.tar.gz)

### 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` 取得任何指令的說明。

## 指令

### 監控

|  |  |
|---|---|
| `kilobat status [--watch] [--json]` | 即時的各 App 流量和工作階段預算；輸出 JSON 快照，或搭配 --watch 輸出 JSON Lines 串流 |
| `kilobat report [--csv\|--json] [--summary] [--days 1…365]` | 本機記錄的用量歷史，或每日總量與用量最多的 App；CSV 每個 App 一列 |
| `kilobat report compare --total 40GB [--unit GB\|GiB] [--direction both\|download\|upload] (--from DATE --to DATE \| --period last-month) [--network NAME] [--json\|--csv]` | 把路由器或電信業者的數字放在 Kilobat 在這台 Mac 上同期記錄的數字旁邊，使用相同單位，並附上記錄時數、每段空缺和造成差異的可能原因 |
| `kilobat health-history [--hours 1…720] [--json]` | App 隨時間記錄的路由器、網際網路、抖動和 DNS 檢查 |
| `kilobat proxy [routes [--app name] \| test] [--json]` | 代理 App、系統代理伺服器及其問題；每個 App 走了哪條規則和哪個節點；每個節點的回應速度 |
| `kilobat vpn [--json]` | VPN，以及 DNS 或 IPv6 是否繞過它 |
| `kilobat calls [--limit 1…200] [--json]` | 每次通話後：卡頓了幾次以及原因，來自 App 產生的報告 |
| `kilobat overlay [--port 7171] [--target internet\|router\|host]` | 給 OBS 和其他直播 App 用的即時 ping 疊加層，在 localhost 上提供，直到按下 Ctrl-C |
| `kilobat support-report [--hours 1…168] [--host h] [--markdown\|--html] [--output f]` | 給業者或 IT 支援部門的報告：發現的問題、延遲、斷線和速度測試，不含你的網路名稱或本機位址 |
| `kilobat networks [forget <name>]` | 見過的網路，以及每個網路記住的設定檔、預算和流量費用 |
| `kilobat networks cost <metered\|unmetered\|automatic> [name]` | 把目前的網路或指定的網路視為計量或不計量，或改回依照 macOS 判斷 |
| `kilobat bandwidth [app] [hour\|day\|week\|month] [--back N] [--json]` | 單一 App 在一小時、一天、一週或一個月內傳送和接收的位元組數，以及尖峰值；--back 可往前回溯期間 |
| `kilobat access-policy <bundle-id> [--json]` | App 開發者在 Internet Access Policy 中宣告的連線，以及原因 |

### 診斷

|  |  |
|---|---|
| `kilobat diagnose [--json]` | Wi-Fi、路由器、網際網路、DNS 和強制網頁登入的檢查與建議 |
| `kilobat radar [--watch] [--json]` | 訊號分數與最佳位置搜尋 |
| `kilobat scan [--json]` | 附近的網路、頻道和頻寬 |
| `kilobat channels [--json]` | 各頻道的擁擠程度，以及最不擁擠的頻道 |
| `kilobat speedtest [--json] [--budget-mb 1…80] [--parallel]` | Cloudflare 速度、負載延遲，以及通話和串流的判定，最多 80 MB。預設一條連線；--parallel 會開四條，和大多數測速網站一樣 |
| `kilobat speed-compare [<test> <test>] [--json]` | 兩次已儲存的速度測試差在哪裡：網路、時間、伺服器、連線數、Wi-Fi 頻段和訊號、VPN、其他流量 |
| `kilobat ip [--public] [--json]` | 流量從哪裡出去：在這台 Mac 上讀取的介面和 VPN；--public 還會向 Cloudflare 查詢你的公用 IP 及其註冊國家 |
| `kilobat stutter [--seconds 10…60] [--target router\|internet\|<host>] [--json]` | 每 50 ms ping 一次，找出速度測試漏掉的短暫延遲突波、發生的時間點，以及是否重複出現 |
| `kilobat airdrop [status\|everyone\|contacts\|off] [--json]` | AirDrop 可見度、AirDrop 連結（AWDL）及使用它的項目；更改可見度會打開系統設定 |
| `kilobat bluetooth [--json]` | 藍牙裝置，以及它們是否與你的 Wi-Fi 共用 2.4 GHz |
| `kilobat dns [automatic\|cloudflare\|google\|quad9\|flush]` | 讀取或設定 DNS，或清除快取 |

### Wi-Fi

|  |  |
|---|---|
| `kilobat wifi [status]` | 目前的網路、訊號、頻道和連結速率 |
| `kilobat wifi on\|off\|restart\|disconnect` | 控制 Wi-Fi 電源和連線 |
| `kilobat wifi join <name> [--password-stdin]` | 加入已儲存的網路或新網路 |
| `kilobat wifi known` | 依偏好順序排列的已儲存網路 |
| `kilobat wifi password\|share <name>` | 顯示已儲存的密碼，或顯示可用手機掃描的 QR Code |
| `kilobat low-latency on [--for 15m\|1h\|2h] [--until-quit <app>]` | 在通話和遊戲時暫停 AirDrop 和 AWDL：預設 15 分鐘，最長 4 小時，或直到某個 App 結束 |
| `kilobat low-latency off` | 恢復 AirDrop 和 AWDL，在 App 中開始的暫停也適用 |

### 喚醒與代理程式

|  |  |
|---|---|
| `kilobat awake [--display]` | 讓 Mac 保持喚醒直到按下 Ctrl-C；除非加上 --lid-closed，否則闔上螢幕仍會讓它睡眠 |
| `kilobat awake --lid-closed [--for 2h\|--until-quiet\|-- <command>]` | 闔上螢幕也繼續執行，最長 8 小時，透過 App 的電源輔助程式；需要在「設定」中打開「允許闔上螢幕時執行」 |
| `kilobat awake --for 90m\|2h\|45s` | 保持喚醒一段時間 |
| `kilobat awake --until-quiet [--app <id>] [--quiet 1…60]` | 保持喚醒直到下載或某個 App 安靜下來，預設為低於 16 KB/s 持續 3 分鐘 |
| `kilobat awake -- <command> [args]` | 在指令執行期間保持喚醒，結束後回報其程序傳輸的資料量，並以該指令的狀態碼結束 |
| `kilobat awake --while-frontmost <app> [--display] [--for 2h]` | 只在該 App 位於最前面時保持喚醒，適合閱讀或簡報。切換到別的 App 時 Mac 就能睡眠；App 結束、電量剩 20% 或超過 --for 時結束。--display 會讓螢幕也保持開啟 |
| `kilobat settings awake-on-power on\|off` | 接上電源轉接器時 App 一律保持喚醒，拔掉後讓 Mac 恢復睡眠 |
| `kilobat settings keep-screen-on on\|off` | 凡是 App 保持喚醒的情況，螢幕也一併保持開啟：計時、下載、代理程式、最前面的 App 和插電時 |
| `kilobat sessions [--days N] [--json]` | App 記錄的喚醒工作階段和 AI 代理程式執行，附用量和網路變化 |
| `kilobat agent-event <start\|working\|waiting\|done\|failed> [--agent name] [--stdin-json\|--json-arg]` | 給代理程式的 hook 使用：告訴 App 某次執行已開始、正在等待你，或已完成。不會輸出任何內容，一律以 0 結束 |
| `kilobat why <url\|host> [--app <id>] [--proxy <url>] [--context container\|vm\|remote\|provider] [--failed-at <time>] [--json]` | 找出擋住連線的那一層：網路和介面、代理伺服器和 App 自己的代理伺服器、DNS、Kilobat 規則、IPv4 和 IPv6、TLS、伺服器和每一次重新導向。會請求確切的 URL；輸出會隱藏查詢參數值 |
| `kilobat conditions [--json]` | 計量、低數據模式、VPN、延遲、電池和溫度，以及能否闔上螢幕，並附上長時間執行的建議 |

### 控制

|  |  |
|---|---|
| `kilobat profile [travel\|work\|unrestricted]` | 列出或選擇設定檔 |
| `kilobat allow\|block <bundle-id> [--minutes 1…1440] [--profile name]` | 儲存 App 規則，可設為暫時規則或用於其他設定檔 |
| `kilobat reset <bundle-id> [--profile name]` | 移除 App 的規則，讓它改用預設處理 |
| `kilobat rules [--profile name] [--json]` | 設定檔的規則 |
| `kilobat limit [GB] [--cycle session\|daily\|weekly\|monthly] [--reset-day N] [--alert 50,80,100]` | 讀取或設定這個網路的流量預算、重新計算的時間和通知時機 |
| `kilobat quota <bundle-id> <GB> [--upload] [--all-networks]` | 限制單一 App 每個預算週期的流量；quota <bundle-id> --remove 可以取消 |
| `kilobat quota --list [--json]` | 各 App 的配額，以及本週期已使用的量 |
| `kilobat updaters [--json]` | 在計量網路上暫停的更新程式、在這個網路上仍溜過去的更新位元組數，以及從 App 內部自行更新的 App |
| `kilobat updaters on\|off` | 在網路計量時暫停 Google Updater 和 macOS 軟體更新等更新輔助程式（預設開啟）；App 本身照常運作 |
| `kilobat settings [name [value] ]` | 讀取或更改設定，例如 new-apps（allow、ask 或 block）、apple-software、auto-travel、pause-updaters、awake-on-power、public-ip（預設關閉）、speed-streams、alerts 和 menu-bar |
| `kilobat approvals [--json]` | 在詢問新 App 模式下等待核准的 App，附簽署者和目的地 |
| `kilobat approve\|deny <app-id> [--minutes 1…1440]` | 立即阻擋等待中的 App，或請使用者在 Kilobat 中確認允許它 |
| `kilobat block-host\|unblock-host <domain\|IP\|CIDR> [--app <id>]` | 對所有 App 或單一 App 阻擋網域（包含子網域，也接受 *.example.com）、IP 或網段 |
| `kilobat quit <PID> [--force]` | 結束程序 |

### 安裝與設定

|  |  |
|---|---|
| `kilobat open` | 打開 Mac App |
| `kilobat doctor` | 檢查 App、網路過濾器和監控 |
| `kilobat completion [zsh\|bash\|fish]` | 輸出 shell 自動補齊腳本 |
| `kilobat mcp` | 以 stdio 為 AI 代理程式執行 MCP 伺服器 |
| `kilobat update` | 更新以 Homebrew 安裝的版本 |

### 進階

|  |  |
|---|---|
| `kilobat destinations [--pid PID] [--json]` | 觀察到的程序通訊端 |
| `kilobat devices [--bonjour] [--json]` | 網路上的裝置和 Bonjour 服務 |
| `kilobat devices name <MAC> <name>` | 為裝置命名 |
| `kilobat trace <host> [--rounds 2…10] [--json]` | 有上限的 12 跳路由探測；--rounds 會追蹤多次，顯示每一跳的封包遺失和延遲 |
| `kilobat route-history --host <host> [--json]` | 對某台主機的每次已儲存追蹤，像 mtr 一樣逐跳列出：封包遺失、最佳、平均、最差、路由變化，以及延遲從哪裡開始 |
| `kilobat http-check <URL> [--json]` | DNS、連線、TLS 和第一個位元組的時間 |
| `kilobat dns-benchmark` | 解析器的回應時間 |
| `kilobat lan-test <server> [--reverse] [--json]` | 對執行 iperf3 -s 的裝置做五秒的 iperf3 測試；需要 iperf3，Kilobat 不會替你安裝 |
| `kilobat interfaces [--json]` | 實體介面和 VPN 的計數器，分開顯示 |
| `kilobat capture <interface> <file.pcap>` | 有上限的封包擷取 |
| `kilobat connection-rule allow\|block <app> <host> [port]` | 儲存目的地規則 |
| `kilobat blocklist status\|import <path>\|clear` | 管理網域阻擋列表 |
| `kilobat wake <MAC-address>` | 傳送 Wake-on-LAN 封包 |
| `kilobat spots [save <name>\|remove <id>]` | 已儲存的 Wi-Fi 地點 |
| `kilobat outages / speed-history [--days N]` | 以 JSON 輸出記錄到的斷線事件和速度測試 |

## 腳本與 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](https://kilobat.app/agents/claude-code.html)、[Codex](https://kilobat.app/agents/codex.html)、[Cursor](https://kilobat.app/agents/cursor.html)、[Gemini CLI](https://kilobat.app/agents/gemini-cli.html)、[Claude Desktop](https://kilobat.app/agents/claude-desktop.html)、[Windsurf](https://kilobat.app/agents/windsurf.html)、[Cline](https://kilobat.app/agents/cline.html)、[Zed](https://kilobat.app/agents/zed.html) 和[任何 MCP 用戶端](https://kilobat.app/agents/mcp-client.html)的逐步設定方式，請見[在 AI 代理程式中設定 Kilobat](https://kilobat.app/agents/index.html)。

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

```
Install the Kilobat CLI with `brew install seifip/kilobat/kilobat`. Run `kilobat diagnose --json`, `kilobat status --json` and `kilobat scan --json`, then tell me what is slowing my connection and how to fix it. Ask me before changing DNS, profiles or rules.
```

### 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
```

|  |  |
|---|---|
| [kilobat](https://github.com/seifip/kilobat-skills/tree/main/skills/kilobat) | 從這裡開始。安裝設定、安全規則，以及哪個技能適合這個問題。 |
| [mac-network-troubleshooting](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-network-troubleshooting) | 網路很慢或不穩定，原因不明：找出出問題的那一層。 |
| [mac-wifi-troubleshooting](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-wifi-troubleshooting) | Wi-Fi 訊號弱或常斷線、頻道擁擠、Mac 或路由器的最佳擺放位置。 |
| [mac-hotspot-data-saver](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-hotspot-data-saver) | 手機熱點和流量上限：哪些東西在用流量、「旅行」設定檔、預算。 |
| [mac-dns-troubleshooting](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-dns-troubleshooting) | 查詢緩慢、解析器效能測試、切換 DNS、強制網頁登入。 |
| [video-call-network-check](https://github.com/seifip/kilobat-skills/tree/main/skills/video-call-network-check) | 卡頓的通話和遊戲串流：延遲突波、抖動、封包遺失、緩衝膨脹和背景上傳。 |
| [mac-bandwidth-monitor](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-bandwidth-monitor) | 哪些 App 在使用連線、用量歷史，以及它們連到哪裡。 |
| [mac-app-firewall](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-app-firewall) | 阻擋或允許 App、網域和 IP；詢問新 App 並回應。 |
| [mac-agent-runs](https://github.com/seifip/kilobat-skills/tree/main/skills/mac-agent-runs) | 長時間的代理程式執行：讓 Mac 保持喚醒、檢查環境條件、連接代理程式 hook，查看執行何時完成、在等你，或卡住了。 |

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

## 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 的捷徑動作](https://kilobat.app/shortcuts.html)則可以在「捷徑」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 上。沒有帳號，也沒有遙測。診斷會連到測試服務，授權啟用和更新檢查會連到各自的服務。請閱讀[隱私權聲明](https://kilobat.app/privacy.html)。