Chuyển đến nội dung chính

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.

Trình trợ giúp gỡ lỗi cho đầu ra phát 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 runtime

Sử dụng /debug trong trò chuyện để đặt ghi đè cấu hình chỉ runtime (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 cài đặt khó thấy 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 tất cả ghi đè và quay lại cấu hình trên đĩa.

​
Đầu ra dấu vết phiên

Sử dụng /trace khi bạn muốn xem các dòng dấu 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
Sử dụng /trace cho chẩn đoán Plugin 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 ghi đè cấu hình chỉ runtime.

​
Dấu vết vòng đời Plugin

Sử 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 phân tích pha tích hợp sẵn cho siêu dữ liệu Plugin, khám phá, sổ đăng ký, bản sao runtime, đột biến cấu hình và công việc làm mới. Dấu 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"
Sử dụng mục này để điều tra vòng đời Plugin trước khi dùng đến bộ định hình CPU. Nếu lệnh đang chạy 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 cả chi phí của trình chạy mã nguồn.

​
Khởi động CLI và định hình lệnh

Sử dụng benchmark khởi động đã được đưa vào repo khi một lệnh có vẻ chậm: 
pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
Để định hình 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ờ hồ sơ CPU của Node và ghi một .cpuprofile cho lệnh. Sử dụng cách này trước khi thêm công cụ đo tạm thời vào mã lệnh. Đối với các lần khởi động bị kẹt trông giống công việc hệ thống tệp đồng bộ hoặc bộ nạp module, thêm cờ dấu 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 muốn rõ ràng đầu ra dấu 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, thao tác này khởi động 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 hồ sơ/cổng cụ thể như openclaw-gateway-watch-dev-19001) và tự động gắn vào từ các terminal tương tác. Shell không tương tác, CI và các lệnh exec của agent vẫn tách rời và in hướng dẫn gắn vào thay thế. Gắn vào thủ công khi cần: 
tmux attach -t openclaw-gateway-watch-main
Ô tmux chạy trình theo dõi thô: 
node scripts/watch-node.mjs gateway --force
Sử dụng chế độ foreground khi không muốn dùng tmux: 
pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
Tắt tự động gắn vào nhưng vẫn giữ quản lý tmux: 
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
Định hình 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 .cpuprofile V8 cho mỗi lần thoát của tiến trình con Gateway dưới .artifacts/gateway-watch-profiles/. Dừng hoặc khởi động lại gateway được theo dõi để xả hồ sơ hiện tại, rồi mở bằng Chrome DevTools hoặc Speedscope: 
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
Sử dụng --benchmark-dir <path> khi bạn muốn hồ sơ ở nơi khác. Sử dụng --benchmark-no-force khi bạn muốn tiến trình con được benchmark bỏ qua dọn dẹp cổng --force mặc định và thất bại nhanh nếu cổng Gateway đã được sử dụng. Chế độ benchmark mặc định chặn spam dấu vết sync-I/O. Đặt OPENCLAW_TRACE_SYNC_IO=1 cùng với --benchmark khi bạn muốn rõ ràng cả hồ sơ CPU và stack trace sync-I/O của Node. Trong chế độ benchmark, các khối dấu vết đó được ghi vào gateway-watch-output.log dưới thư mục benchmark và được lọc khỏi ô terminal; nhật ký Gateway thông thường vẫn hiển thị. Wrapper tmux mang các bộ chọn runtime không bí mật phổ biến như OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT, và OPENCLAW_SKIP_CHANNELS vào ô. Đặt thông tin xác thực nhà cung cấp trong hồ sơ/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 dùng một lần. Nếu Gateway được theo dõi thoát trong lúc khởi động, trình theo dõi chạy openclaw doctor --fix --non-interactive một lần và khởi động lại tiến trình con Gateway. Sử 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. Ô tmux được quản lý cũng mặc định dùng nhật ký Gateway có màu để dễ đọc; đặt FORCE_COLOR=0 khi khởi động pnpm gateway:watch để tắt đầu ra ANSI. Trình theo dõi 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 build lại tsdown; thay đổi nguồn và cấu hình vẫn build lại 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ẽ sinh lại ô tmux đã đặt tên, và trình theo dõi thô vẫn giữ khóa một-trình-theo-dõi để các tiến trình cha theo dõi trùng lặp được thay thế thay vì chồng chất.

​
Hồ sơ dev + gateway dev (—dev)

Sử dụng hồ sơ dev để cô lập trạng thái và dựng một thiết lập an toàn, có thể bỏ đi cho gỡ lỗi. Có hai cờ --dev:
  • --dev toàn cục (hồ sơ): cô lập trạng thái dưới ~/.openclaw-dev và mặc định cổng gateway thành 19001 (các cổng suy ra dịch chuyển theo).
  • gateway --dev: yêu cầu Gateway tự tạo cấu hình mặc định + workspace khi thiếu (và bỏ qua BOOTSTRAP.md).
Luồng khuyến nghị (hồ sơ dev + bootstrap dev): 
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
Nếu bạn chưa có bản cài đặt toàn cục, chạy CLI qua pnpm openclaw .... Việc này làm gì:
  1. Cô lập hồ sơ (--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 một 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).
    • Tạo sẵn 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
--dev là một cờ hồ sơ toàn cục và bị một số trình chạy nuốt mất. Nếu bạn cần viết rõ, dùng dạng biến môi trường:
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
--reset xóa sạch 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.
Nếu một gateway không phải dev đang chạy (launchd hoặc systemd), dừng nó trước:
openclaw gateway stop

​
Ghi nhật ký stream thô (OpenClaw)

OpenClaw có thể ghi nhật ký stream trợ lý 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 có đang đến dưới dạng delta văn bản thuần (hay dưới dạng các khối suy nghĩ riêng biệt) hay khô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
Biến môi trường tương đương: 
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
Tệp mặc định: ~/.openclaw/logs/raw-stream.jsonl

​
Ghi nhật ký chunk thô (pi-mono)

Để thu thập chunk tương thích OpenAI thô trước khi chúng được phân tích thành khối, pi-mono cung cấp một logger riêng: 
PI_RAW_STREAM=1
Đường dẫn tùy chọn: 
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
Tệp mặc định: ~/.pi-mono/logs/raw-openai-completions.jsonl
Lưu ý: mục này chỉ được phát ra bởi các tiến trình sử dụng nhà cung cấp openai-completions của pi-mono.

​
Ghi chú an toàn

  • Nhật ký stream thô có thể bao gồm toàn bộ prompt, đầu ra công cụ và dữ liệu người dùng.
  • Giữ nhật ký cục bộ và xóa chúng sau khi gỡ lỗi.
  • Nếu bạn chia sẻ nhật ký, 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 ra 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 tới dịch vụ Gateway, nhưng có thể được điều chỉnh nhanh cho các mục đích khác:
  1. Build lại và gỡ lỗi Gateway - Gỡ lỗi dịch vụ Gateway sau khi tạo build mới
  2. Gỡ lỗi Gateway - Gỡ lỗi dịch vụ Gateway của một build đã có sẵn

​
Thiết lập

Cấu hình Build lại và gỡ lỗi Gateway mặc định có đủ mọi thứ cần thiết, nó sẽ tự động xóa thư mục /dist và build lại dự án với gỡ lỗi được bật:
  1. Mở bảng Run and Debug từ Activity Bar hoặc nhấn Ctrl+Shift+D
  2. Trong IDE, đảm bảo Build lại và gỡ lỗi Gateway được chọn trong menu thả xuống cấu hình rồi nhấn nút Start Debugging
Hoặc, nếu bạn muốn tự quản lý quá 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, build lại dự án: pnpm clean:dist && pnpm build
  3. Trong IDE, chọn tùy chọn Gỡ lỗi Gateway trong menu thả xuống cấu hình Run and Debug rồi nhấn nút Start Debugging
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 các breakpoint tới JavaScript đã biên dịch qua source map. Bạn sẽ có thể kiểm tra biến, bước qua mã và xem call stack như mong đợi.

​
Ghi chú

  • Nếu dùng tùy chọn “Build lại và gỡ lỗi 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 một pnpm build đầy đủ với source map được bật trước khi khởi động Gateway
  • Nếu dùng tùy chọn “Gỡ lỗi Gateway” - phiên gỡ lỗi có thể được khởi động và dừng bất cứ 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ài đặt 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 CLI OpenClaw đã 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 ra 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