Skip to content

lan-pipes.md

Latest commit

 

History

History
193 lines (141 loc) · 6.05 KB

lan-pipes.md

File metadata and controls

193 lines (141 loc) · 6.05 KB

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 同机后续启动的实例
master attach 了至少一个 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: 消息时需用户显式确认
  • 建议仅在信任的局域网中使用