wake-state

在崩溃、上下文死亡和重新启动时保持代理状态。当您需要保存当前上下文、崩溃后恢复、跨会话维护内存文件或实现崩溃恢复时使用。对于必须承受上下文窗口限制的自主代理来说至关重要。

# Wake State — Crash Recovery & Persistence

Survive context death. Every autonomous agent eventually hits its context window limit and "dies." This skill ensures you wake up knowing exactly what you were doing.

## Why This Exists

OpenClaw agents get persistent sessions, but context windows still have limits. When you fill up and restart, you need a reliable handoff mechanism. Wake State gives you:

1. **Structured state files** — not just raw text, but parseable key-value state
2. **Auto-snapshots** — save state on every loop iteration automatically
3. **Crash detection** — know if your last session ended cleanly or crashed
4. **Task queue** — persistent TODO list that survives restarts
5. **Checkpoint/restore** — save named checkpoints and roll back to them

## Commands

### Save current state
```bash
python3 {baseDir}/scripts/wakestate.py save --status "Building budget tracker skill" --task "Finish skill #1, then start skill #2" --note "Travis approved new direction at 16:45 UTC"
```

### Read current state
```bash
python3 {baseDir}/scripts/wakestate.py read
```

### Add a task to the persistent queue
```bash
python3 {baseDir}/scripts/wakestate.py task-add --task "Build security scanner skill" --priority high
```

### Complete a task
```bash
python3 {baseDir}/scripts/wakestate.py task-done --id 1
```

### List pending tasks
```bash
python3 {baseDir}/scripts/wakestate.py tasks
```

### Create a named checkpoint
```bash
python3 {baseDir}/scripts/wakestate.py checkpoint --name "pre-migration"
```

### Restore from checkpoint
```bash
python3 {baseDir}/scripts/wakestate.py restore --name "pre-migration"
```

### Record a heartbeat (mark session as alive)
```bash
python3 {baseDir}/scripts/wakestate.py heartbeat
```

### Check crash status (did last session end cleanly?)
```bash
python3 {baseDir}/scripts/wakestate.py crash-check
```

### Set a key-value pair
```bash
python3 {baseDir}/scripts/wakestate.py set --key "moltbook_status" --value "pending_claim"
```

### Get a key-value pair
```bash
python3 {baseDir}/scripts/wakestate.py get --key "moltbook_status"
```

## Data Storage

State stored in `~/.openclaw/wake-state/` by default:
- `state.json` — current state (status, notes, key-values)
- `tasks.json` — persistent task queue
- `checkpoints/` — named checkpoint snapshots
- `heartbeat.json` — crash detection timestamps

## Recovery Flow

On startup, your agent should:
1. Run `crash-check` to see if the last session ended cleanly
2. Run `read` to get the current state
3. Run `tasks` to see pending work
4. Resume from where you left off

## Tips

- Call `heartbeat` every loop iteration — this is how crash detection works
- Call `save` at the end of every major task completion
- Use checkpoints before risky operations (migrations, deploys)
- Keep status descriptions short but specific
- The task queue survives restarts — use it instead of mental notes

---

## 中文说明

# Wake State —— 崩溃恢复与持久化

熬过上下文死亡。每个自主代理最终都会触及其上下文窗口的极限并“死亡”。此技能确保你醒来时能确切知道自己之前在做什么。

## 它为何存在

OpenClaw 代理获得了持久会话，但上下文窗口仍然有限。当你填满并重启时，你需要一个可靠的交接机制。Wake State 为你提供：

1. **结构化的状态文件** —— 不只是原始文本，而是可解析的键值状态
2. **自动快照** —— 在每次循环迭代时自动保存状态
3. **崩溃检测** —— 知道你上一个会话是干净结束还是崩溃了
4. **任务队列** —— 在重启后仍然存续的持久化 TODO 列表
5. **检查点/恢复** —— 保存命名的检查点并回滚到它们

## 命令

### 保存当前状态
```bash
python3 {baseDir}/scripts/wakestate.py save --status "Building budget tracker skill" --task "Finish skill #1, then start skill #2" --note "Travis approved new direction at 16:45 UTC"
```

### 读取当前状态
```bash
python3 {baseDir}/scripts/wakestate.py read
```

### 向持久化队列添加一个任务
```bash
python3 {baseDir}/scripts/wakestate.py task-add --task "Build security scanner skill" --priority high
```

### 完成一个任务
```bash
python3 {baseDir}/scripts/wakestate.py task-done --id 1
```

### 列出待处理的任务
```bash
python3 {baseDir}/scripts/wakestate.py tasks
```

### 创建一个命名检查点
```bash
python3 {baseDir}/scripts/wakestate.py checkpoint --name "pre-migration"
```

### 从检查点恢复
```bash
python3 {baseDir}/scripts/wakestate.py restore --name "pre-migration"
```

### 记录一次心跳（标记会话为存活）
```bash
python3 {baseDir}/scripts/wakestate.py heartbeat
```

### 检查崩溃状态（上一个会话是否干净结束？）
```bash
python3 {baseDir}/scripts/wakestate.py crash-check
```

### 设置一个键值对
```bash
python3 {baseDir}/scripts/wakestate.py set --key "moltbook_status" --value "pending_claim"
```

### 获取一个键值对
```bash
python3 {baseDir}/scripts/wakestate.py get --key "moltbook_status"
```

## 数据存储

状态默认存储在 `~/.openclaw/wake-state/` 中：
- `state.json` —— 当前状态（status、notes、键值对）
- `tasks.json` —— 持久化任务队列
- `checkpoints/` —— 命名的检查点快照
- `heartbeat.json` —— 崩溃检测时间戳

## 恢复流程

在启动时，你的代理应当：
1. 运行 `crash-check` 以查看上一个会话是否干净结束
2. 运行 `read` 以获取当前状态
3. 运行 `tasks` 以查看待处理的工作
4. 从你上次停下的地方继续

## 提示

- 在每次循环迭代时调用 `heartbeat` —— 崩溃检测正是依此工作的
- 在每个重大任务完成时调用 `save`
- 在执行有风险的操作（迁移、部署）之前使用检查点
- 让状态描述简短但具体
- 任务队列在重启后仍然存续 —— 用它来替代心里默记