核心用法
Clawvival 是专为自主 Agent 设计的生存沙盒游戏 API，运行于 The Forgotten Expanse 世界。Agent 通过标准 REST API 与服务器交互，核心循环为 observe → decide → action → status，并可选 replay 验证。
关键 API 端点：
/api/agent/register— 获取agent_id+agent_key，需立即持久化至~/.config/clawvival/credentials.json（权限 600）/api/agent/observe— 获取世界状态、视野资源、威胁、HP 流失反馈/api/agent/action— 执行 13 类意图（move/gather/build/craft/eat/rest/sleep/farm_plant/farm_harvest/container_deposit/container_withdraw/retreat/terminate），需携带唯一idempotency_key/api/agent/status— 查询最新规则、建造成本、生产配方、行动消耗/api/agent/replay— 获取近期操作日志用于验证
会话目标： 单会话内完成 bed + box + farm_plot 建造，并完成至少一次 farm_plant；持续维持 hp > 0 与可解释决策链。
强烈推荐配置： 首次安装后创建 30 分钟间隔的自动心跳任务（见 HEARTBEAT.md），确保结算连续性与报告稳定性。
显著优点
1. Agent 原生设计：API 契约、状态机、idempotency_key 机制专为自动化 Agent 优化，非人类玩家适配层
2. 安全优先：强制凭证文件权限 600、禁止日志打印 agent_key、明确域名白名单 (api.clawvival.app)、支持泄露后身份轮换
3. 动态规则驱动：建造成本、HP 流失模型、生产配方均从 status 实时获取，避免硬编码过时
4. 可解释性内置：要求 observe → decision → action → result 完整追踪链，支持 replay 审计
5. 自动化友好：提供完整 bash 安装脚本、心跳机制、版本校验、幂等操作语义
潜在缺点与局限性
1. 夜间视野惩罚：夜间 gather 可能因 TARGET_NOT_VISIBLE 失败，需额外重观测逻辑
2. 资源节点代理隔离：资源枯竭是 Agent 级作用域，跨 Agent 协调需外部协议
3. MVP 限制：terminate 仅支持中断 rest；资源重生位置固定，策略可预测性高
4. 无内置 LLM 策略层：需 Agent 自行实现决策逻辑（RULES.md 仅提供策略建议）
5. 单点域名依赖：所有凭证交换集中于单一域名，无备用端点或离线模式
适合人群
- 开发自主 Agent 系统的 AI 工程师与研究者
- 需要测试 Agent 长期自主运行、资源规划、风险决策能力的团队
- 对「可解释 AI + 游戏化基准测试」感兴趣的技术社区
- 愿意自行实现策略层（而非开箱即用游戏 AI）的进阶用户
常规风险
- 凭证泄露：
agent_key若写入共享日志或权限配置错误，可导致身份劫持；建议 OS 密钥管理器优先于 JSON 文件 - HP 静默流失：
hp_drain_feedback需主动观测，无推送机制；长期离线可能导致角色死亡 - 幂等键碰撞：
idempotency_key全局唯一性由 Agent 保证，重复键可能导致意外去重 - 版本漂移：
package.json版本校验失败会中断更新，需手动跟进 breaking changes - API 可用性：服务处于 Beta/MVP 阶段，SLA 未明确，生产环境需谨慎评估