Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ccb.agent-aura.top/llms.txt

Use this file to discover all available pages before exploring further.

​
LAN Pipes — 局域网多机器群控指南

​
什么是 LAN Pipes

LAN Pipes 让多台机器上的 Claude Code 实例通过局域网自动发现并协作。你可以在一台机器（main）上操控其他机器（sub）上的 Claude Code，发送 prompt、查看执行结果、审批权限请求——全程零配置。 基于本机 Pipe IPC（UDS_INBOX）扩展，新增 TCP 传输层 + UDP Multicast 发现。

​
前置条件

  • 两台或以上机器在同一局域网
  • 每台机器安装了 CCB 并能 bun run dev
  • Feature flag LAN_PIPES（dev/build 默认开启）
  • 防火墙允许 UDP 7101 + TCP 动态端口（见下方配置）

​
快速开始

​
第一步：配置防火墙

每台机器都需要执行。 Windows（管理员 PowerShell）： 
New-NetFirewallRule -DisplayName "CCB LAN Beacon (UDP)" -Direction Inbound -Protocol UDP -LocalPort 7101 -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "CCB LAN Pipes (TCP)" -Direction Inbound -Protocol TCP -LocalPort 1024-65535 -Program (Get-Command bun).Source -Action Allow -Profile Private
New-NetFirewallRule -DisplayName "CCB LAN Beacon Out (UDP)" -Direction Outbound -Protocol UDP -RemotePort 7101 -Action Allow -Profile Private
验证网络为”专用”（非公共）：Get-NetConnectionProfile macOS： 首次运行时系统弹出”允许接受传入连接”对话框，点击”允许”。 如果使用 pf 防火墙： 
echo "pass in proto udp from any to any port 7101" | sudo pfctl -ef -
Linux（firewalld）： 
sudo firewall-cmd --zone=trusted --add-port=7101/udp --permanent
sudo firewall-cmd --zone=trusted --add-port=1024-65535/tcp --permanent
sudo firewall-cmd --reload
Linux（iptables）： 
sudo iptables -A INPUT -p udp --dport 7101 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 1024:65535 -m owner --uid-owner $(id -u) -j ACCEPT

​
第二步：启动

# 机器 A（例如 192.168.50.22）
bun run dev

# 机器 B（例如 192.168.50.27）
bun run dev
启动后等待 3-5 秒（beacon 广播间隔），两边自动发现并连接。

​
第三步：查看和操作

在任一台机器上： 
/pipes
输出示例： 
pipe: cli-a91bad56 (main) 192.168.50.22  2/3 selected

Main machine: 205d6c3a... (this machine)
  [main] cli-a91bad56  XC/192.168.50.22  [alive] (you)
  ☑ [sub-1] cli-da029538  XC/192.168.50.22  [alive] [connected]

LAN Peers:
  ☐ [main] cli-04d67950  vmwin11/192.168.50.27  tcp:192.168.50.27:58853  [LAN]

​
第四步：选中目标并发送任务

  1. 按 Shift+↓ 展开选择面板
  2. ↑↓ 移动到 LAN peer
  3. Space 选中
  4. Enter 确认
  5. 输入 prompt，自动路由到远端执行
远端执行结果会流式回传到你的消息列表： 
[main vmwin11/192.168.50.27 / cli-04d67950] 正在检查 git status...
[main vmwin11/192.168.50.27 / cli-04d67950] Completed

​
完整命令参考

命令说明
/pipes显示所有实例（本机 + LAN），Shift+↓ 展开选择面板
/pipes select <name>选中某实例
/pipes all全选
/pipes none取消全选
/attach <name>手动 attach（自动识别 LAN peer 并通过 TCP 连接）
/detach <name>断开连接
/send <name> <msg>向指定 pipe 发送消息
/send tcp:host:port <msg>直接通过 TCP 地址发送
/claim-main强制声明为 main
/pipe-status显示详细状态
/peers列出所有已发现的 peer

​
快捷键

快捷键场景作用
Shift+↓状态栏可见时展开/收起选择面板
↑ / ↓面板展开时移动光标
Space面板展开时选中/取消
Enter面板展开时确认关闭
Esc面板展开时取消关闭
← / →有选中 pipe 时切换路由模式
M面板展开时同 ←/→ 切换路由模式

​
路由模式

模式显示行为
selected pipes only绿色prompt 仅发送到选中的 pipe，本地不执行
local main灰色prompt 仅在本地执行，不转发
切换路由模式不会清空选择。

​
权限转发

当远端 slave 执行需要权限的工具（如 BashTool）时：
  1. slave 发送 permission_request 到 main
  2. main 弹出权限确认对话框，显示 [role hostname/ip / pipeName]
  3. 用户确认/拒绝
  4. 结果发回 slave，继续或中断

​
工作原理

​
发现机制

  • 每台机器启动时创建 UDP multicast beacon
  • 组地址 224.0.71.67，端口 7101，TTL=1（不跨路由器）
  • 每 3 秒广播一次自身信息（pipeName、IP、TCP 端口、角色）
  • 15 秒未收到广播则标记 peer 丢失

​
通信机制

  • 本机实例：UDS（Unix Domain Socket / Named Pipe）
  • 跨机器：TCP（动态端口，通过 beacon 发现）
  • 协议：NDJSON（每行一个 JSON 对象）
  • 消息类型：ping/pong、attach/detach、prompt/stream/done/error、permission

​
角色模型

角色说明
main首个启动的实例
sub同机后续启动的实例
masterattach 了至少一个 slave 的实例
slave被 master attach 的实例
跨机器 attach 时，两边都可以是 main——不要求对方必须是 sub。

​
常见问题

​
看不到 LAN peer

  1. 检查防火墙是否放行 UDP 7101
  2. Get-NetConnectionProfile（Windows）确认网络为”专用”
  3. 确认两台机器在同一子网（ping 能通）
  4. 路由器未开启 AP 隔离

​
连接超时

  1. 检查 TCP 入站防火墙规则
  2. 确认没有 VPN 劫持流量
  3. 尝试 /send tcp:ip:port hello 直接测试

​
beacon 绑到了错误网卡

Windows 上 WSL/Docker 虚拟网卡可能劫持 multicast。beacon 会自动选择非内部 IPv4 接口。如果选错，检查 getLocalIp() 返回值。

​
安全说明

  • TCP 连接当前无认证——同 LAN 内知道端口号即可连接
  • Multicast TTL=1，不跨路由器
  • AI 通过 SendMessageTool 发送 tcp: 消息时需用户显式确认
  • 建议仅在信任的局域网中使用