OpenClaw Pi 開發指南：測試、除錯與環境重置流程

每次在開發複雜的整合功能時，最怕的就是環境亂掉或是測試跑不起來。如果你正在處理 OpenClaw 裡的 Pi 整合，這份指南會幫你整理出一套順手的開發流程，讓你不用在混亂的指令中迷失。

這套流程能確保你的程式碼品質，並讓你在開發過程中可以快速驗證功能是否正常運作。

型別檢查與 Linting

在開發過程中，保持程式碼整潔是非常重要的。你可以透過以下指令來進行檢查：

• 型別檢查與編譯：pnpm build
• Lint 檢查：pnpm lint
• 格式檢查：pnpm format
• 推送到遠端前的完整檢查：pnpm lint && pnpm build && pnpm test

執行 Pi 測試

如果你想針對 Pi 相關的功能進行測試，可以直接使用 Vitest 執行特定的測試集：

pnpm test -- \
  "src/agents/pi-*.test.ts" \
  "src/agents/pi-embedded-*.test.ts" \
  "src/agents/pi-tools*.test.ts" \
  "src/agents/pi-settings.test.ts" \
  "src/agents/pi-tool-definition-adapter*.test.ts" \
  "src/agents/pi-hooks/**/*.test.ts"

如果你需要包含真實環境的 Provider 測試：

OPENCLAW_LIVE_TEST=1 pnpm test -- src/agents/pi-embedded-runner-extraparams.live.test.ts

這會涵蓋主要的 Pi 單元測試套件：

• src/agents/pi-*.test.ts
• src/agents/pi-embedded-*.test.ts
• src/agents/pi-tools*.test.ts
• src/agents/pi-settings.test.ts
• src/agents/pi-tool-definition-adapter.test.ts
• src/agents/pi-hooks/*.test.ts

手動測試

我推薦的測試流程如下：

• 以開發模式啟動 Gateway：
  • pnpm gateway:dev
• 直接觸發 Agent：
  • pnpm openclaw agent --message "Hello" --thinking low
• 使用 TUI 進行互動式除錯：
  • pnpm tui

針對 Tool Call 的行為，你可以嘗試要求執行 read 或 exec 動作，這樣你就能觀察 Tool 的串流輸出（streaming）以及 Payload 的處理狀況。

重置環境

OpenClaw 的狀態資料儲存在狀態目錄中。預設路徑是 ~/.openclaw。如果你有設定 OPENCLAW_STATE_DIR 環境變數，請改用該目錄。

如果你想徹底重置所有內容，請注意以下檔案：

• openclaw.json：設定檔
• credentials/：身分驗證設定檔與 Token
• agents/<agentId>/sessions/：Agent 的對話歷史紀錄
• agents/<agentId>/sessions.json：對話索引
• sessions/：如果存在舊版路徑
• workspace/：如果你想要一個乾淨的工作區

如果你只想重置對話紀錄，只需要刪除該 Agent 的 agents/<agentId>/sessions/ 和 agents/<agentId>/sessions.json 即可。如果你不想重新進行身分驗證，請保留 credentials/ 資料夾。

參考資料

• Testing
• Getting Started

下一步

• 了解如何設定 Testing 環境
• 回到 Getting Started 查看基礎教學

有任何設定上的問題嗎？可以詢問我們的 AI Setup Assistant。