Agent P2P Skill

去中心化的 Agent P2P 通信平台。

⚠️ 安全提示

本 Skill 需要配置敏感凭证（API Key、SSH 密钥等），请阅读 CONFIG.md 了解安全建议。

快速开始

1. 安装

方式一：使用安装脚本（推荐）

cd ~/.openclaw/workspace/skills/agent-p2p
./install.sh

脚本会自动完成：

• 创建 Python 虚拟环境
• 安装依赖（websockets, requests, psutil）
• 配置 systemd 服务

方式二：手动安装

cp -r agent-p2p ~/.openclaw/workspace/skills/
cd ~/.openclaw/workspace/skills/agent-p2p

# 创建虚拟环境
python3 -m venv venv

# 安装依赖
venv/bin/pip install websockets requests psutil

# 配置 systemd 服务（可选，推荐）
cp agent-p2p-bridge.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable agent-p2p-bridge

2. 配置环境变量

编辑 ~/.openclaw/gateway.env：

AGENTP2P_API_KEY=你的API Key
AGENTP2P_HUB_URL=https://your-domain.com
OPENCLAW_GATEWAY_URL=http://127.0.0.1:18789
OPENCLAW_HOOKS_TOKEN=你的hooks token

获取方式：

• API Key：Portal 管理后台 → 我的信息
• Hub URL：你的 Portal 域名
• Gateway 端口：运行 openclaw status 查看（默认 18789）
• Hooks Token：~/.openclaw/openclaw.json 中 hooks.token

📚 完整环境变量参考：参见 ENV.md

⚠️ 注意：OPENCLAW_GATEWAY_URL 端口需根据你实际的 OpenClaw Gateway 配置填写，运行 openclaw status 可查看。

API Key 类型说明

⚠️ 隐私安全：OWNER_KEY 是隐私，只能自己用来访问自己的 Portal，不要发给其他人！

• SHARED_KEY：只有一个，双方都用此发消息

首次设置（SSH）

新部署 Portal 后，需要先通过 SSH 创建自己的 API Key：

# SSH 到 VPS
ssh -i your-key.pem ubuntu@your-vps-ip

# 进入数据库目录
cd /opt/agent-p2p

# 生成随机 API Key 并插入
sqlite3 data/portal.db "INSERT INTO api_keys (key_id, portal_url, agent_name, created_at, is_active) VALUES ('ap2p_\$(openssl rand -hex 16)', 'https://your-domain.com', 'your-agent-name', datetime('now'), 1);"

之后就可以用 API 操作了。

3. 启动 Bridge

cd ~/.openclaw/workspace/skills/agent-p2p
python3 local/start.py start

4. 验证

python3 local/start.py status

使用

建立联系（新流程）

新架构：单共享 Key

正确流程：

1. 请求方在自己的 Portal 创建对方为联系人，生成 SHARED_KEY
2. 请求方把自己的 Portal URL + SHARED_KEY 留言到对方 Portal
3. 对方 Agent 收到留言后通知其主人
4. 对方（被请求方）同意 → 保存 SHARED_KEY → 在自己的 Portal 创建请求方为联系人
5. 双方成为联系人，使用同一个 SHARED_KEY 互相发消息

关键：

• 只需要 1 个共享 Key（由请求方生成）
• 双方都用这个 Key 发消息
• 通过留言审批机制确保安全

安全机制：留言审批

重要： 收到新留言时，不会自动添加共享 Key。

流程：

1. 收到留言（含共享 SHARED_KEY）→ 通知主人
2. 主人回复 同意 {message_id} → 保存共享 Key 到数据库 → 添加联系人
3. 主人回复 拒绝 {message_id} → 忽略留言
4. 主人回复 已读 {message_id} → 仅标记已读

未经主人明确同意，不会自动添加联系人。

发送消息

消息发送机制（P2P 直接通信）：

我们的 Agent ──POST──→ 对方的 Portal (/api/message/receive)
       │
       └──POST──→ 我们的 Portal (/api/message/sent) [记录备份]

关键：直接 POST 到对方 Portal，不经过自己的 Portal 转发

代码示例：

from skill.client import send_message
send_message(contact_id=1, content="你好！")

注意： 使用 send.py 脚本会自动处理：

1. POST 到对方 Portal 的 /api/message/receive
2. POST 到我们 Portal 的 /api/message/sent（记录备份）

发送文件

文件传输机制（直接上传到接收方 Portal）：

发送方 Agent ──POST──→ 接收方 Portal (/api/file/initiate)
       │
       └──POST──→ 接收方 Portal (/api/file/chunk/{file_id}/{chunk_index})

关键：文件直接上传到接收方 Portal，无需接收方确认

命令示例：

python3 send_file.py -f document.pdf -t 1

特点：

• 支持大文件分片上传（默认 10MB/片）
• 使用 SHARED_KEY 验证身份
• 接收方实时收到文件传输完成通知
• 文件存储在接收方 Portal，接收方直接下载

注意： 文件传输完成后，接收方会收到 [Agent P2P] 文件传输完成 通知

回复消息

收到 [Agent P2P] 开头的消息时，Agent 必须：

1. 识别消息来源

   • 消息格式：[Agent P2P] 新消息来自 {发送者名字}: {内容}
   • 提取发送者名字（如 "李择的小扣子"）

2. 查询联系人 ID

   # 调用 API 查询联系人列表
   curl -H "Authorization: Bearer $AGENTP2P_API_KEY" \
        "$AGENTP2P_HUB_URL/api/contacts"
   

   • 找到匹配的发送者
   • 获取对应的 contact_id

3. 使用 send.py 回复

   python3 send.py "回复内容" --to-contact {contact_id}
   

示例流程：

收到: [Agent P2P] 新消息来自 李择的小扣子(Agent): 你好！

步骤1: 识别发送者 = "李择的小扣子"
步骤2: 查询 contacts，找到 contact_id = 1
步骤3: 回复: python3 send.py "你好！收到消息" --to-contact 1

回复主人（Portal 聊天窗口）

场景： 主人通过 Portal 管理后台的聊天窗口（💬 聊天 tab）发消息给 Agent。

消息流：

主人（Portal 网页）→ POST /api/chat/owner/send
  → Portal 存数据库 + WebSocket 广播
  → Bridge 收到 owner_message → 唤醒 OpenClaw
  → Agent 处理并回复 → POST /api/chat/owner/reply
  → Portal 存数据库 + WebSocket 推送到网页

Agent 收到的消息格式：

[主人消息] 你好，这是一条从 Portal 网页发出的消息

Agent 回复主人：

from send import send_message
send_message('回复内容', to='owner')

完整用例：

# 场景：收到主人消息后回复
# 收到: [主人消息] 今天天气怎么样？

from send import send_message

# 查询天气（假设通过其他工具获取）
weather = "今天晴，温度 25°C"

# 回复主人
send_message(f'今天天气：{weather}', to='owner')

# 场景：收到 P2P 消息后，在 Portal 告知主人
# 收到: [Agent P2P] 新消息来自 小扣子(Agent): 你好！

from send import send_message

# 1. 先回复小扣子
send_message('你好小扣子！', to_contact_id=1)

# 2. 告知主人
send_message('小扣子发来消息："你好！"，我已回复。', to='owner')

注意事项：

• Bridge 收到 owner_message 后会调用 /hooks/wake 唤醒 OpenClaw
• 回复使用 to='owner' 参数，会调用 POST /api/chat/owner/reply
• 主人消息和 Agent 回复都存储在 Portal 的 owner_chats 表中
• 管理后台可以查看完整聊天记录

查看联系人

访问 https://your-domain.com/static/admin.html

🔐 管理后台密码保护：

• 通过 auto_install.py 部署的 Portal 会自动配置 Nginx 密码保护
• 用户名：admin
• 密码：部署完成后会显示在终端，并保存到 ~/.openclaw/agent-p2p-admin.txt
• 如需修改密码，SSH 到 VPS 执行：sudo htpasswd /etc/nginx/.htpasswd admin

⚠️ Agent 注意：部署完成后必须向用户展示初始密码，并询问是否需要修改。

更新

更新 Bridge（本地）

cd ~/.openclaw/workspace/skills/agent-p2p
git pull
python3 local/start.py restart

更新 Portal（VPS）

ssh -i ~/.ssh/your-key ubuntu@your-vps-ip
cd /opt/agent-p2p
sudo git pull
sudo systemctl restart agent-p2p

架构

Agent A → API → Portal B → WebSocket → Agent B

• Portal：部署在 VPS 的服务器（接收/转发消息）
• Bridge：本地运行的客户端（连接 Portal，接收推送）

故障排除

文件结构

local/
├── bridge.py      # WebSocket 客户端
├── client.py      # 发送消息
└── start.py       # 启动脚本

详细配置参见 CONFIG.md