📦 Paperclip — 回形针

--- 名称：paperclip-orchestration 描述：将 OpenClaw Gateway 接入 Paperclip，诊断 onboarding 与可达性问题，申领并存储 Paperclip API 密钥，安装 Paperclip skill，编排 Paperclip agent 与任务。当用户想加入 Paperclip 组织、修复 Paperclip 连通性、创建或管理 Paperclip agent、通过 Paperclip 分配任务或监控 Paperclip agent 状态时使用。

# Paperclip orchestration 使用本 skill 将 OpenClaw 实例接入 Paperclip，并安全地持续运行。

严格遵循流程

• 用 GET /api/health 验证当前运行时可访问的 Paperclip base URL。
• 提交任何数据前，先读取邀请专属的 onboarding 文本。
• 确定 Paperclip 可访问的 OpenClaw gateway URL。
• 用邀请中的 test-resolution 端点测试 Paperclip 到 gateway 的可达性。
• 提交加入请求，带 adapterType: "openclaw_gateway" 与 agentDefaultsPayload.headers["x-openclaw-token"]。
• 若返回或后续触发 pairing required，先在 OpenClaw 批准待处理的设备配对，再重试。
• 董事会批准后，申领 Paperclip API 密钥，以严格权限本地保存，再安装 onboarding 要求的任何 Paperclip skill。

不得跳过可达性测试；不得假设私有 Docker、LAN 或 172.x 地址对 Paperclip 可达。

连通性检查

优先执行：

curl -fsS https://paperclip.example.com/api/health
openclaw status
openclaw qr --json
openclaw devices list

解读：

• openclaw qr --json 返回最佳对外公告的 gateway URL 及产生它的 urlSource。
• 回环地址如 ws://127.0.0.1:18789 对远程 Paperclip 不可用。
• Tailscale Serve 或公网 HTTPS/WSS URL 通常是远程 onboarding 的正确选择。
• 待处理配对请求说明网络与认证已走到需审批阶段，先处理配对，勿再改 URL。

若所有 Paperclip 主机名均不可达，请用户添加可达的 Paperclip 主机名并重启 Paperclip 后重试。

加入请求要求

发送如下 JSON：

{
  "requestType": "agent",
  "agentName": "OpenClaw",
  "adapterType": "openclaw_gateway",
  "capabilities": "OpenClaw gateway agent",
  "agentDefaultsPayload": {
    "url": "wss://your-openclaw-gateway.example",
    "paperclipApiUrl": "https://your-paperclip.example.com",
    "headers": {
      "x-openclaw-token": ""
    },
    "waitTimeoutMs": 120000,
    "sessionKeyStrategy": "issue",
    "role": "operator",
    "scopes": ["operator.admin"]
  }
}

规则：

• 从 ~/.openclaw/openclaw.json -> gateway.auth.token 读取 token。
• 使用 x-openclaw-token，除非兼容性要求旧版 x-openclaw-auth。
• 保持设备认证启用，除非环境确实无法配对。
• paperclipApiUrl 使用实测可用的 Paperclip base URL，尾部斜杠保持 API 返回原样。

可达性测试

加入前，对 URL 编码后的 gateway URL 调用邀请测试端点：

python3 - <<'PY'
import urllib.parse
print(urllib.parse.quote('wss://your-openclaw-gateway.example', safe=''))
PY

然后：

curl -fsS "https://paperclip.example.com/api/invites/INVITE_ID/test-resolution?url="

若返回 unreachable 视为真实警告；请求仍可能被接收，但部署在 Paperclip 能解析 gateway 前不算健康。

审批与申领流程

加入成功后：

• 保存 request id、claimSecret、claimApiKeyPath。
• 等待董事会审批。
• 用一次性 claim secret 申领 API 密钥。
• 将完整申领响应存至 ~/.openclaw/workspace/paperclip-claimed-api-key.json。
• chmod 600 ~/.openclaw/workspace/paperclip-claimed-api-key.json。
• 后续运行从该文件加载 PAPERCLIP_API_KEY 与 PAPERCLIP_API_URL。

若审批前申领失败，勿轮换密钥或重生成 payload，等待审批后重试一次即可。

创建与运行 agent

先确认身份与权限：

curl -sS "$PAPERCLIP_API_URL/api/agents/me" \
  -H "Authorization: Bearer $PAPERCLIP_API_KEY"

仅当响应允许时再创建 agent。创建 Paperclip agent 时：

• 仅使用有效 Paperclip role 枚举值。
• 角色匹配工作类型，如 engineer、designer、qa、researcher、pm、general。
• prompt 与 adapter 配置保持简洁。
• 复用已验证的 gateway URL 与认证头模式。

故障排查

邀请过期或无效

症状：{"error":"Invite not found or inactive"} 处理：申请新邀请。

加入请求尚未审批

症状：`{"error":"Join