Agent Wallet — 开放技能

单个技能文件： skills/SKILL.md。Cursor 通过 .cursor/skills/open → skills/ 加载该文件。ClawHub 发布命令：clawhub publish skills。

OpenClaw / ClawHub： 关于 agent_id 与 TEE 如何交互的唯一可信来源。在提出“序列不匹配”或双 ID 理论前，请务必先阅读此处。

适用场景

• POST /create-agent-wallet、POST /sign-transaction、GET /agent/:id、GET /user/:username。
• 生产环境问题： 钱包错误、签名失败，/agent/2 与 /user/foo 对同一 ID 的所有者判断不一致。
• 部署配置： GKE 环境下需正确设置 DATABASE_URL、TEE_BASE_URL 和 INTERNAL_HMAC_SECRET。

错误假设 — 请勿使用以下说法

1. “TEE 分配 agent_id，且可能与 Postgres 不同步。”
   错误。 API 负责分配 agent_id（调用 allocUsername）。TEE 仅将 agent_id 作为 字符串 接收，并**仅用作 AES-GCM AAD**。TEE 内部无钱包表，也无 ID 序列机制。详见 api/src/teeClient.ts、tee-app/src/index.ts、tee-app/src/walletCore.ts。

2. “TEE 内存重置导致 ID 对齐失效。”
   具有误导性。 TEE 在身份管理上是无状态的。密文存储于 API（Share B）和 客户端（key_share）中。

3. “让 TEE 先返回 agent_id 即可修复。”
   错误的修复方式。 当前设计已明确为 API 主导的 ID 分配；TEE 仅使用该 AAD 进行加密。

若对同一数值型 agent_id 的 HTTP 查询结果不一致，常见原因是 多个 API 副本 + 内存数据库（未配置 DATABASE_URL），而非 TEE 与 Postgres 之间的不一致。

架构（权威定义）

流程：API 调用 allocUsername → TEE 调用 create-wallet 并传入 { agent_id } → API 调用 finalizeWallet。签名流程：API 根据 agent_id 加载 Share B，再将两份密钥分片（Share B 与 key_share）及 agent_id 一并转发至 TEE。

故障排查

参见 api/src/storage/createAgentWalletStorage.ts，其中包含当 DATABASE_URL 未设置时针对 K8s 环境的警告提示。

HTTP 路由

tx_data 格式定义： api/src/validation/txSchema.ts — 必须包含 chainId 字段；建议使用 jq 或 python3 构建 JSON（原始 shell 中 base64 编码的 key_share 易出错）。

常见错误码： 409（用户名已被占用）；404（未找到）；429（限流）+ scope；502（TEE 故障）。

运行环境

• API： api/.env.example — 对于多于一个副本的部署，DATABASE_URL 为必填项。
• TEE： tee-app/.env.example — TEE_MASTER_KEY 绝不可出现在 API 侧。

代码映射

api/src/index.ts、api/src/teeClient.ts、api/src/storage/*、tee-app/src/walletCore.ts、deploy/gcp/README.md。

ClawHub 发布

技能格式。已发布的技能采用 MIT-0 许可协议；本文件中不得包含任何密钥或敏感信息。

clawhub login
cd /path/to/agent-wallet
clawhub publish skills

在 OpenClaw 中安装或同步该技能包，使 Agent 能加载此能力。