如何使用ws-ckpt

ws-ckpt 是一個 AI Agent 工作區快照工具，為 AI Agent 提供毫秒級 checkpoint/rollback 能力。

Harness Agent 使用

1. 安裝

1.1 檢查是否安裝 ws-ckpt CLI 工具

ws-ckpt --version

如果沒有安裝，使用 yum 安裝

sudo yum install ws-ckpt

1.2 OpenClaw 安裝 ws-ckpt 外掛程式

執行下面命令安裝/卸載外掛程式：

# 安裝 openclaw 外掛程式
ws-ckpt plugin install --runtime openclaw
# 卸載 openclaw 外掛程式
ws-ckpt plugin uninstall --runtime openclaw

預設工作區路徑 `~/.openclaw/workspace`，建議使用預設工作區路徑，如需自訂，安裝外掛程式後自然語言告知 OpenClaw 或者修改設定檔 `~/.openclaw/ws-ckpt.json`：

"workspace": "/path/to/workspace"

重要

工作區路徑不可以是 Openclaw 啟動路徑或其父路徑
由於目前快照功能涉及檔案系統變更，將影響工作區內進程cwd，禁止設定工作區路徑為系統重要路徑，如主目錄，根目錄等

註：openclaw gateway 啟動路徑通常是主目錄，TUI 啟動路徑為 TUI 命令執行路徑

如需開啟自動快照功能，安裝外掛程式後用自然語言告知 OpenClaw 或者修改設定檔 `~/.openclaw/ws-ckpt.json`，外掛程式將在每輪會話結束時自動快照：

"autoCheckpoint": true

1.3 Hermes 安裝 ws-ckpt 外掛程式

執行下面命令安裝/卸載外掛程式：

# 安裝 hermes 外掛程式
ws-ckpt plugin install --runtime hermes
# 卸載 hermes 外掛程式
ws-ckpt plugin uninstall --runtime hermes

必須主動配置工作區路徑，安裝外掛程式後執行下面命令：

# 修改 config 檔案指定工作區
hermes config set plugins.ws-ckpt.workspace /path/to/workspace

重要

工作區路徑不可以是 Hermes 啟動路徑或其父路徑
由於目前快照功能涉及檔案系統變更，將影響工作區內進程cwd，禁止設定工作區路徑為系統重要路徑，如主目錄，根目錄等

註：hermes gateway 啟動路徑通常是 `~/.hermes/hermes-agent`，TUI 啟動路徑為 TUI 命令執行路徑

如需開啟自動快照功能，安裝外掛程式後執行下面命令，或用自然語言告知 Hermes，外掛程式將在每輪會話結束時自動快照：

# 修改 config 檔案開啟自動快照
hermes config set plugins.ws-ckpt.autoCheckpoint true

1.4 其他 Agent 可安裝ws-ckpt skill

本地安裝：

Skill 檔案路徑：/usr/share/anolisa/runtime/skills/ws-ckpt/SKILL.md
對 agent 說：“幫我安裝 /usr/share/anolisa/runtime/skills/ws-ckpt/SKILL.md 這個 skill”

Github 源安裝：

Skill 檔案 github 連結：https://github.com/alibaba/anolisa/blob/main/src/ws-ckpt/src/skills/ws-ckpt/SKILL.md
對 agent 說：“幫我安裝https://github.com/alibaba/anolisa/blob/main/src/ws-ckpt/src/skills/ws-ckpt/SKILL.md 這個 skill”

說明

Plugin 和 Skill 不可同時安裝，二者互斥。

Skill 有模型理解有誤風險，優先推薦使用Plugin

2. 自然語言使用

2.1 指定工作區目錄

# 使用者輸入
配置快照工作區目錄為/path/to/workspace

重要：openclaw 配置修改落盤將觸發 gateway 重啟，因此會話中僅修改記憶體，僅當前會話生效

2.2 建立快照

# 使用者輸入
建立一個快照，名字是test1，msg是測試快照

重要：必須給出名字，此後操作以名字標識快照，該名字需要具備唯一性

2.3 開啟每輪對話自動快照

開啟後，每輪對話後將自動建立快照。

# 使用者輸入
開啟每輪會話自動快照

說明

開啟自動快照時，建議不要手動打快照，這將影響快照版本鏈，打破回退n步與對話輪次一一對應的語義。

2.4 開啟定時快照

開啟後，會在規定時間自動建立快照。

定時任務的觸發時間用分、時、日、月、周五段運算式描述，能覆蓋絕大多數周期性和一次性定時需求，但做不到秒級定時、條件觸發（比如檔案變更後執行）、或者 A 完成後自動跑 B 這種鏈式調度。

# 使用者輸入
每天12點定時快照

2.5 查看快照

# 使用者輸入
列出所有快照

2.6 復原快照

# 使用者輸入
復原到快照test1

重要：必須給出名字，定位快照

2.7 刪除快照

# 使用者輸入
刪除快照test1

重要：必須給出名字，定位快照

2.8 開啟自動清理快照

# 使用者輸入
開啟自動清理快照，僅保留最近7天的快照

說明

自動清理預設僅當前工作區生效，如果需要伺服器上所有 workspace 都會基於該配置進行自動清理請顯式要求全域自動清理。

CLI 使用

1. 建立快照

ws-ckpt checkpoint -w <workspace> [-s <snapshot id>] [-m <message>] [--metadata <json>]

參數	簡寫	必填	說明
`--workspace`	`-w`	是	工作區路徑或 ID
`--snapshot`	`-s`	否	快照id 唯一標識快照，未填寫將自動產生一個id
`--message`	`-m`	否	快照描述資訊
`--metadata`		否	JSON 格式的附加中繼資料

樣本：

# 基本用法
ws-ckpt checkpoint -w ./my-project -s test

# 帶message
ws-ckpt checkpoint -w ./my-project -s test -m "initial state"

# 帶中繼資料
ws-ckpt checkpoint -w ws-6d5aaa -s test --metadata '{"tool":"write","file":"main.py"}'

2. 復原到指定快照

ws-ckpt rollback -w <workspace> -s <snapshot> [--preview]

--snapshot簡寫 -s 接受快照 ID（如 test）

--workspace簡寫 -w，工作區路徑或 ID

參數	簡寫	必填	說明
`--snapshot`	`-s`	否	快照id 唯一標識快照，和`-n`互斥，但至少有一個
`--num-ancestors`	`-n`	否	沿 parent 鏈回退 N 個祖先，`-s`互斥，但至少有一個
`--workspace`	`-w`	是	工作區路徑或 ID
`--preview`		否	展示將復原的 target 快照與目前的目錄的差異，不會修改工作區

樣本：

# 按快照 ID 復原
ws-ckpt rollback -w ./my-project -s test
# 復原到 3 個快照前
ws-ckpt rollback -w <workspace> -n 3
# 查看 test 和目前的目錄的差異
ws-ckpt rollback -w ./my-project -s test --preview

3. 列出快照

ws-ckpt list [-w <workspace>] [--format <table|json>]

參數	簡寫	必填	說明
`--workspace`	`-w`	否	省略 `-w` 時列出所有工作區的快照。
`--format`		否	輸出格式，table 或 json

樣本：

# 列出所有工作區的快照
ws-ckpt list

# 列出指定工作區
ws-ckpt list -w ./my-project

# JSON 格式輸出
ws-ckpt list -w workspace-6d5aaa --format json

4. 查看快照間差異

ws-ckpt diff -w <workspace> -f <snapshot> [-t <snapshot>]

參數	簡寫	必填	說明
`--workspace`	`-w`	是	工作區路徑或 ID。
`--from`	`-f`	是	起始快照 ID
`--to`	`-t`	否	目標快照 ID；省略時與當前工作區比較

樣本：

# 列出所有工作區的快照
ws-ckpt list

# 列出指定工作區
ws-ckpt list -w ./my-project

# JSON 格式輸出
ws-ckpt list -w workspace-6d5aaa --format json

5. 刪除指定快照

ws-ckpt delete [-w <workspace>] -s <snapshot> [--force]

參數	簡寫	必填	說明
`--snapshot`	`-s`	是	快照id 唯一標識快照
`--workspace`	`-w`	否	工作區路徑或 ID，如果 snapshot id 全域唯一無需 `-w`參數，如果跨工作區id重複必須指定工作區

樣本：

# 刪除單個快照
ws-ckpt delete -w ./my-project -s test

# 按快照 ID 全域刪除（無需 -w，若 ID 全域唯一）
ws-ckpt delete -s test

6. 查看狀態

ws-ckpt status [-w <workspace>] [--format <table|json>]

參數	簡寫	必填	說明
`--workspace`	`-w`	否	省略 `-w` 時顯示全域狀態
`--format`		否	輸出格式，table 或 json

樣本：

# 全域狀態
ws-ckpt status

# 指定工作區
ws-ckpt status -w ./my-project

7. 配置自動快照清理

ws-ckpt config 
      [-g | -w <workspace>]
      [--enable-auto-cleanup]
      [--disable-auto-cleanup]
      [--auto-cleanup-keep] <AUTO_CLEANUP_KEEP>
      [--auto-cleanup-interval] <AUTO_CLEANUP_INTERVAL>

參數	簡寫	必填	說明
`--global`	`-g`	否	指定修改/查看全域配置
`--workspace`	`-w`	否	指定修改/查看特定工作區配置
`--enable-auto-cleanup`		否	開啟自動快照清理
`--disable-auto-cleanup`		否	禁用自動快照清理
`--auto-cleanup-keep`		否	設定清理保留時間：整數（計數模式，0表示禁用）或到期時間，如“30d”（時效模式，單位為秒/分鐘/小時/天/周）
`--auto-cleanup-interval`		否	設定自動清理間隔（以秒為單位）（0表示禁用調度迴圈）

說明

自動清理分為全域配置和局部配置，局部配置覆蓋全域配置

樣本：

# 查看配置
# 查看 summary
ws-ckpt config
# 查看全域配置
ws-ckpt config -g
# 查看特定工作區配置
ws-ckpt config -w ~/proj

# 修改配置
# === 全域 ===
# 開啟快照自動清理，保留最近10個快照
ws-ckpt config -g --enable-auto-cleanup --auto-cleanup-keep 10
# 開啟快照自動清理，保留7天內的快照
ws-ckpt config -g --enable-auto-cleanup --auto-cleanup-keep 7d
# 禁用快照自動清理
ws-ckpt config -g --disable-auto-cleanup

# === 局部(per-workspace 覆蓋) ===
# 開啟快照自動清理，保留最近10個快照
ws-ckpt config -w ~/proj --enable-auto-cleanup --auto-cleanup-keep 10
# 開啟快照自動清理，保留7天內的快照
ws-ckpt config -w ~/proj --enable-auto-cleanup --auto-cleanup-keep 7d
# 禁用快照自動清理
ws-ckpt config -w ~/proj --disable-auto-cleanup