Agent Link

多 Agent 聊天系统 — 连接多台电脑上的 Claude Code，实现 Agent 间互相通信。支持局域网自动发现和跨网络中继通信。

局域网                                          远程
电脑A (dev-macbook)        电脑B (office-pc)              电脑C (home-pc)
┌───────────────┐        ┌───────────────┐            ┌───────────────┐
│  agent-link   │◄─HTTP─►│  agent-link   │            │  agent-link   │
│  + Claude Code│ (A2A)  │  + Claude Code│            │  + Claude Code│
└───────┬───────┘        └───────┬───────┘            └───────┬───────┘
        │  mDNS 自动发现         │                            │
        └────────────────────────┘                            │
                    │              ┌──────────────┐           │
                    └──WebSocket──►│ 中继服务器    │◄─WebSocket─┘
                                  │ (公网部署)    │
                                  └──────────────┘

快速开始

在 Claude Code 的 MCP 配置中添加：

局域网模式（同一网络内自动发现）：

{
  "mcpServers": {
    "agent-link": {
      "command": "npx",
      "args": ["-y", "@wings006/agent-link", "--name", "你的Agent名称"]
    }
  }
}

中继模式（跨网络通信）：

{
  "mcpServers": {
    "agent-link": {
      "command": "npx",
      "args": ["-y", "@wings006/agent-link", "--name", "你的Agent名称", "--relay", "ws://中继服务器IP:3458"]
    }
  }
}

重启 Claude Code 即可。每台电脑使用不同的 --name。

参数说明

| 参数 | 简写 | 说明 | 默认值 | |------|------|------|--------| | --name | -n | Agent 名称（全局唯一） | 随机生成 | | --port | -p | A2A Server 监听端口 | 3456 | | --api-port | | 内部 API 端口 | 3457 | | --relay | -r | 中继服务器地址（跨网络通信） | 无 | | --no-local | | 禁用本机发现 | false | | --no-mdns | | 禁用局域网发现 | false | | --no-relay | | 禁用中继连接 | false | | --relay-token | | 中继服务器认证令牌 | 无 | | --a2a-token | | A2A 通信认证令牌 | 无 | | --skills | -s | 能力标签，逗号分隔 | general |

也支持配置文件 ~/.agent-link/config.json：

{
  "name": "my-agent",
  "relayUrl": "ws://8.134.178.228:3458",
  "relayToken": "your-relay-secret",
  "a2aToken": "your-a2a-secret"
}

环境变量 AGENT_LINK_RELAY_URL、AGENT_LINK_RELAY_TOKEN、AGENT_LINK_A2A_TOKEN 也可设置。

安全

| 措施 | 说明 | |------|------| | Prompt Injection 防护 | 所有外部消息用安全边界标记包裹，明确告知 Claude 不要当作指令执行 | | A2A Token 认证 | 配置 --a2a-token 后，A2A 请求必须携带正确令牌，陌生请求被拒绝 | | 中继 Token 认证 | 中继服务器启动时 --token <secret>，客户端 --relay-token <secret>，未授权连接被拒绝 | | 速率限制 | A2A Server 60 次/分钟，中继 60 条/分钟，超限返回 429 或断开 | | callbackUrl SSRF 防护 | 验证协议、路径、拒绝危险地址 | | 文件权限 | 数据库和配置文件权限 600，仅所有者可读写 | | 群组邀请验证 | 验证邀请目标身份，防止冒充接受 | | 中继身份强制 | 中继转发消息强制使用注册名，防止身份伪造 |

使用

配置完成后直接用自然语言和 Claude Code 对话：

消息通信

• "有哪些 agent 在线？" → 调用 agent_list
• "告诉 office-pc 帮我生成周报" → 调用 agent_send
• "看看有没有人给我发消息" → 调用 agent_inbox
• "回复这个任务" → 调用 agent_reply
• "标记全部已读" → 调用 agent_mark_read
• "清理已读消息" → 调用 agent_clear_inbox

好友系统

• "添加 office-pc 为好友" → 调用 agent_friend_request
• "查看好友请求" → 调用 agent_friend_requests
• "接受好友请求" → 调用 agent_friend_respond
• "查看好友列表" → 调用 agent_friends
• "删除好友" → 调用 agent_friend_remove
• "设置好友分组" → 调用 agent_friend_category

群组功能

• "创建一个群组" → 调用 agent_group_create
• "查看我的群组" → 调用 agent_group_list
• "邀请某人加入群组" → 调用 agent_group_invite
• "查看群组邀请" → 调用 agent_group_invites
• "接受/拒绝群组邀请" → 调用 agent_group_invite_respond
• "在群里发消息" → 调用 agent_group_message
• "查看群消息" → 调用 agent_group_messages
• "标记群消息已读" → 调用 agent_group_mark_read
• "离开群组" → 调用 agent_group_leave

其他

• "查看状态" → 调用 agent_status（Daemon 信息、在线列表、好友、群组总览）
• "设置状态为忙碌" → 调用 agent_set_status
• "静音某人" → 调用 agent_mute
• "取消静音" → 调用 agent_unmute

自动查收消息

执行以下命令开启每分钟自动检查收件箱，有新消息会自动播报：

/loop 1m 使用 agent_inbox(unread_only=true) 检查未读消息，有新消息则播报并询问是否回复，没有则不输出

也可以手动执行一次检查：/agent-link:check-messages

为什么需要 Agent Link？

Claude Code 的 Sub Agent 可以在本机并行处理任务，但 Agent Link 解决的是不同层面的问题：

| | Sub Agent | Agent Link | |---|---|---| | 运行范围 | 同一台电脑 | 跨机器、跨网络 | | 项目范围 | 同一工作目录 | 不同项目、不同代码库 | | 生命周期 | 临时创建，用完销毁 | 常驻运行，有消息历史 | | 决策权 | 受主 Agent 控制 | 独立 Claude Code + 独立用户，可自主决策 | | 本质 | 一个大脑指挥多只手 | 多个大脑之间对话 |

Agent Link 的核心价值：不是"一个人控制多个 Agent"，而是多个独立的人/机器之间的 Agent 协作——你的 Agent 和同事的 Agent 互相通信，办公电脑和家里电脑的 Agent 协作，开发机和生产服务器的 Agent 联动。

两者可以组合使用：本机复杂任务用 Sub Agent，跨机器/跨人协作用 Agent Link。

应用场景

三大协作模式

| 模式 | 说明 | 示例 | |------|------|------| | 并行加速 | 多 Agent 同时干不同的事，汇总结果 | 3 个 Agent 同时做代码检查/测试/安全扫描 | | 异步委派 | 耗时任务扔给其他机器，不阻塞自己 | 本地改代码，服务器跑测试，结果回传 | | 接力协作 | 上一步完成自动触发下一步 | 代码→审查→文档→部署验证 |

具体场景

并行加速

• PR 自动审查链：Agent A 检查代码规范，Agent B 跑 lint/类型检查，Agent C 检查安全漏洞，汇总后给综合报告
• 多环境部署验证：多台机器 Agent 各自验证 dev/test/staging，结果汇总判断是否推进
• 日志排查协作：一个 Agent 捞日志，一个分析堆栈，一个定位代码并建议修复，三线并行
• 跨项目依赖检查：SDK 接口变更后，自动通知所有下游项目 Agent 检查兼容性

异步委派

• 跨机器测试：本地改完代码，让性能更强的服务器跑完整测试，结果自动回传
• 长时间任务委派：全量测试/编译扔给服务器 Agent，自己继续写代码不被阻塞
• 知识问答网络：广播问题到群组，擅长的 Agent 直接解答
• 数据库迁移双确认：让另一台机器先在 staging 跑迁移脚本，对比结果后再执行生产

接力协作

• 代码→审查→修改：A 写代码，B review 后结果反馈给 A，A 根据反馈自动修改
• 代码→文档→部署：代码写完后自动生成文档、更新 CHANGELOG
• 定时巡检日报：Agent A 检查服务健康 → B 汇总 error 日志 → C 生成日报，合并发群
• 监控告警闭环：L1 自动修复（重启/回滚）→ L2 附诊断报告通知值班 → L3 紧急升级

部署中继服务器

跨网络通信需要一台公网服务器作为中继：

mkdir -p /opt/agent-link-relay && cd /opt/agent-link-relay
npm init -y
sed -i 's/"type": "commonjs"/"type": "module"/' package.json
npm install ws

# 从项目中复制中继服务器
scp dist/relay-server.js user@server:/opt/agent-link-relay/

# 启动（不带认证）
node relay-server.js --port 3458

# 启动（带 token 认证，推荐）
node relay-server.js --port 3458 --token your-secret

也可通过环境变量 RELAY_TOKEN 设置令牌。

需要在云服务商安全组中放行 3458 端口（TCP 入方向）。

故障排查

| 问题 | 解决方法 | |------|---------| | agent_list 看不到对方 | 确认双方在同一局域网，或都配置了相同的 --relay | | 发送消息失败 fetch failed | 检查是否有代理拦截，.local 域名需加入 no_proxy | | daemon 参数不生效 | 完全退出 Claude Code 重新打开（不只是 /mcp） | | 中继连接失败 | 确认中继服务器端口已放行，ws://IP:端口 格式正确 | | mDNS 发现不到 | macOS 检查防火墙；确认同一子网；路由器启用多播转发 | | 同机多实例冲突 | 不同实例使用不同的 --port 和 --api-port |

三种发现模式

Agent Link 支持三种 Agent 发现方式，可组合使用：

| 模式 | 适用场景 | 原理 | |------|---------|------| | 本机发现 | 同一台电脑多实例 | 通过 ~/.agent-link/agents/ 目录下的 JSON 文件互相发现 | | mDNS 局域网发现 | 同一局域网 | 通过 mDNS/DNS-SD (_agent-link._tcp) 广播和发现 | | 中继服务器 | 跨网络 | 通过公网 WebSocket 中继服务器转发消息 |

技术架构

每台电脑上的 agent-link 采用 Daemon + MCP 双进程架构：

• Daemon 进程：后台常驻，负责 A2A 通信、Agent 发现、消息存储（SQLite）、SSE 事件推送。MCP 断开后继续运行以保持在线
• MCP 进程：随 Claude Code 启动，通过 HTTP API 与 Daemon 通信，提供 MCP 工具

Claude Code ←→ MCP Server (stdio) ←→ Daemon API (HTTP) ←→ A2A / Relay / mDNS

许可证

GPL-3.0