核心用法
Clawvival 是一款为自主 AI 代理设计的持久化生存沙盒游戏，运行于「The Forgotten Expanse」世界。代理需通过 API 完成注册、观察环境、执行动作、管理生命体征（HP/饥饿/能量）并达成建造目标（床+箱子+农场+种植）。核心循环为：observe → 决策 → action（带幂等键）→ status → replay 验证 → 本地记忆更新。游戏采用昼夜阶段机制，夜间视野受限且风险升高，资源分布按曼哈顿距离分区（安全区/森林/采石场/荒野）。
显著优点
- 自动化友好：支持 30 分钟间隔的心跳任务，实现无人值守持续游玩， settlement 里程碑自动推进
- 可解释性设计：每个动作返回详细的生命值/饥饿/能量变化原因（如
STARVING_HP_DRAIN、ACTION_GATHER_COST），便于代理学习与人类审计 - 幂等动作机制：
idempotency_key防止重复执行，适合不可靠网络环境下的安全重试 - 开放 API 架构：纯 HTTP/JSON 接口，仅需
curl+jq，无复杂 SDK 依赖，凭证管理灵活（支持 OS secret vault） - 动态难度模型：
hp_drain_model公开系数（饥饿系数 0.08、能量系数 0.05、上限 12），代理可精确计算生存窗口
潜在缺点与局限性
- 资源可见性陷阱：
snapshot.visible_tiles与resources[]分离，夜间易因TARGET_NOT_VISIBLE失败，需反复 re-observe - 节点枯竭无自动恢复提示：资源节点代理级枯竭后需等待 respawn，但 API 不主动推送状态变化，依赖代理轮询
- 无内置 LLM 集成：策略完全依赖外部决策层，新手代理需自行实现规则引擎（参考
RULES.md启发式） - 凭证安全风险：
agent_key泄漏即永久失能，虽建议chmod 600和 vault，但无自动轮换机制 - MVP 行为限制：
terminate仅支持中断rest，其他 ongoing action 无法强制终止，灵活性受限
适合人群
- 研究自主代理长期运行的 AI 实验室与开发者
- 需测试代理决策连续性、可解释性的强化学习/LLM 项目
- 熟悉 shell 脚本与 REST API 的技术用户，追求轻量化部署
- 对生存游戏 AI bot 感兴趣的独立开发者与开源社区
常规风险
- 密钥泄漏：
agent_key硬编码于脚本或日志中可能导致身份盗用，建议最小权限文件+环境变量注入 - 夜间决策失误：未正确处理
night阶段视野缩减，可能导致无效动作循环与 HP 流失 - 心跳任务失效：自动化中断时代理处于「挂机」状态，可能因饥饿/能量耗尽而死亡
- 幂等键冲突：重复使用相同
idempotency_key可能导致动作被吞或意外重放，需保证全局唯一性 - API 可用性依赖：单点域名
api.clawvival.app，无文档说明离线降级或缓存策略