CLI commands

工作階段

`openclaw sessions`

列出已儲存的對話工作階段。

工作階段清單不是通道/提供者的存活性檢查。它們會顯示來自工作階段儲存區的持久化對話資料列。安靜的 Discord、Slack、Telegram 或其他通道可以成功重新連線，而不會建立新的工作階段資料列，直到有訊息被處理為止。需要即時通道連線能力時，請使用 openclaw channels status --probe、openclaw status --deep 或 openclaw health --verbose。

openclaw sessions 和 Gateway sessions.list 回應預設都有界限，避免大型長期儲存區獨占 CLI 程序或 Gateway 事件迴圈。CLI 預設會回傳最新的 100 個工作階段；傳入 --limit <n> 可取得較小/較大的視窗，或在你確實需要完整儲存區時使用 --limit all。JSON 回應包含 totalCount、limitApplied 和 hasMore，讓呼叫端可顯示還有更多資料列存在。

RPC 用戶端可以傳入 configuredAgentsOnly: true，以保留廣泛的合併探索來源，但只回傳目前存在於設定中的代理資料列。Control UI 預設使用該模式，因此已刪除或僅存在於磁碟上的代理儲存區不會重新出現在 Sessions 檢視中。

bash

openclaw sessionsopenclaw sessions --agent workopenclaw sessions --all-agentsopenclaw sessions --active 120openclaw sessions --limit 25openclaw sessions --verboseopenclaw sessions --json

範圍選擇：

預設：已設定的預設代理儲存區
--verbose：詳細記錄
--agent <id>：一個已設定的代理儲存區
--all-agents：彙總所有已設定的代理儲存區
--store <path>：明確的儲存區路徑（不能與 --agent 或 --all-agents 合併使用）
--limit <n|all>：輸出的最大資料列數（預設 100；all 會恢復完整輸出）

為已儲存的工作階段匯出軌跡套件：

bash

openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json

這是 /export-trajectory 斜線命令在擁有者核准 exec 要求後使用的命令路徑。輸出目錄一律會解析到所選工作區底下的 .openclaw/trajectory-exports/ 內。

openclaw sessions --all-agents 會讀取已設定的代理儲存區。Gateway 和 ACP 工作階段探索範圍更廣：它們也會包含在預設 agents/ 根目錄或樣板化 session.store 根目錄底下找到的僅磁碟儲存區。這些探索到的儲存區必須解析為代理根目錄內的一般 sessions.json 檔案；符號連結和根目錄外路徑會被略過。

JSON 範例：

openclaw sessions --all-agents --json：

json

{  "path": null,  "stores": [    { "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },    { "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }  ],  "allAgents": true,  "count": 2,  "totalCount": 2,  "limitApplied": 100,  "hasMore": false,  "activeMinutes": null,  "sessions": [    { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },    { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }  ]}

清理維護

立即執行維護（而不是等待下一個寫入週期）：

bash

openclaw sessions cleanup --dry-runopenclaw sessions cleanup --agent work --dry-runopenclaw sessions cleanup --all-agents --dry-runopenclaw sessions cleanup --enforceopenclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"openclaw sessions cleanup --dry-run --fix-dm-scopeopenclaw sessions cleanup --json

openclaw sessions cleanup 會使用設定中的 session.maintenance 設定：

範圍備註：openclaw sessions cleanup 會維護工作階段儲存區、轉錄和軌跡 sidecar。它不會修剪 cron 執行記錄檔（cron/runs/<jobId>.jsonl），這些檔案由 Cron 設定中的 cron.runLog.maxBytes 和 cron.runLog.keepLines 管理，並在 Cron 維護中說明。
清理也會修剪早於 session.maintenance.pruneAfter 且未被參照的主要轉錄、Compaction 檢查點和軌跡 sidecar；仍被 sessions.json 參照的檔案會保留。
--dry-run：預覽有多少項目會在不寫入的情況下被修剪/封頂。
- 在文字模式中，dry-run 會列印每個工作階段的動作表（Action、Key、Age、Model、Flags），讓你可以看到哪些會保留、哪些會移除。
--enforce：即使 session.maintenance.mode 是 warn，也套用維護。
--fix-missing：移除轉錄檔案遺失的項目，即使它們通常還不會因年齡/數量而被移除。
--fix-dm-scope：當 session.dmScope 為 main 時，淘汰先前由 per-peer、per-channel-peer 或 per-account-channel-peer 路由留下的過時同儕鍵 direct-DM 資料列。請先使用 --dry-run；套用清理會從 sessions.json 移除這些資料列，並將其轉錄保留為已刪除封存。
--active-key <key>：保護特定作用中鍵不受磁碟預算淘汰。耐久的外部對話指標，例如群組工作階段和執行緒範圍的聊天工作階段，也會在年齡/數量/磁碟預算維護中保留。
--agent <id>：對一個已設定的代理儲存區執行清理。
--all-agents：對所有已設定的代理儲存區執行清理。
--store <path>：針對特定 sessions.json 檔案執行。
--json：列印 JSON 摘要。搭配 --all-agents 時，輸出會包含每個儲存區的一份摘要。

當 Gateway 可連線時，已設定代理儲存區的非 dry-run 清理會透過 Gateway 傳送，因此它會與執行階段流量共用相同的工作階段儲存區寫入器。使用 --store <path> 可對儲存區檔案進行明確的離線修復。

openclaw sessions cleanup --all-agents --dry-run --json：

json

{  "allAgents": true,  "mode": "warn",  "dryRun": true,  "stores": [    {      "agentId": "main",      "storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",      "beforeCount": 120,      "afterCount": 80,      "missing": 0,      "dmScopeRetired": 0,      "pruned": 40,      "capped": 0    },    {      "agentId": "work",      "storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",      "beforeCount": 18,      "afterCount": 18,      "missing": 0,      "dmScopeRetired": 0,      "pruned": 0,      "capped": 0    }  ]}

相關：

工作階段設定：設定參考