跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.jsonOpenClaw 版本、作業系統/執行階段、模型、設定快照、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 超過了 匯出安全限制。請開始新的工作階段，或匯出較小的重現案例。

​
相關