OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Gateway

Gateway là máy chủ WebSocket của OpenClaw (các kênh, Node, phiên, hook). Tất cả các lệnh con bên dưới đều nằm dưới openclaw gateway ....

Khám phá Bonjour

Thiết lập mDNS cục bộ + DNS-SD diện rộng.
Tổng quan về khám phá

Cách OpenClaw quảng bá và tìm các Gateway.
Cấu hình

Các khóa cấu hình Gateway cấp cao nhất.

Chạy Gateway

bash
openclaw gatewayopenclaw gateway run   # dạng tương đương, tường minh
Hành vi khi khởi động
  • Từ chối khởi động trừ khi gateway.mode=local được đặt trong ~/.openclaw/openclaw.json. Dùng --allow-unconfigured cho các lần chạy đặc biệt/phát triển; cờ này bỏ qua cơ chế bảo vệ mà không ghi hoặc sửa cấu hình.
  • openclaw onboard --mode local và openclaw setup ghi gateway.mode=local. Nếu tệp cấu hình tồn tại nhưng thiếu gateway.mode, tệp đó được coi là cấu hình bị hỏng/ghi đè và Gateway sẽ không tự suy đoán local cho bạn — hãy chạy lại quy trình thiết lập ban đầu, đặt khóa theo cách thủ công hoặc truyền --allow-unconfigured.
  • Việc liên kết ra ngoài loopback mà không có xác thực sẽ bị chặn.
  • Các giá trị lan, tailnet và custom của --bind hiện chỉ phân giải qua các đường dẫn IPv4; các thiết lập dùng máy chủ riêng chỉ có IPv6 cần một tiến trình phụ IPv4 hoặc proxy phía trước Gateway.
  • SIGUSR1 kích hoạt khởi động lại trong tiến trình khi được phép. commands.restart (mặc định: bật) kiểm soát SIGUSR1 được gửi từ bên ngoài; đặt thành false để chặn khởi động lại thủ công bằng tín hiệu hệ điều hành trong khi vẫn cho phép khởi động lại qua lệnh gateway restart, công cụ Gateway và thao tác áp dụng/cập nhật cấu hình.
  • SIGINT/SIGTERM dừng tiến trình nhưng không khôi phục trạng thái thiết bị đầu cuối tùy chỉnh — nếu bạn bọc CLI trong TUI hoặc đầu vào chế độ thô, hãy tự khôi phục thiết bị đầu cuối trước khi thoát.

Tùy chọn

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> Cổng WebSocket (mặc định lấy từ cấu hình/biến môi trường; thường là 18789).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYmluZCA8bW9kZQ " type="string"> Chế độ liên kết: loopback (mặc định), lan, tailnet, auto, custom.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdG9rZW4gPHRva2Vu " type="string"> Token dùng chung cho connect.params.auth.token. Mặc định là OPENCLAW_GATEWAY_TOKEN khi được đặt.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tYXV0aCA8bW9kZQ " type="string"> Chế độ xác thực: none, token, password, trusted-proxy.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcGFzc3dvcmQgPHBhc3N3b3Jk " type="string"> Mật khẩu cho --auth password.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdGFpbHNjYWxlIDxtb2Rl " type="string"> Chế độ công khai qua Tailscale: off, serve, funnel.

--tailscale-reset-on-exitboolean

Đặt lại cấu hình serve/funnel của Tailscale khi tắt.

--allow-unconfiguredboolean

Khởi động mà không bắt buộc gateway.mode=local. Chỉ dùng để khởi tạo đặc biệt/phát triển; không lưu hoặc sửa cấu hình.

--devboolean

Tạo cấu hình phát triển + không gian làm việc nếu chưa có (bỏ qua BOOTSTRAP.md).

--resetboolean

Đặt lại cấu hình phát triển, thông tin xác thực, phiên và không gian làm việc. Yêu cầu --dev.

--forceboolean

Dừng mọi trình lắng nghe hiện có trên cổng đích trước khi khởi động.

--verboseboolean

Ghi nhật ký chi tiết ra stdout/stderr.

--cli-backend-logsboolean

Chỉ hiển thị nhật ký phần phụ trợ CLI trong bảng điều khiển (đồng thời bật stdout/stderr).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0td3MtbG9nIDxzdHlsZQ " type="string" default="auto"> Kiểu nhật ký WebSocket: auto, full, compact.

--compactboolean

Bí danh của --ws-log compact.

--raw-streamboolean

Ghi các sự kiện luồng mô hình thô vào JSONL.

--claude-cli-logs là bí danh không còn được khuyến nghị của --cli-backend-logs.

Với --bind custom, hãy đặt gateway.customBindHost thành một địa chỉ IPv4. Mọi địa chỉ ngoài 127.0.0.1 hoặc 0.0.0.0 cũng yêu cầu 127.0.0.1 trên cùng cổng cho các máy khách trên cùng máy chủ; quá trình khởi động sẽ thất bại nếu một trong hai trình lắng nghe không thể liên kết. Địa chỉ đại diện 0.0.0.0 không thêm một bí danh bắt buộc riêng. Các thiết lập dùng máy chủ riêng chỉ có IPv6 cần một tiến trình phụ IPv4 hoặc proxy phía trước Gateway.

Khởi động lại Gateway

bash
openclaw gateway restartopenclaw gateway restart --safeopenclaw gateway restart --safe --skip-deferralopenclaw gateway restart --forceopenclaw gateway restart --wait 30s

--safe yêu cầu Gateway đang chạy kiểm tra trước công việc đang hoạt động và lên lịch một lần khởi động lại hợp nhất sau khi công việc đó hoàn tất. Thời gian chờ bị giới hạn bởi gateway.reload.deferralTimeoutMs (mặc định: 5 phút / 300000); khi hết khoảng thời gian này, việc khởi động lại sẽ bị buộc thực hiện. Đặt deferralTimeoutMs: 0 để chờ vô thời hạn (kèm cảnh báo định kỳ rằng vẫn đang chờ) thay vì buộc thực hiện. Không thể kết hợp --safe với --force hoặc --wait.

--skip-deferral bỏ qua cổng trì hoãn do công việc đang hoạt động khi khởi động lại an toàn, vì vậy Gateway khởi động lại ngay lập tức ngay cả khi có báo cáo về yếu tố cản trở. Cờ này yêu cầu --safe — hãy dùng khi việc trì hoãn bị kẹt do một tác vụ mất kiểm soát.

--wait <duration> ghi đè khoảng thời gian chờ hoàn tất cho một lần khởi động lại thông thường (không an toàn). Chấp nhận giá trị mili giây thuần hoặc hậu tố đơn vị ms, s, m, h, d (ví dụ: 30s, 5m, 1h30m); --wait 0 chờ vô thời hạn. Không tương thích với --force hoặc --safe.

--force bỏ qua việc chờ công việc đang hoạt động hoàn tất và khởi động lại ngay lập tức. restart thông thường (không có cờ) giữ nguyên hành vi khởi động lại hiện có của trình quản lý dịch vụ.

Lập hồ sơ Gateway

  • OPENCLAW_GATEWAY_STARTUP_TRACE=1 ghi thời gian của từng giai đoạn trong lúc khởi động, bao gồm độ trễ eventLoopMax theo từng giai đoạn và thời gian của bảng tra cứu Plugin (chỉ mục đã cài đặt, sổ đăng ký manifest, lập kế hoạch khởi động, xử lý ánh xạ chủ sở hữu).
  • OPENCLAW_GATEWAY_RESTART_TRACE=1 ghi các dòng restart trace: trong phạm vi khởi động lại: xử lý tín hiệu, chờ công việc đang hoạt động hoàn tất, các giai đoạn tắt, lần khởi động tiếp theo, thời gian sẵn sàng và chỉ số bộ nhớ.
  • OPENCLAW_DIAGNOSTICS=timeline cùng OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path> ghi dòng thời gian chẩn đoán khởi động JSONL theo khả năng tốt nhất cho các bộ kiểm thử QA bên ngoài (tương đương cấu hình diagnostics.flags: ["timeline"]; đường dẫn vẫn chỉ có thể đặt qua biến môi trường). Thêm OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 để bao gồm các mẫu vòng lặp sự kiện.
  • Chạy pnpm build, sau đó chạy pnpm test:startup:gateway -- --runs 5 --warmup 1 để đo chuẩn quá trình khởi động Gateway dựa trên điểm vào CLI đã dựng: đầu ra tiến trình đầu tiên, /healthz, /readyz, thời gian theo dõi khởi động, độ trễ vòng lặp sự kiện và thời gian bảng tra cứu Plugin.
  • Chạy pnpm build, sau đó chạy pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5 để đo chuẩn quá trình khởi động lại trong tiến trình trên macOS hoặc Linux (không được hỗ trợ trên Windows; khởi động lại yêu cầu SIGUSR1). Lệnh này dùng SIGUSR1, bật cả hai chế độ theo dõi trong tiến trình con và ghi lại lần /healthz tiếp theo, lần /readyz tiếp theo, thời gian gián đoạn, thời gian sẵn sàng, CPU, RSS và các chỉ số theo dõi khởi động lại.
  • /healthz biểu thị tiến trình còn hoạt động; /readyz biểu thị mức sẵn sàng sử dụng. Hãy coi các dòng theo dõi và đầu ra đo chuẩn là tín hiệu quy trách nhiệm cho chủ sở hữu, không phải kết luận hiệu năng hoàn chỉnh từ một khoảng đo hoặc mẫu duy nhất.

Truy vấn một Gateway đang chạy

Tất cả các lệnh truy vấn đều dùng RPC qua WebSocket.

Chế độ đầu ra

  • Mặc định: con người có thể đọc được (có màu trong TTY).
  • --json: JSON máy có thể đọc được (không có định kiểu/chỉ báo xoay).
  • --no-color (hoặc NO_COLOR=1): tắt ANSI trong khi vẫn giữ bố cục dành cho con người.

Tùy chọn dùng chung

  • --url <url>: URL WebSocket của Gateway.
  • --token <token>: Token Gateway.
  • --password <password>: Mật khẩu Gateway.
  • --timeout <ms>: thời gian chờ/ngân sách thời gian (mặc định thay đổi theo từng lệnh; xem từng lệnh bên dưới).
  • --expect-final: chờ phản hồi "cuối cùng" (các lệnh gọi tác tử).

gateway health

bash
openclaw gateway health --url ws://127.0.0.1:18789openclaw gateway health --port 18789

/healthz là phép thăm dò trạng thái hoạt động: nó trả về ngay khi máy chủ có thể phản hồi HTTP. /readyz nghiêm ngặt hơn và duy trì trạng thái đỏ trong khi các tiến trình phụ Plugin khởi động, kênh hoặc hook đã cấu hình vẫn đang ổn định. Các phản hồi /readyz chi tiết cục bộ hoặc đã xác thực bao gồm một khối chẩn đoán eventLoop (độ trễ, mức sử dụng, tỷ lệ lõi CPU, cờ degraded).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> Nhắm đến một Gateway local loopback trên cổng này. Ghi đè OPENCLAW_GATEWAY_URL và OPENCLAW_GATEWAY_PORT cho lệnh gọi này.

gateway usage-cost

Lấy các bản tóm tắt chi phí sử dụng từ nhật ký phiên.

bash
openclaw gateway usage-costopenclaw gateway usage-cost --days 7openclaw gateway usage-cost --agent work --jsonopenclaw gateway usage-cost --all-agentsopenclaw gateway usage-cost --json
"--days
"--agent
--all-agentsboolean

Tổng hợp trên tất cả các tác tử đã cấu hình. Không thể kết hợp với --agent.

gateway stability

Lấy bộ ghi độ ổn định chẩn đoán gần đây từ một Gateway đang chạy.

bash
openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --bundle latestopenclaw gateway stability --bundle latest --exportopenclaw gateway stability --json

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tbGltaXQgPGxpbWl0 " type="number" default="25"> Số sự kiện gần đây tối đa cần bao gồm (tối đa 1000).

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tdHlwZSA8dHlwZQ " type="string"> Lọc theo loại sự kiện chẩn đoán, ví dụ: payload.large hoặc diagnostic.memory.pressure.

"--since-seq
--bundle [path]string

Đọc một gói độ ổn định đã lưu thay vì gọi Gateway đang chạy. --bundle latest (hoặc chỉ --bundle) chọn gói mới nhất trong thư mục trạng thái; bạn cũng có thể truyền trực tiếp đường dẫn JSON của gói.

--exportboolean

Ghi một tệp zip chẩn đoán hỗ trợ có thể chia sẻ thay vì in chi tiết độ ổn định.

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tb3V0cHV0IDxwYXRo " type="string"> Đường dẫn đầu ra cho --export.

Quyền riêng tư và hành vi của gói
  • Bản ghi giữ lại siêu dữ liệu vận hành: tên sự kiện, số lượng, kích thước byte, số đo bộ nhớ, trạng thái hàng đợi/phiên, mã định danh phê duyệt, tên kênh/Plugin và bản tóm tắt phiên đã che thông tin nhạy cảm. Chúng loại trừ nội dung trò chuyện, phần thân Webhook, đầu ra công cụ, phần thân yêu cầu/phản hồi thô, token, cookie, giá trị bí mật, tên máy chủ và mã định danh phiên thô. Đặt diagnostics.enabled: false để tắt hoàn toàn bộ ghi.
  • Các lần Gateway thoát nghiêm trọng, hết thời gian chờ khi tắt và lỗi khởi động sau khi khởi động lại sẽ ghi cùng ảnh chụp nhanh chẩn đoán vào ~/.openclaw/logs/stability/openclaw-stability-*.json khi bộ ghi có sự kiện. Kiểm tra gói mới nhất bằng openclaw gateway stability --bundle latest; --limit, --type và --since-seq cũng áp dụng cho đầu ra của gói.

gateway diagnostics export

Ghi một tệp zip chẩn đoán cục bộ được thiết kế cho báo cáo lỗi. Để biết mô hình quyền riêng tư và nội dung gói, hãy xem Xuất dữ liệu chẩn đoán.

bash
openclaw gateway diagnostics exportopenclaw gateway diagnostics export --output openclaw-diagnostics.zipopenclaw gateway diagnostics export --json
"--log-lines
"--log-bytes
"--url
"--token
"--password
"--timeout
--no-stability-bundleboolean

Bỏ qua việc tra cứu gói ổn định đã lưu.

--jsonboolean

In đường dẫn đã ghi, kích thước và tệp kê khai dưới dạng JSON.

Bản xuất đóng gói: manifest.json (danh mục tệp), summary.md (bản tóm tắt Markdown), diagnostics.json (bản tóm tắt cấu hình/nhật ký/khám phá/độ ổn định/trạng thái/tình trạng cấp cao nhất), config/sanitized.json, status/gateway-status.json, health/gateway-health.json, logs/openclaw-sanitized.jsonl và stability/latest.json khi có gói.

Bản xuất này được thiết kế để chia sẻ. Nó giữ lại các chi tiết vận hành hữu ích cho việc gỡ lỗi — các trường nhật ký an toàn, tên hệ thống con, mã trạng thái, khoảng thời gian, chế độ đã cấu hình, cổng, mã định danh Plugin/nhà cung cấp, cài đặt tính năng không bí mật và thông báo nhật ký vận hành đã được che bớt — đồng thời loại bỏ hoặc che bớt nội dung trò chuyện, nội dung Webhook, đầu ra công cụ, thông tin xác thực, cookie, mã định danh tài khoản/tin nhắn, nội dung lời nhắc/chỉ dẫn, tên máy chủ và các giá trị bí mật. Khi một thông báo nhật ký có vẻ là nội dung tải trọng của người dùng/cuộc trò chuyện/công cụ (ví dụ: "người dùng đã nói", "nội dung trò chuyện", "đầu ra công cụ", "nội dung Webhook"), bản xuất chỉ giữ lại thông tin rằng một thông báo đã bị loại bỏ cùng với số byte của thông báo đó.

gateway status

Hiển thị dịch vụ Gateway (launchd/systemd/schtasks) cùng với phép kiểm tra kết nối/xác thực tùy chọn.

bash
openclaw gateway statusopenclaw gateway status --jsonopenclaw gateway status --require-rpc
"--url
"--token
"--password
"--timeout
--no-probeboolean

Bỏ qua phép kiểm tra kết nối (chỉ hiển thị dịch vụ).

--deepboolean

Quét cả các dịch vụ cấp hệ thống.

--require-rpcboolean

Nâng cấp phép kiểm tra kết nối thành phép kiểm tra đọc và thoát với mã khác 0 nếu thất bại. Không thể kết hợp với --no-probe.

Ngữ nghĩa trạng thái
  • Vẫn khả dụng cho mục đích chẩn đoán ngay cả khi cấu hình CLI cục bộ bị thiếu hoặc không hợp lệ.
  • Đầu ra mặc định xác minh trạng thái dịch vụ, kết nối WebSocket và khả năng xác thực hiển thị tại thời điểm bắt tay — không xác minh các thao tác đọc/ghi/quản trị.
  • Các phép kiểm tra không làm thay đổi trạng thái đối với việc xác thực thiết bị lần đầu: chúng sử dụng lại token thiết bị hiện có trong bộ nhớ đệm khi có, nhưng không bao giờ tạo danh tính thiết bị CLI mới hoặc bản ghi ghép nối chỉ đọc chỉ để kiểm tra trạng thái.
  • Phân giải các SecretRef xác thực đã cấu hình để xác thực phép kiểm tra khi có thể. Nếu một SecretRef bắt buộc chưa được phân giải, --json báo cáo rpc.authWarning khi kết nối/xác thực của phép kiểm tra thất bại; hãy truyền rõ ràng --token/--password hoặc sửa nguồn bí mật. Cảnh báo xác thực chưa phân giải sẽ bị ẩn sau khi phép kiểm tra thành công.
  • Đầu ra JSON bao gồm gateway.version khi Gateway đang chạy báo cáo giá trị này; --require-rpc có thể dùng tải trọng RPC status.runtimeVersion làm phương án dự phòng nếu phép kiểm tra bắt tay không thể cung cấp siêu dữ liệu phiên bản.
  • Dùng --require-rpc trong tập lệnh/tự động hóa khi một dịch vụ đang lắng nghe là chưa đủ và RPC phạm vi đọc cũng cần hoạt động bình thường.
  • --deep quét các bản cài đặt launchd/systemd/schtasks bổ sung; khi tìm thấy nhiều dịch vụ tương tự Gateway, đầu ra dành cho người dùng in các gợi ý dọn dẹp (thường chỉ nên chạy một Gateway trên mỗi máy) và báo cáo lần bàn giao khởi động lại gần đây của trình giám sát khi thích hợp.
  • --deep cũng chạy xác thực cấu hình ở chế độ nhận biết Plugin (pluginValidation: "full") và hiển thị cảnh báo tệp kê khai Plugin (ví dụ: thiếu siêu dữ liệu cấu hình kênh). gateway status mặc định giữ đường dẫn chỉ đọc nhanh, bỏ qua việc xác thực Plugin.
  • Đầu ra dành cho người dùng bao gồm đường dẫn tệp nhật ký đã phân giải cùng với đường dẫn/tính hợp lệ của cấu hình CLI so với dịch vụ để giúp chẩn đoán sự sai lệch của hồ sơ hoặc thư mục trạng thái.
Kiểm tra sai lệch xác thực systemd trên Linux
  • Các phép kiểm tra sai lệch xác thực của dịch vụ đọc cả Environment= và EnvironmentFile= từ đơn vị dịch vụ (bao gồm %h, đường dẫn trong dấu ngoặc kép, nhiều tệp và các tệp tùy chọn có tiền tố -).
  • Phân giải các SecretRef gateway.auth.token bằng môi trường thời gian chạy đã hợp nhất (môi trường lệnh dịch vụ trước, sau đó dùng môi trường tiến trình làm phương án dự phòng).
  • Các phép kiểm tra sai lệch token bỏ qua việc phân giải token cấu hình khi xác thực bằng token không thực sự hoạt động (gateway.auth.mode được đặt rõ ràng là password/none/trusted-proxy, hoặc chế độ chưa được đặt trong trường hợp mật khẩu có thể được ưu tiên và không có ứng viên token nào có thể được ưu tiên).

gateway probe

Lệnh "gỡ lỗi mọi thứ". Lệnh này luôn kiểm tra:

  • Gateway từ xa đã cấu hình của bạn (nếu có), và
  • localhost (local loopback), ngay cả khi địa chỉ từ xa đã được cấu hình.

Truyền --url sẽ thêm đích rõ ràng đó trước cả hai đích trên. Đầu ra dành cho người dùng gắn nhãn các đích là URL (được chỉ định rõ ràng), Từ xa (đã cấu hình) / Từ xa (đã cấu hình, không hoạt động) và Local loopback.

bash
openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --port 18789

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcG9ydCA8cG9ydA " type="number"> Dùng cổng này cho đích kiểm tra local loopback và cổng từ xa của đường hầm SSH. Khi không có --url, tùy chọn này chỉ chọn đích local loopback thay vì URL môi trường Gateway đã cấu hình, cổng môi trường hoặc các đích từ xa.

Diễn giải
  • Có thể truy cập: có nghĩa là ít nhất một đích đã chấp nhận kết nối WebSocket.
  • Khả năng: chỉ đọc|có thể ghi|có thể quản trị|đang chờ ghép nối|chỉ kết nối báo cáo điều mà phép kiểm tra có thể xác minh về xác thực, tách biệt với khả năng truy cập.
  • Phép kiểm tra đọc: đạt nghĩa là các lệnh gọi RPC chi tiết thuộc phạm vi đọc (health/status/system-presence/config.get) cũng thành công.
  • Phép kiểm tra đọc: bị giới hạn - thiếu phạm vi: operator.read nghĩa là kết nối thành công nhưng RPC phạm vi đọc bị giới hạn. Được báo cáo là khả năng truy cập suy giảm, không phải thất bại hoàn toàn.
  • Phép kiểm tra đọc: thất bại sau Kết nối: đạt nghĩa là WebSocket đã kết nối nhưng chẩn đoán đọc tiếp theo đã hết thời gian chờ hoặc thất bại — cũng là suy giảm, không phải không thể truy cập.
  • Giống như gateway status, phép kiểm tra sử dụng lại thông tin xác thực thiết bị hiện có trong bộ nhớ đệm nhưng không tạo danh tính thiết bị hoặc trạng thái ghép nối lần đầu.
  • Mã thoát chỉ khác 0 khi không thể truy cập bất kỳ đích nào được kiểm tra.
Đầu ra JSON

Cấp cao nhất:

  • ok: có thể truy cập ít nhất một đích.
  • degraded: ít nhất một đích đã chấp nhận kết nối nhưng không hoàn tất đầy đủ chẩn đoán RPC chi tiết.
  • capability: khả năng tốt nhất được ghi nhận trên các đích có thể truy cập (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope hoặc unknown).
  • primaryTargetId: đích tốt nhất để coi là đích đang hoạt động, theo thứ tự: URL rõ ràng, đường hầm SSH, địa chỉ từ xa đã cấu hình, local loopback.
  • warnings[]: các bản ghi cảnh báo theo nỗ lực tối đa với code, message, targetIds tùy chọn.
  • network: các gợi ý URL local loopback/tailnet được suy ra từ cấu hình hiện tại và mạng của máy chủ.
  • discovery.timeoutMs / discovery.count: ngân sách khám phá/số lượng kết quả thực tế được dùng cho lượt kiểm tra này.

Theo từng đích (targets[].connect): ok (khả năng truy cập + phân loại suy giảm), rpcOk (RPC chi tiết đầy đủ thành công), scopeLimited (RPC chi tiết thất bại do thiếu phạm vi toán tử).

Theo từng đích (targets[].auth): role và scopes được báo cáo trong hello-ok khi có, cùng với phân loại capability được hiển thị.

Các mã cảnh báo thường gặp
  • ssh_tunnel_failed: thiết lập đường hầm SSH thất bại; lệnh đã dùng các phép kiểm tra trực tiếp làm phương án dự phòng.
  • multiple_gateways: có thể truy cập các danh tính Gateway khác nhau, hoặc OpenClaw không thể xác minh rằng các đích có thể truy cập là cùng một Gateway. Đường hầm SSH, URL proxy hoặc URL từ xa đã cấu hình trỏ tới cùng một Gateway sẽ không kích hoạt cảnh báo này.
  • auth_secretref_unresolved: không thể phân giải SecretRef xác thực đã cấu hình cho một đích thất bại.
  • probe_scope_limited: kết nối WebSocket thành công, nhưng phép kiểm tra đọc bị giới hạn do thiếu operator.read.
  • local_tls_runtime_unavailable: TLS của Gateway cục bộ đã được bật nhưng OpenClaw không thể tải dấu vân tay chứng chỉ cục bộ.

Từ xa qua SSH (tương đương ứng dụng Mac)

Chế độ "Remote over SSH" của ứng dụng macOS sử dụng chuyển tiếp cổng cục bộ để một Gateway từ xa chỉ dùng local loopback có thể được truy cập tại ws://127.0.0.1:<port>.

Lệnh CLI tương đương:

bash
openclaw gateway probe --ssh user@gateway-host

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tc3NoIDx0YXJnZXQ " type="string"> user@host hoặc user@host:port (cổng mặc định là 22).

--ssh-autoboolean

Chọn máy chủ Gateway đầu tiên được khám phá làm đích SSH từ điểm cuối khám phá đã phân giải (local. cộng với miền diện rộng đã cấu hình, nếu có). Các gợi ý chỉ có TXT sẽ bị bỏ qua.

Giá trị mặc định của cấu hình (tùy chọn): gateway.remote.sshTarget, gateway.remote.sshIdentity.

gateway call <method>

Trình trợ giúp RPC cấp thấp.

bash
openclaw gateway call statusopenclaw gateway call logs.tail --params '{"limit": 200}'
"--params
"--url
"--token
"--password
"--timeout
--expect-finalboolean

Chủ yếu dành cho các RPC kiểu tác tử truyền phát các sự kiện trung gian trước tải trọng cuối cùng.

--jsonboolean

Đầu ra JSON có thể đọc bằng máy.

Quản lý dịch vụ Gateway

bash
openclaw gateway installopenclaw gateway startopenclaw gateway stopopenclaw gateway restartopenclaw gateway uninstall

Cài đặt bằng trình bao bọc

Dùng --wrapper khi dịch vụ được quản lý phải khởi động thông qua một tệp thực thi khác, chẳng hạn như một lớp đệm của trình quản lý bí mật hoặc trình trợ giúp chạy dưới danh nghĩa người dùng khác. Trình bao bọc nhận các đối số Gateway thông thường và chịu trách nhiệm cuối cùng thực thi openclaw hoặc Node với các đối số đó.

bash
cat > ~/.local/bin/openclaw-doppler <<'EOF'#!/usr/bin/env bashset -euo pipefailexec doppler run --project my-project --config production -- openclaw "$@"EOFchmod +x ~/.local/bin/openclaw-doppler openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --forceopenclaw gateway restart

Bạn cũng có thể đặt trình bao bọc thông qua môi trường. gateway install xác thực rằng đường dẫn là một tệp thực thi, ghi trình bao bọc vào ProgramArguments của dịch vụ và lưu OPENCLAW_WRAPPER trong môi trường dịch vụ để dùng cho các lần buộc cài đặt lại, cập nhật và sửa chữa bằng doctor sau này.

bash
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --forceopenclaw doctor

Để xóa trình bao bọc đã lưu, hãy xóa giá trị OPENCLAW_WRAPPER trong khi cài đặt lại:

bash
OPENCLAW_WRAPPER= openclaw gateway install --forceopenclaw gateway restart
Tùy chọn lệnh
  • gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
  • gateway install: --port, --runtime <node|bun> (mặc định: node), --token, --wrapper <path>, --force, --json
  • gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
  • gateway uninstall|start: --json
  • gateway stop: --disable, --json
Hành vi vòng đời
  • Sử dụng gateway restart để khởi động lại một dịch vụ được quản lý. Không nối tiếp gateway stop và gateway start để thay thế thao tác khởi động lại.
  • Trên macOS, theo mặc định, gateway stop sử dụng launchctl bootout, thao tác này xóa LaunchAgent khỏi phiên khởi động hiện tại mà không lưu trạng thái vô hiệu hóa — khả năng tự động khôi phục của KeepAlive vẫn hoạt động cho các sự cố sau này và gateway start bật lại một cách bình thường mà không cần chạy launchctl enable thủ công. Truyền --disable để ngăn KeepAlive và RunAtLoad một cách lâu dài, nhờ đó Gateway không khởi chạy lại cho đến lần chạy gateway start rõ ràng tiếp theo; hãy dùng tùy chọn này khi cần duy trì trạng thái dừng thủ công sau khi khởi động lại hệ thống.
  • Các lệnh vòng đời chấp nhận --json để dùng trong tập lệnh.
Xác thực và SecretRef tại thời điểm cài đặt
  • Khi xác thực bằng mã thông báo yêu cầu mã thông báo và gateway.auth.token được quản lý bằng SecretRef, gateway install xác thực rằng SecretRef có thể được phân giải nhưng không lưu mã thông báo đã phân giải vào siêu dữ liệu môi trường dịch vụ.
  • Nếu xác thực bằng mã thông báo yêu cầu mã thông báo nhưng SecretRef mã thông báo đã cấu hình không thể phân giải, quá trình cài đặt sẽ từ chối tiếp tục thay vì lưu văn bản thuần dự phòng.
  • Đối với xác thực bằng mật khẩu trên gateway run, nên dùng OPENCLAW_GATEWAY_PASSWORD, --password-file hoặc gateway.auth.password được hỗ trợ bởi SecretRef thay vì --password nội tuyến.
  • Trong chế độ xác thực được suy luận, OPENCLAW_GATEWAY_PASSWORD chỉ có trong shell không làm giảm yêu cầu về mã thông báo khi cài đặt; hãy dùng cấu hình lâu dài (gateway.auth.password hoặc env trong cấu hình) khi cài đặt một dịch vụ được quản lý.
  • Nếu cả gateway.auth.token và gateway.auth.password đều được cấu hình nhưng gateway.auth.mode chưa được đặt, quá trình cài đặt sẽ bị chặn cho đến khi chế độ được đặt rõ ràng.

Khám phá các Gateway (Bonjour)

gateway discover quét tìm các tín hiệu Gateway (_openclaw-gw._tcp).

  • DNS-SD đa hướng: local.
  • DNS-SD đơn hướng (Bonjour diện rộng): chọn một miền (ví dụ: openclaw.internal.) và thiết lập DNS phân tách cùng một máy chủ DNS; xem Bonjour.

Chỉ các Gateway đã bật tính năng khám phá Bonjour (mặc định) mới quảng bá tín hiệu.

Các gợi ý TXT trên mỗi tín hiệu: role (gợi ý vai trò Gateway), transport (gợi ý phương thức truyền tải, ví dụ: gateway), gatewayPort (cổng WebSocket, thường là 18789), tailnetDns (tên máy chủ MagicDNS, khi khả dụng), gatewayTls / gatewayTlsSha256 (TLS đã bật + dấu vân tay chứng chỉ). sshPort và cliPath chỉ được công bố trong chế độ khám phá đầy đủ (discovery.mdns.mode: "full"; mặc định là "minimal", chế độ này lược bỏ chúng — khi đó, máy khách mặc định dùng cổng 22 cho đích SSH).

gateway discover

bash
openclaw gateway discover
"--timeout
--jsonboolean

Đầu ra máy có thể đọc được (đồng thời tắt định dạng và biểu tượng tiến trình).

Ví dụ:

bash
openclaw gateway discover --timeout 4000openclaw gateway discover --json | jq '.beacons[].wsUrl'

Liên quan

Was this useful?
On this page

On this page