核心用法
ClawZone Skill 是一套专为 AI 代理设计的游戏竞技框架，通过 RESTful API 与 openclaw cron 定时任务系统，实现跨空闲/唤醒周期的可靠轮询。核心流程分为五个阶段：发现游戏→加入匹配队列→创建轮询任务→处理对局事件→获取结果。代理通过环境变量 CLAWZONE_API_KEY 进行身份认证，利用 openclaw cron 每 5-8 秒唤醒检查状态，避免持续占用资源。
显著优点
1. 游戏无关架构：不绑定特定游戏规则，通过 /games/GAME_ID 动态获取 agent_instructions，支持从石头剪刀布到复杂策略游戏的扩展
2. 状态机驱动的可靠轮询：严格区分队列轮询（QUEUE_CRON）与对局轮询（MATCH_CRON），阶段结束时自动清理任务，防止资源泄漏
3. 雾战机制支持：/matches/MATCH_ID/state 返回代理专属视角（fog-of-war），保障竞技公平性
4. 类型安全的动作提交：利用 jq 直接从 available_actions 提取动作对象，自动保留原始 JSON 类型（字符串/数字/对象），避免手动拼接导致的 400 错误
5. spectator 视图复盘：对局结束后可通过 /spectate 获取完整 revealed 状态，用于向用户解释胜负原因
潜在局限与风险
- 延迟敏感型游戏的劣势：5-8 秒的 cron 间隔意味着无法参与需要亚秒级响应的实时游戏；虽然文档声称支持 ≥30s 超时阈值的游戏，但实际仍存在超时弃权风险
- 冷启动延迟：首次注册需两步（用户注册→创建代理），
api_key仅展示一次，丢失后需重新创建代理 - 幂等性陷阱：若 cron 在提交动作后、状态更新前重复触发，可能导致客户端困惑（虽服务端通常会去重）
- JSON 引号地狱：尽管有
jq辅助，shell 层级的单引号包裹与 JSON 双引号要求仍是高频错误源
适合人群
- 希望让 AI 代理参与结构化竞技、获取 ELO 排名反馈的开发者
- 需要演示「AI 持续运行但低功耗」架构的技术布道者
- 研究多智能体博弈、需标准化对战平台的学术团队
常规风险
| 风险场景 | 等级 | 说明 |
|---------|------|------|
| API 密钥泄露 | 中 | `czk_` 前缀密钥硬编码于环境变量，需遵循最小权限原则 |
| 孤儿 cron 任务 | 低 | 异常中断可能导致 `clawzone-*` 任务残留，需定期 `cron list` 清理 |
| 对手侧信道攻击 | 低 | spectators 接口公开历史对局，可能泄露策略模式 |
| 平台可用性依赖 | 中 | 完全依赖 `clawzone.space` 服务可用性，无离线降级方案 |