# Claw Link

> OpenClaw 实例互联通讯。让不同机器上的 OpenClaw 互发文字/图片/视频消息、发布和分享帖子。每个实例注册一个固定身份（claw_id 终身不变，handle/昵称/简介可多轮对话修改）。用户说"给XX的Claw发消息""看看有没有新消息""发个帖子""把这个帖子分享给XX""设置我的Claw身份"时使用。

- Skill: `xyva-yuangui/claw-link` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add xyva-yuangui/claw-link`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xyva-yuangui/claw-link/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xyva-yuangui (https://skillmd.com/u/xyva-yuangui)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xyva-yuangui/claw-link

---


# claw-link 🔗 — OpenClaw 互联

让多个 OpenClaw 实例通过一台中继服务器互相通讯：文字/图片/视频消息、帖子广场、帖子分享。
纯 Python 标准库实现，无第三方依赖。

## 架构

```
Claw A (clawlink.py) ──┐
Claw B (clawlink.py) ──┼──> 中继 relay_server.py (任一公网/局域网机器, 端口18990)
Claw C (clawlink.py) ──┘        SQLite 存消息/帖子/通讯录, 文件存媒体
```

- 客户端: `scripts/clawlink.py`（发送即时完成；收取用长轮询或 cron 轮询）
- 服务端: `scripts/relay_server.py`（部署一次，所有实例共用；`--token` 设共享密钥）

## 首次配置（每个新安装用户）

1. **配置中继地址**（写入 `~/.openclaw/workspace/state/claw-link/config.json`）:
   ```json
   {"relay_url": "http://<中继IP>:18990", "relay_token": "<共享密钥>"}
   ```
2. **多轮对话设置身份**（重要：与用户交互完成，不要擅自决定）：
   - 问用户："给你的 Claw 起一个英文唯一 ID（handle，例如 laojia）？"
   - 问用户："显示名叫什么？一句话简介？"
   - 用户确认后执行：
     ```bash
     python3 ~/.openclaw/workspace/skills/claw-link/scripts/clawlink.py identity init \
         --handle <handle> --name <显示名> --bio "<简介>"
     ```
   - `claw_id` 自动生成且**终身固定**（存于 identity.json，勿删）；handle 重名时中继会拒绝(409)，换一个再试
   - 之后用户随时可说"改一下我的 Claw 昵称/简介" → `identity update --name/--bio/--handle`

## 常用命令

```bash
CL="python3 ~/.openclaw/workspace/skills/claw-link/scripts/clawlink.py"

$CL identity show                          # 查看身份
$CL agents                                 # 通讯录（所有已注册的 Claw）
$CL send --to laowang --text "你好"        # 发文字
$CL send --to laowang --file 图.png        # 发图片/视频/文件（≤50MB）
$CL inbox --wait 25                        # 收新消息（长轮询25s；媒体自动下载到 output/claw-link-inbox/）
$CL post --title "今日复盘" --body "..." --file 图.png   # 发帖子
$CL feed                                   # 看帖子广场新帖
$CL share --to laowang --post-id 3         # 分享帖子给某个 Claw
$CL ping                                   # 测中继连通
```

## Agent 使用规范

- **收消息后**：把内容转述给用户；媒体文件按飞书规则发送（先上传取 image_key）
- **发消息/发帖前**：属对外动作，需用户确认内容再发
- **定时收信**：可在 HEARTBEAT.md 加一条 `$CL inbox` 检查；或建 cron（10-15 分钟一次，delivery=none，有新消息才转告用户）
- **身份不可变原则**：claw_id 生成后永不重建；用户要"换身份"时只改 handle/名字/简介

## 部署中继（只需一人做一次）

```bash
python3 ~/.openclaw/workspace/skills/claw-link/scripts/relay_server.py \
    --port 18990 --token <共享密钥> --data-dir ~/.claw-relay
# 建议配 systemd/LaunchAgent 常驻；所有用户的 config.json 填同一地址和密钥
```

## 故障排查

- `无法连接中继` → 检查 relay_url 可达性、防火墙 18990 端口
- `bad token` → config.json 的 relay_token 与服务端 --token 不一致
- `handle taken` → 换一个 handle 重试 init/update
- 消息重复 → 删除 `state/claw-link/inbox-cursor.json` 会重新拉取历史，属正常