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（智能体及其命令连接过的每个主机）、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（应用后台静默测试得出的各网络最快 DNS）、list_rules、list_approvals、list_blocked_connections、explain_verdict（与主机或应用匹配的每条规则及决定结果的规则）、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（查询指定服务或正在运行的应用的公开状态页面）以及 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（暂缓另一个应用的上传）、set_dns（还会清空缓存）、set_fastest_dns、set_dns_fallback 和 set_airdrop_visibility（打开隔空投送设置））标记为更改，其描述会要求智能体先询问你。

连接智能体

没有额外帮助时，Kilobat 根据智能体的流量和 CPU 判断，所以一个安静的智能体可能已经完成，也可能在等你。智能体的钩子会告诉 Kilobat 某次运行属于哪个项目、何时在等你、何时完成。每个钩子都运行 kilobat agent-event，它不输出任何内容、立即返回且始终以 0 退出，因此不会搞坏智能体。如果应用没在运行，事件会先存进一个小文件，应用打开时再读取。Kilobat 只读取会话 ID、文件夹和简短的状态文字，从不读取提示词或回复。请把这些钩子与你已有的钩子合并。

Claude Code，写在 ~/.claude/settings.json 中。每个钩子都会通过 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 钩子，并用 /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 检测来覆盖。

其他任何智能体都可以从自己的钩子调用 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 或虚拟机自身的进程离开），以及在编辑器扩展主机中运行的智能体，例如 VS Code 中的 Cline 或 Copilot，它们无法与编辑器区分。在 Cursor 和 Windsurf 中，在其终端输入的命令计入该应用。在两次一秒采样之间打开又关闭的连接仍计入会话字节数，但没有主机。内核的 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，不带参数时返回它自己的会话，这样智能体就能查看它运行的安装连接了哪些地方。

清除历史记录或忘记网站

在“设置 › 数据与隐私”中，忘记网站会从被阻止的尝试、智能体网络日志、智能体运行和保持唤醒会话的目标地址以及防护通知记录中移除主机。选择包含子域名还会移除 www.example.com 等名称。“清除网站历史记录”会移除过去一小时、午夜以来或全部相同记录。被阻止的尝试和智能体网络日志也有各自的清除菜单；主机行的上下文菜单提供“忘记”。清除历史记录会保留规则和防护设置。之后的活动仍可再次记录。

在终端中使用 kilobat history forget example.com --subdomains --json 或 kilobat history clear --hour（也可使用 --today 和 --all）。应用运行时，命令会要求应用删除实时记录；应用关闭时则编辑保存的历史记录。MCP clear_history 执行相同操作，但只在你要求智能体删除历史记录时执行。删除无法撤销；结果会统计从各历史记录中移除的条目。

某个应用在前台时

阅读或演示时，茶杯菜单里的“某个应用在前台时”只在你选定的应用位于前台时保持 Mac 唤醒，一旦切走就允许它重新睡眠。茶杯菜单里的“保持屏幕常亮”决定屏幕是否也保持点亮，这对 Kilobat 保持唤醒的所有情况都一样。Kilobat 跟随 macOS 自身的应用切换事件：它不轮询、不移动鼠标，也不伪造活动，所以无法让你在监控软件面前显得“在线”。应用退出、你手动关闭，或使用电池时电量降到 20%（或你为合盖运行设定的下限）时，它就会结束，而且从不阻止合盖睡眠。它有自己独立的唤醒保持，所以切换应用或退出应用都不会结束唤醒会话或智能体运行。在终端中：kilobat awake --while-frontmost Keynote --display。

接通电源时

打开“接通电源时保持唤醒”（设置 › 唤醒与智能体），或茶杯菜单里的“接通电源时”，插上电源适配器后 Mac 会一直保持唤醒，直到你拔掉电源，状态条上也会显示“接通电源时保持唤醒”。“保持屏幕常亮”决定屏幕是否也保持点亮。关闭后，它会保持关闭直到你下次插电，即使 Kilobat 重启也是如此。Kilobat 通过 macOS 自身的电源变化通知得知插拔，无需轮询。拔掉电源只会结束由插电开启的会话：你自己开启的会话、正在等待的下载、前台应用、智能体运行或来自终端的唤醒保持都会继续。它从不让 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 退出 1 分钟后。如果辅助程序或 Mac 在保持期间重启，它会先恢复原来的设置。Kilobat 会显示每次唤醒保持是如何结束的，例如“已允许 Mac 睡眠：电量为 20%”。

在终端中，kilobat awake --lid-closed 会向应用请求同样的唤醒保持，做不到时会说明原因；命令结束时，保持也随之结束。智能体使用 keep_awake 配合 lid_closed，其描述会要求智能体先与你确认。kilobat conditions --json 会报告 lidClosedAllowed 和当前的 lidHold。

智能体技能

9 个 Agent Skills 教编程智能体排查 Mac 网络问题，并借助 Kilobat 让长时间运行不中断。它们会解读 Kilobat 的测量结果，说明哪些地方不确定，并在更改设置前先询问。请一起安装；kilobat 技能会把智能体引向最合适的那个技能。

npx skills add seifip/kilobat-skills

用上面的 Homebrew 命令单独安装 Kilobat CLI，或连接它的 MCP 服务器。CLI 需要 macOS 14 或更高版本；通过 Homebrew 从源码构建需要 Xcode 16 或更高版本。查看 skills.sh 上的技能，或阅读它们的源码和参考资料。

Siri 与快捷指令

向 Siri 询问连接情况，Kilobat 会根据自身检查用一两句话回答，并附上数字卡片。按 Siri 的要求在问题中说出应用名称：“用 Kilobat 查看网速为什么慢？”会运行新的检查并指出原因：“Wi-Fi 正常；运营商线路自晚上 9:05 起丢失了 4% 的数据包。详情在运营商报告中。”其他问题包括：“用 Kilobat 查看连接是否正常？”“用 Kilobat 查看通话为什么卡住？”（上次通话报告）、“用 Kilobat 查看 Slack 是否故障？”（Kilobat 可读取状态页面的任何服务，或询问“用 Kilobat 查看应用是否故障？”以检查正在使用的应用）、“用 Kilobat 查看什么在使用网络？”“用 Kilobat 查看用了多少流量？”“用 Kilobat 查看是否可以开始通话？”“用 Kilobat 查看 VPN 是否泄漏？”以及“用 Kilobat 测试速度”。相同问题也可在聚焦搜索中使用，每项都是快捷指令应用中的操作，可将答案传给下一步：网络状态及其健康状况、原因、延迟和丢包；通话报告；服务及其是否报告故障；今天使用的数据量。快捷指令的“使用模型”操作可将这些结果交给 Apple Intelligence。没有 Kilobat Pro 时，Siri 会说明问题和线路测量值、通话卡住的次数以及服务是否故障；Pro 会补充原因和应对方法。现成快捷指令基于相同操作构建。