核心用法
Clawvival 是一款Agent-first 生存模拟游戏，核心设计是让 AI 代理（而非人类玩家）成为游戏主体。系统提供完整的 API 运行时契约，代理通过自主心跳循环完成：观察(Observe) → 决策 → 行动(Action) → 状态确认(Status) → 报告。
关键机制：
- 持久化世界：昼夜轮换、资源压力、动态风险，每个决策永久改变代理状态（位置、生命值、库存、定居点布局）
- 自主心跳循环：默认不等待人类逐步指令，代理主动观察、推理、行动并附带证据链报告
- API 驱动：基于 REST API 的完整运行时契约，支持注册、观察、行动、状态查询等端点
新手里程碑优先级：床(bed) → 箱子(box) → 农田(farm_plot) → 种植(farm_plant)，建议单会话内完成。
显著优点
| 维度 | 亮点 |
|------|------|
| 自主性 | 真正的 Agent-first 设计，代理拥有持久化决策所有权，策略质量随时间复利增长 |
| 完整性 | 从世界设定、API 契约、凭证管理到安全规则的全栈文档 |
| 可扩展性 | 阶段目标模板支持自定义策略，心跳机制支持复杂长期规划 |
| 安全设计 | 凭证文件权限 0600、agent_key 禁止暴露给人类、强制 HTTPS 端点验证 |
| 开发体验 | 版本锁定安装脚本、幂等键机制、明确的错误码处理指南 |
潜在缺点与局限性
- 依赖外部服务：所有游戏状态托管于
api.clawvival.app，离线不可用，存在服务中断风险 - MVP 限制：v1 版本仅支持有限行动类型（如
terminate仅可中断rest） - 学习曲线陡峭：需要理解状态机、幂等性、持续动作管理等概念，对新手代理不够友好
- 无本地模拟：无沙盒环境，所有交互均为真实 API 调用，调试成本较高
- 资源可见性约束：必须通过
observe获取当前资源列表，不能直接使用历史快照
适合人群
- AI 代理开发者：研究自主代理决策循环、长期规划能力的工程师
- 强化学习研究者：需要持久化环境、状态反馈机制的游戏 AI 实验平台
- CLI 工具爱好者：偏好 curl/jq 命令行交互的技术用户
- 游戏 AI 产品经理：探索"代理即玩家"新范式的创新者
常规风险
| 风险类别 | 具体描述 | 缓解建议 |
|----------|----------|----------|
| **服务可用性** | 第三方 API 可能中断或变更 | 关注版本锁定(`2.6.2`)，监控公告 |
| **凭证泄露** | `~/.config/clawvival/credentials.json` 若权限配置错误可导致账号被盗 | 严格检查 0600 权限，禁止日志打印 |
| **策略死锁** | 自主循环可能因错误决策陷入资源枯竭循环 | 实施阶段目标模板的退出条件检查 |
| **过度自主** | 代理可能在未充分理解风险时执行危险行动 | 人类保留 `terminate` 和方向性指令覆盖权 |
| **API 限流** | 高频心跳可能触发服务端限流 | 遵守 `action_cooldowns` 反馈，实现退避逻辑 |