English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Tools

軌跡套件

Trajectory capture 是 OpenClaw 針對每個工作階段的飛行記錄器。它會為每次代理程式執行記錄結構化時間軸，然後 /export-trajectory 會將目前工作階段封裝成已遮蔽敏感資訊的支援套件。

當你需要回答以下問題時使用它：

  • 哪些提示、系統提示與工具已傳送給模型？
  • 哪些逐字稿訊息與工具呼叫導致了這個答案？
  • 這次執行是否逾時、中止、進行 Compaction，或遇到供應商錯誤？
  • 哪個模型、plugins、Skills 與執行階段設定處於啟用狀態？
  • 供應商傳回了哪些用量與提示快取中繼資料？

如果你要針對即時 Gateway 問題提交廣泛的支援報告，請從 /diagnostics 開始。Diagnostics 會收集 已清理的 Gateway 套件，而且對於 OpenAI Codex harness 工作階段，在核准後也可以將 Codex 回饋傳送到 OpenAI 伺服器。當你特別需要詳細的每個工作階段提示、工具與逐字稿 時間軸時，請使用 /export-trajectory。

快速開始

在作用中的工作階段傳送：

/export-trajectory

別名：

/trajectory

OpenClaw 會將套件寫入工作區底下：

.openclaw/trajectory-exports/openclaw-trajectory-<session>-<timestamp>/

你可以選擇相對輸出目錄名稱：

/export-trajectory bug-1234

自訂路徑會在 .openclaw/trajectory-exports/ 內解析。絕對 路徑與 ~ 路徑會被拒絕。

Trajectory 套件可能包含提示、模型訊息、工具結構描述、工具 結果、執行階段事件與本機路徑。因此聊天斜線指令每次都會 經過 exec 核准。當你打算建立套件時，核准該匯出一次；不要使用 allow-all。在群組聊天中，OpenClaw 會將 核准提示與匯出結果私下傳送給擁有者，而不是將 Trajectory 詳細資訊貼回共享聊天室。

對於本機檢查或支援工作流程，你也可以直接執行已核准的指令 路徑：

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

存取權限

Trajectory export 是擁有者指令。傳送者必須通過該頻道的正常指令 授權檢查與擁有者檢查。

會記錄的內容

OpenClaw 代理程式執行預設會啟用 Trajectory capture。

執行階段事件包含：

  • session.started
  • trace.metadata
  • context.compiled
  • prompt.submitted
  • model.fallback_step，包含來源模型、下一個模型、失敗原因/詳細資訊、鏈中位置，以及 fallback 是否推進、成功或耗盡鏈
  • model.completed
  • trace.artifacts
  • session.ended

逐字稿事件也會從作用中的工作階段分支重建：

  • 使用者訊息
  • 助理訊息
  • 工具呼叫
  • 工具結果
  • Compaction
  • 模型變更
  • 標籤與自訂工作階段項目

事件會以 JSON Lines 寫入，並帶有此結構描述標記：

{
  "traceSchema": "openclaw-trajectory",
  "schemaVersion": 1
}

套件檔案

匯出的套件可以包含：

檔案 內容
manifest.json 套件結構描述、來源檔案、事件計數與產生的檔案清單
events.jsonl 已排序的執行階段與逐字稿時間軸
session-branch.json 已遮蔽敏感資訊的作用中逐字稿分支與工作階段標頭
metadata.json OpenClaw 版本、作業系統/執行階段、模型、設定快照、plugins、Skills 與提示中繼資料
artifacts.json 最終狀態、錯誤、用量、提示快取、Compaction 計數、助理文字與工具中繼資料
prompts.json 已提交的提示與選定的提示建構詳細資訊
system-prompt.txt 最新編譯的系統提示（若已擷取）
tools.json 傳送給模型的工具定義（若已擷取）

manifest.json 會列出該套件中存在的檔案。有些檔案會在 工作階段未擷取對應的執行階段資料時省略。

擷取位置

預設情況下，執行階段 Trajectory 事件會寫在工作階段檔案旁邊：

<session>.trajectory.jsonl

OpenClaw 也會在工作階段旁邊寫入一個盡力而為的指標檔案：

<session>.trajectory-path.json

設定 OPENCLAW_TRAJECTORY_DIR，即可將執行階段 Trajectory sidecar 儲存在 專用目錄中：

export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories

設定此變數時，OpenClaw 會針對該目錄中的每個工作階段 ID 寫入一個 JSONL 檔案。

工作階段維護會在其擁有的工作階段項目因工作階段磁碟預算而被 剪除、封頂或逐出時，移除 Trajectory sidecar。只有當指標目標仍能證明它 屬於該工作階段時，才會移除工作階段目錄外的執行階段檔案。

停用擷取

在啟動 OpenClaw 前設定 OPENCLAW_TRAJECTORY=0：

export OPENCLAW_TRAJECTORY=0

這會停用執行階段 Trajectory capture。/export-trajectory 仍然可以匯出 逐字稿分支，但僅限執行階段的檔案，例如已編譯的內容、 供應商成品與提示中繼資料，可能會遺失。

隱私與限制

Trajectory 套件是為支援與偵錯而設計，不適合公開張貼。 OpenClaw 會在寫入匯出檔案前遮蔽敏感值：

  • 憑證與已知類似秘密的承載欄位
  • 圖像資料
  • 本機狀態路徑
  • 工作區路徑，會取代為 $WORKSPACE_DIR
  • 主目錄路徑（偵測到時）

匯出工具也會限制輸入大小：

  • 執行階段 sidecar 檔案：即時擷取會在 10 MiB 停止，並在仍有空間時記錄截斷事件；匯出會接受最多 50 MiB 的既有執行階段 sidecar
  • 工作階段檔案：50 MiB
  • 執行階段事件：200,000
  • 匯出事件總數：250,000
  • 個別執行階段事件行超過 256 KiB 時會被截斷

在團隊外分享套件前，請先檢閱。遮蔽敏感資訊是盡力而為， 無法知道每一種應用程式特定的秘密。

疑難排解

如果匯出沒有執行階段事件：

  • 確認 OpenClaw 啟動時未設定 OPENCLAW_TRAJECTORY=0
  • 檢查 OPENCLAW_TRAJECTORY_DIR 是否指向可寫入的目錄
  • 在工作階段中再執行一則訊息，然後重新匯出
  • 檢查 manifest.json 中的 runtimeEventCount

如果指令拒絕輸出路徑：

  • 使用像 bug-1234 這樣的相對名稱
  • 不要傳入 /tmp/... 或 ~/...
  • 將匯出保持在 .openclaw/trajectory-exports/ 內

如果匯出因大小錯誤而失敗，代表工作階段或 sidecar 超過了 匯出安全限制。請開始新的工作階段，或匯出較小的重現案例。

相關