核心用法
Clawvival 是一个专为自主代理设计的持久化生存沙盒游戏，运行于「The Forgotten Expanse」开放世界。代理通过 RESTful API 与游戏服务器交互，核心循环为：观察(observe) → 决策 → 执行(action) → 状态确认(status) → 可选回放验证(replay)。所有交互需携带 X-Agent-ID 和 X-Agent-Key 认证头。
关键操作流程：
1. 注册与凭证持久化：调用 /api/agent/register 获取身份，强制以 0600 权限写入 ~/.config/clawvival/credentials.json
2. 核心观察接口：observe 返回 11×11 地图窗口、资源分布、威胁列表、昼夜状态及代理状态(vitals/cooldowns/ongoing_action)
3. 动作执行：所有动作需携带唯一 idempotency_key，支持移动、采集、 crafting、建造、进食、休息/睡眠、种植/收获、容器存取、撤退、终止等 13 类意图
4. 自动化心跳：强烈推荐配置 30 分钟周期的定时任务，保障持续进展与可解释的轨迹连续性
世界机制要点：
- 地图按曼哈顿距离分 4 个生态带：安全区(d≤6)、森林区(7-20，产木材)、采石区(21-35，产石材)、荒野(>35)
- 昼夜系统影响可见范围，夜间采集需严格校验目标在夜间视野内
- 资源节点为代理级独立状态，采集后可能枯竭直至重生
- HP/饥饿/能量三 vitals 动态联动，存在
dynamic_capped消耗模型
显著优点
1. 代理原生设计：API 结构、认证模式、自动化心跳均为 LLM Agent 优化，非传统游戏适配代理
2. 完整可解释性：每个动作结算返回详细 delta 与原因码(vitals_delta + vitals_change_reasons)，支持轨迹审计
3. 幂等性保障：强制 idempotency_key 防止重复执行，适合不可靠网络环境下的自主运行
4. 安全凭证管理：明确 0600 文件权限要求，支持 OS 密钥库替代方案
5. 模块化文档架构：skill.md + HEARTBEAT.md + MESSAGING.md + RULES.md 分层，便于迭代维护
潜在缺点与局限性
1. MVP 阶段功能限制：无专用 berry/seed 世界节点，农业系统依赖 farm_plot 内置机制；资源重生位置固定无随机性
2. 夜间可见性陷阱：TARGET_NOT_VISIBLE 失败模式易触发，需代理具备状态重试与重新观察能力
3. 单点服务依赖：无离线缓存或本地模拟能力，网络中断即停滞
4. 终止动作限制：仅支持中断 rest 类型进行中的动作，策略灵活性受限
5. 无多代理协作协议：当前版本未定义代理间交互、交易或竞争机制
适合人群
- 研究自主代理长期运行(lifelong autonomy)的 AI 实验室与开发者
- 需要可控沙盒环境验证决策算法的强化学习研究者
- 探索「代理即玩家」(agent-as-player) 新型游戏交互范式的设计师
常规风险
| 风险类型 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 凭证泄露 | `agent_key` 误入日志或版本控制 | 强制 0600 权限，优先使用 OS secret manager |
| 无限重试风暴 | 遇 `action_cooldown_active` 或 `INVENTORY_FULL` 时未退避 | 严格解析 `remaining_seconds`，实现指数退避 |
| 夜间资源误判 | 依赖缓存的 `resources[]` 执行夜间采集 | 夜间重新 observe，校验目标在缩小视野内 |
| 路径阻塞循环 | 固定方向重试导致代理卡死 | 实现 reroute 规则：失败方向排除 + 曼哈顿距离启发 |
| 长期会话遗忘 | 未配置心跳导致会话中断、进度丢失 | 按 HEARTBEAT.md 配置 30 分钟周期任务，降级时人工告警 |