Gỡ lỗi

Các trợ giúp gỡ lỗi cho đầu ra truyền trực tuyến, đặc biệt khi một nhà cung cấp trộn phần suy luận vào văn bản thông thường.

Ghi đè gỡ lỗi lúc chạy

Dùng /debug trong chat để đặt các ghi đè cấu hình chỉ lúc chạy (bộ nhớ, không phải đĩa). /debug bị tắt theo mặc định; bật bằng commands.debug: true. Điều này hữu ích khi bạn cần bật/tắt các thiết lập ít gặp mà không chỉnh sửa openclaw.json.

Ví dụ:

/debug show/debug set messages.responsePrefix="[openclaw]"/debug unset messages.responsePrefix/debug reset

/debug reset xóa mọi ghi đè và trở về cấu hình trên đĩa.

Đầu ra truy vết phiên

Dùng /trace khi bạn muốn xem các dòng truy vết/gỡ lỗi do plugin sở hữu trong một phiên mà không bật toàn bộ chế độ chi tiết.

Ví dụ:

/trace/trace on/trace off

Dùng /trace cho chẩn đoán plugin, chẳng hạn như tóm tắt gỡ lỗi Active Memory. Tiếp tục dùng /verbose cho đầu ra trạng thái/công cụ chi tiết thông thường, và tiếp tục dùng /debug cho các ghi đè cấu hình chỉ lúc chạy.

Truy vết vòng đời Plugin

Dùng OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 khi các lệnh vòng đời plugin có vẻ chậm và bạn cần phân rã pha tích hợp sẵn cho siêu dữ liệu plugin, khám phá, registry, bản sao runtime, đột biến cấu hình và công việc làm mới. Truy vết là tùy chọn bật và ghi vào stderr, nên đầu ra lệnh JSON vẫn có thể phân tích được.

Ví dụ:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

Đầu ra ví dụ:

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

Dùng tính năng này để điều tra vòng đời plugin trước khi dùng trình phân tích CPU. Nếu lệnh đang chạy từ một bản checkout mã nguồn, ưu tiên đo runtime đã build bằng node dist/entry.js ... sau pnpm build; pnpm openclaw ... cũng đo phần chi phí của trình chạy mã nguồn.

Khởi động CLI và profiling lệnh

Dùng benchmark khởi động đã được đưa vào repo khi một lệnh có vẻ chậm:

pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

Để profiling một lần qua trình chạy mã nguồn thông thường, đặt OPENCLAW_RUN_NODE_CPU_PROF_DIR:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

Trình chạy mã nguồn thêm các cờ Node CPU profile và ghi một .cpuprofile cho lệnh. Dùng cách này trước khi thêm instrumentation tạm thời vào mã lệnh.

Với các điểm nghẽn khởi động trông giống công việc hệ thống tệp đồng bộ hoặc trình nạp mô-đun, thêm cờ truy vết I/O đồng bộ của Node qua trình chạy mã nguồn:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch để cờ này tắt theo mặc định cho tiến trình con Gateway được theo dõi. Đặt OPENCLAW_TRACE_SYNC_IO=1 khi bạn chủ động muốn đầu ra truy vết I/O đồng bộ của Node trong chế độ watch.

Chế độ watch của Gateway

Để lặp nhanh, chạy gateway dưới trình theo dõi tệp:

pnpm gateway:watch

Theo mặc định, lệnh này bắt đầu hoặc khởi động lại một phiên tmux tên là openclaw-gateway-watch-main (hoặc một biến thể theo profile/cổng như openclaw-gateway-watch-dev-19001) và tự động attach từ terminal tương tác. Shell không tương tác, CI và các lệnh exec của agent vẫn detached và in hướng dẫn attach thay vào đó. Attach thủ công khi cần:

tmux attach -t openclaw-gateway-watch-main

Pane tmux chạy trình watch thô:

node scripts/watch-node.mjs gateway --force

Dùng chế độ foreground khi không muốn dùng tmux:

pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Tắt tự động attach trong khi vẫn giữ quản lý tmux:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Profile thời gian CPU của Gateway được theo dõi khi gỡ lỗi các điểm nóng khởi động/runtime:

pnpm gateway:watch --benchmark

Wrapper watch tiêu thụ --benchmark trước khi gọi Gateway và ghi một V8 .cpuprofile cho mỗi lần tiến trình con Gateway thoát dưới .artifacts/gateway-watch-profiles/. Dừng hoặc khởi động lại gateway đang được theo dõi để flush profile hiện tại, rồi mở nó bằng Chrome DevTools hoặc Speedscope:

npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile

Dùng --benchmark-dir <path> khi bạn muốn profile ở nơi khác. Dùng --benchmark-no-force khi bạn muốn tiến trình con được benchmark bỏ qua bước dọn cổng --force mặc định và thất bại nhanh nếu cổng Gateway đã được dùng. Chế độ benchmark mặc định chặn spam truy vết sync-I/O. Đặt OPENCLAW_TRACE_SYNC_IO=1 cùng với --benchmark khi bạn chủ động muốn cả CPU profile và stack trace sync-I/O của Node. Trong chế độ benchmark, các khối truy vết đó được ghi vào gateway-watch-output.log dưới thư mục benchmark và được lọc khỏi pane terminal; log Gateway thông thường vẫn hiển thị.

Wrapper tmux mang các bộ chọn runtime phổ biến không phải bí mật như OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT, và OPENCLAW_SKIP_CHANNELS vào pane. Đặt thông tin xác thực nhà cung cấp trong profile/cấu hình thông thường của bạn, hoặc dùng chế độ foreground thô cho các bí mật tạm thời một lần. Nếu Gateway đang được theo dõi thoát trong lúc khởi động, watcher chạy openclaw doctor --fix --non-interactive một lần và khởi động lại tiến trình con Gateway. Dùng OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 khi bạn muốn lỗi khởi động ban đầu mà không có lượt sửa chữa chỉ dành cho dev. Pane tmux được quản lý cũng mặc định dùng log Gateway có màu để dễ đọc; đặt FORCE_COLOR=0 khi bắt đầu pnpm gateway:watch để tắt đầu ra ANSI.

Watcher khởi động lại khi có các tệp liên quan đến build dưới src/, tệp nguồn extension, siêu dữ liệu package.json và openclaw.plugin.json của extension, tsconfig.json, package.json, và tsdown.config.ts. Thay đổi siêu dữ liệu extension khởi động lại gateway mà không ép rebuild tsdown; thay đổi nguồn và cấu hình vẫn rebuild dist trước.

Thêm bất kỳ cờ CLI gateway nào sau gateway:watch và chúng sẽ được truyền qua trong mỗi lần khởi động lại. Chạy lại cùng lệnh watch sẽ respawn pane tmux đã đặt tên, và trình watch thô vẫn giữ khóa single-watcher để các tiến trình cha watcher trùng lặp được thay thế thay vì chất chồng.

Profile dev + gateway dev (--dev)

Dùng profile dev để cô lập trạng thái và khởi tạo một thiết lập an toàn, dùng xong bỏ được để gỡ lỗi. Có hai cờ --dev:

• --dev toàn cục (profile): cô lập trạng thái dưới ~/.openclaw-dev và đặt mặc định cổng gateway thành 19001 (các cổng dẫn xuất dịch chuyển theo).
• gateway --dev: yêu cầu Gateway tự tạo cấu hình + workspace mặc định khi thiếu (và bỏ qua BOOTSTRAP.md).

Luồng khuyến nghị (profile dev + bootstrap dev):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

Nếu bạn chưa có bản cài toàn cục, chạy CLI qua pnpm openclaw ....

Việc này thực hiện:

1. Cô lập profile (--dev toàn cục)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (trình duyệt/canvas dịch chuyển tương ứng)

2. Bootstrap dev (gateway --dev)

   • Ghi cấu hình tối thiểu nếu thiếu (gateway.mode=local, bind loopback).
   • Đặt agent.workspace thành workspace dev.
   • Đặt agent.skipBootstrap=true (không có BOOTSTRAP.md).
   • Seed các tệp workspace nếu thiếu: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • Danh tính mặc định: C3-PO (droid giao thức).
   • Bỏ qua các nhà cung cấp kênh trong chế độ dev (OPENCLAW_SKIP_CHANNELS=1).

Luồng đặt lại (khởi đầu mới):

pnpm gateway:dev:reset

--reset xóa cấu hình, thông tin xác thực, phiên và workspace dev (dùng trash, không phải rm), rồi tạo lại thiết lập dev mặc định.

Ghi log luồng thô (OpenClaw)

OpenClaw có thể ghi log luồng assistant thô trước mọi bước lọc/định dạng. Đây là cách tốt nhất để xem liệu phần suy luận đang đến dưới dạng các delta văn bản thuần (hay dưới dạng các khối suy nghĩ riêng).

Bật qua CLI:

pnpm gateway:watch --raw-stream

Ghi đè đường dẫn tùy chọn:

pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

Các biến môi trường tương đương:

OPENCLAW_RAW_STREAM=1OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

Tệp mặc định:

~/.openclaw/logs/raw-stream.jsonl

Ghi log chunk OpenAI-compatible thô

Để chụp chunk OpenAI-compat thô trước khi chúng được phân tích thành các khối, bật transport logger:

OPENCLAW_RAW_STREAM=1

Đường dẫn tùy chọn:

OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl

Tệp mặc định:

~/.openclaw/logs/raw-openai-completions.jsonl

Ghi chú an toàn

• Log luồng thô có thể bao gồm toàn bộ prompt, đầu ra công cụ và dữ liệu người dùng.
• Giữ log cục bộ và xóa chúng sau khi gỡ lỗi.
• Nếu bạn chia sẻ log, hãy loại bỏ bí mật và PII trước.

Gỡ lỗi trong VSCode

Source map là bắt buộc để bật gỡ lỗi trong các IDE dựa trên VSCode vì nhiều tệp được tạo cuối cùng có tên băm như một phần của quá trình build. Các cấu hình launch.json đi kèm nhắm đến dịch vụ Gateway, nhưng có thể được điều chỉnh nhanh cho các mục đích khác:

1. Rebuild and Debug Gateway - Gỡ lỗi dịch vụ Gateway sau khi tạo một bản build mới
2. Debug Gateway - Gỡ lỗi dịch vụ Gateway của một bản build đã có sẵn

Thiết lập

Cấu hình Rebuild and Debug Gateway mặc định có sẵn mọi thứ cần thiết, nó sẽ tự động xóa thư mục /dist và rebuild dự án với gỡ lỗi được bật:

1. Mở panel Chạy và gỡ lỗi từ Thanh hoạt động hoặc nhấn Ctrl+Shift+D
2. Trong IDE, bảo đảm Rebuild and Debug Gateway được chọn trong menu thả xuống cấu hình rồi nhấn nút Bắt đầu gỡ lỗi

Ngoài ra - nếu bạn muốn tự quản lý các quy trình build và gỡ lỗi:

1. Mở terminal và bật source map:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. Trong cùng terminal, rebuild dự án: pnpm clean:dist && pnpm build
3. Trong IDE, chọn tùy chọn Debug Gateway trong menu thả xuống cấu hình Chạy và gỡ lỗi rồi nhấn nút Bắt đầu gỡ lỗi

Bây giờ bạn có thể đặt breakpoint trong các tệp nguồn TypeScript của mình (thư mục src/) và trình gỡ lỗi sẽ ánh xạ đúng breakpoint sang JavaScript đã biên dịch thông qua source map. Bạn sẽ có thể kiểm tra biến, đi từng bước qua mã và xem call stack như mong đợi.

Ghi chú

• Nếu dùng tùy chọn "Rebuild and Debug Gateway" - mỗi lần trình gỡ lỗi được khởi chạy, nó sẽ xóa hoàn toàn thư mục /dist và chạy đầy đủ pnpm build với source map được bật trước khi bắt đầu Gateway
• Nếu dùng tùy chọn "Debug Gateway" - các phiên gỡ lỗi có thể được bắt đầu và dừng bất kỳ lúc nào mà không ảnh hưởng đến thư mục /dist, nhưng bạn phải dùng một tiến trình terminal riêng để vừa bật gỡ lỗi vừa quản lý chu kỳ build
• Sửa các thiết lập launch.json cho args để gỡ lỗi các phần khác của dự án
• Nếu bạn cần dùng OpenClaw CLI đã build cho các tác vụ khác (ví dụ dashboard --no-open nếu phiên gỡ lỗi của bạn sinh một token xác thực mới), bạn có thể thực thi nó trong terminal khác bằng node ./openclaw.mjs hoặc tạo một alias shell như alias openclaw-build="node $(pwd)/openclaw.mjs"

Liên quan

• Khắc phục sự cố
• Câu hỏi thường gặp