Gỡ lỗi

Các tiện ích gỡ lỗi cho đầu ra truyền trực tiếp, quá trình lặp Gateway và lập hồ sơ khởi động.

Ghi đè gỡ lỗi thời gian chạy

/debug đặt các giá trị ghi đè cấu hình chỉ dành cho thời gian chạy (trong bộ nhớ, không phải trên đĩa). Mặc định bị tắt; bật bằng commands.debug: true.

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

/debug reset xóa tất cả giá trị ghi đè và trở về cấu hình trên đĩa.

Đầu ra truy vết phiên

/trace hiển thị các dòng truy vết/gỡ lỗi do plugin sở hữu cho một phiên mà không bật toàn bộ chế độ chi tiết. Dùng lệnh này để chẩn đoán plugin, chẳng hạn như bản tóm tắt gỡ lỗi Active Memory; dùng /verbose cho đầu ra trạng thái/công cụ thông thường.

/trace/trace on/trace off

Truy vết vòng đời Plugin

Đặt OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 để xem phân tích theo từng giai đoạn về siêu dữ liệu plugin, khám phá, sổ đăng ký, bản sao thời gian chạy, thay đổi cấu hình và công việc làm mới. Kết quả được ghi vào stderr, vì vậy đầu ra lệnh JSON vẫn có thể phân tích cú pháp.

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[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"

Hãy dùng cách này trước khi dùng đến trình lập hồ sơ CPU. Từ bản checkout mã nguồn, đo thời gian chạy đã xây dựng bằng node dist/entry.js ... sau pnpm build; pnpm openclaw ... cũng đo cả chi phí bổ sung của trình chạy mã nguồn.

Lập hồ sơ khởi động và lệnh CLI

Các phép đo hiệu năng khởi động được lưu trong kho 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

Để lập hồ sơ một lần thông qua trình chạy mã nguồn thông thường, hãy đặ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ờ lập hồ sơ CPU của Node và ghi tệp .cpuprofile cho lệnh. Hãy 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 tình trạng khởi động bị treo có vẻ do thao tác hệ thống tệp đồng bộ hoặc bộ nạp mô-đun, hãy thêm cờ truy vết I/O đồng bộ của Node thông qua trình chạy mã nguồn:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

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

Chế độ theo dõi Gateway

pnpm gateway:watch

Theo mặc định, lệnh này khởi động hoặc khởi động lại một phiên tmux có tên openclaw-gateway-watch-<profile> (ví dụ openclaw-gateway-watch-main), với hậu tố cổng như openclaw-gateway-watch-dev-19001 chỉ được thêm khi OPENCLAW_GATEWAY_PORT khác cổng mặc định 18789. Lệnh tự động đính kèm từ các terminal tương tác; các shell không tương tác, CI và lệnh thực thi của tác nhân vẫn ở trạng thái tách rời và thay vào đó in hướng dẫn đính kèm:

tmux attach -t openclaw-gateway-watch-main

Khung tmux chạy trình theo dõi thô:

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

Dừng dịch vụ Gateway đã cài đặt trước khi theo dõi cùng một cổng:

pnpm openclaw gateway stop

Cờ --force của trình theo dõi xóa trình lắng nghe hiện tại, nhưng không vô hiệu hóa dịch vụ được giám sát. Nếu không, dịch vụ launchd, systemd hoặc Scheduled Task có thể tái khởi chạy và thay thế Gateway đang được theo dõi.

Chế độ chạy nền trước không dùng tmux:

pnpm gateway:watch:raw# hoặcOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Giữ chức năng quản lý tmux nhưng tắt tự động đính kèm:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Lập hồ sơ thời gian CPU của Gateway đang được theo dõi khi gỡ lỗi các điểm nóng trong quá trình khởi động/thời gian chạy:

pnpm gateway:watch --benchmark

Trình bao theo dõi sử dụng --benchmark trước khi gọi Gateway và ghi một tệp V8 .cpuprofile cho mỗi lần tiến trình Gateway con thoát trong .artifacts/gateway-watch-profiles/. Dừng hoặc khởi động lại gateway đang được theo dõi để ghi hoàn tất hồ sơ hiện tại, sau đó mở bằng Chrome DevTools hoặc Speedscope:

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

• --benchmark-dir <path>: ghi hồ sơ vào vị trí khác.
• --benchmark-no-force: bỏ qua thao tác dọn dẹp cổng mặc định bằng --force và thất bại ngay nếu cổng Gateway đã được sử dụng.

Chế độ đo hiệu năng mặc định ngăn lượng lớn thông báo truy vết I/O đồng bộ. Đặt OPENCLAW_TRACE_SYNC_IO=1 cùng --benchmark để nhận cả hồ sơ CPU và truy vết ngăn xếp I/O đồng bộ; trong chế độ đo hiệu năng, các khối truy vết đó được ghi vào gateway-watch-output.log trong thư mục đo hiệu năng (được lọc khỏi khung terminal), trong khi nhật ký Gateway thông thường vẫn hiển thị.

Trình bao tmux chuyển các bộ chọn thời gian chạy phổ biến không chứa bí mật vào khung, bao gồm OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT và OPENCLAW_SKIP_CHANNELS. Đặt thông tin xác thực của nhà cung cấp trong hồ sơ/cấu hình thông thường hoặc dùng chế độ nền trước thô cho các bí mật tạm thời chỉ dùng một lần.

Nếu Gateway đang được theo dõi thoát trong khi khởi động, trình theo dõi chạy openclaw doctor --fix --non-interactive một lần rồi khởi động lại tiến trình Gateway con. Đặt OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 để xem lỗi khởi động ban đầu mà không có lượt sửa chữa chỉ dành cho môi trường phát triển.

Khung tmux được quản lý mặc định hiển thị nhật ký Gateway có màu; đặ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 tệp liên quan đến bản dựng trong src/, các tệp mã nguồn tiện ích mở rộng, siêu dữ liệu package.json và openclaw.plugin.json của tiện ích mở rộng, tsconfig.json, package.json và tsdown.config.ts thay đổi. Các thay đổi siêu dữ liệu tiện ích mở rộng khởi động lại gateway mà không buộc xây dựng lại; thay đổi mã nguồn và cấu hình vẫn xây dựng lại dist trước.

Thêm các cờ CLI của gateway sau gateway:watch và chúng sẽ được chuyển tiếp trong mỗi lần khởi động lại. Chạy lại cùng một lệnh theo dõi sẽ tái tạo khung tmux có tên tương ứng; trình theo dõi thô duy trì khóa trình theo dõi duy nhất để các tiến trình cha trùng lặp được thay thế thay vì tích tụ.

Hồ sơ phát triển + gateway phát triển (--dev)

Có hai cờ --dev riêng biệt:

• --dev toàn cục (hồ sơ): cô lập trạng thái trong ~/.openclaw-dev và đặt cổng gateway mặc định thành 19001 (các cổng dẫn xuất cũng thay đổi theo).
• gateway --dev: yêu cầu Gateway tự động tạo cấu hình + không gian làm việc mặc định khi chưa có (và bỏ qua quá trình bootstrap).

Quy trình được khuyến nghị (hồ sơ phát triển + bootstrap phát triển):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

Nếu không cài đặt toàn cục, hãy chạy CLI qua pnpm openclaw ....

Các tác vụ được thực hiện:

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 (các cổng trình duyệt/canvas thay đổi tương ứng)

2. Bootstrap phát triển (gateway --dev)

   • Ghi cấu hình tối thiểu nếu chưa có (gateway.mode=local, liên kết với local loopback).
   • Đặt agents.defaults.workspace thành không gian làm việc phát triển và agents.defaults.skipBootstrap=true.
   • Khởi tạo các tệp không gian làm việc nếu chưa có: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
   • Danh tính mặc định: C3-PO (người máy giao thức).
   • pnpm gateway:dev cũng đặt OPENCLAW_SKIP_CHANNELS=1 để bỏ qua các nhà cung cấp kênh.

Quy trình đặt lại (khởi đầu mới):

pnpm gateway:dev:reset

--reset xóa sạch cấu hình, thông tin xác thực, phiên và không gian làm việc phát triển (chuyển vào thùng rác, không xóa vĩnh viễn), sau đó tạo lại thiết lập phát triển mặc định.

Ghi nhật ký luồng thô

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

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

Lưu ý an toàn

• Nhật ký luồng thô có thể chứa toàn bộ lời nhắc, đầ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 chia sẻ nhật ký, trước tiên hãy loại bỏ bí mật và thông tin nhận dạng cá nhân.

Gỡ lỗi trong VSCode

Cần có bản đồ mã nguồn vì quá trình xây dựng tạo mã băm cho tên tệp được sinh ra. Tệp launch.json đi kèm nhắm đến dịch vụ Gateway:

1. Rebuild and Debug Gateway - xóa /dist và xây dựng lại với chế độ gỡ lỗi được bật trước khi khởi động Gateway.
2. Debug Gateway - gỡ lỗi bản dựng hiện có mà không thay đổi /dist.

Thiết lập

1. Mở Run and Debug (Thanh Hoạt động hoặc Ctrl+Shift+D).
2. Chọn Rebuild and Debug Gateway rồi nhấn Start Debugging.

Để quản lý thủ công chu kỳ xây dựng/gỡ lỗi:

1. Bật bản đồ mã nguồn trong terminal:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. Xây dựng lại: pnpm clean:dist && pnpm build
3. Chọn Debug Gateway rồi nhấn Start Debugging.

Đặt điểm ngắt trong các tệp TypeScript thuộc src/; trình gỡ lỗi ánh xạ chúng tới JavaScript đã biên dịch thông qua bản đồ mã nguồn.

Lưu ý

• Rebuild and Debug Gateway xóa /dist và chạy toàn bộ pnpm build với bản đồ mã nguồn trong mỗi lần khởi chạy.
• Debug Gateway có thể khởi động/dừng mà không ảnh hưởng đến /dist, nhưng bạn quản lý chu kỳ xây dựng trong một terminal riêng.
• Chỉnh sửa args trong launch.json để gỡ lỗi các lệnh con CLI khác.
• Để dùng CLI đã xây dựng cho các tác vụ khác (ví dụ dashboard --no-open nếu phiên gỡ lỗi của bạn tạo mã thông báo xác thực mới), hãy chạy từ một terminal khác: node ./openclaw.mjs hoặc một bí danh 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