Gateway CLI

Gateway là WebSocket server của OpenClaw (channel, node, session, hook).

Các lệnh con trong trang này nằm dưới openclaw gateway ….

Tài liệu liên quan:

Chạy Gateway

Chạy Gateway process ở local:

openclaw gateway

Alias chạy foreground:

openclaw gateway run

Lưu ý:

  • Mặc định, Gateway từ chối khởi động trừ khi gateway.mode=local được set trong ~/.openclaw/openclaw.json. Dùng --allow-unconfigured cho các lần chạy ad-hoc/dev.
  • Binding ra ngoài loopback mà không có auth sẽ bị chặn (cơ chế bảo vệ).
  • SIGUSR1 kích hoạt restart trong process khi được phép (bật commands.restart hoặc dùng gateway tool/config apply/update).
  • Handler SIGINT/SIGTERM dừng gateway process, nhưng không khôi phục trạng thái terminal tùy chỉnh. Nếu các bạn wrap CLI với TUI hoặc raw-mode input, hãy khôi phục terminal trước khi thoát.

Tùy chọn

  • --port <port>: WebSocket port (mặc định từ config/env; thường là 18789).
  • --bind <loopback|lan|tailnet|auto|custom>: chế độ bind listener.
  • --auth <token|password>: override chế độ auth.
  • --token <token>: override token (cũng set OPENCLAW_GATEWAY_TOKEN cho process).
  • --password <password>: override password (cũng set OPENCLAW_GATEWAY_PASSWORD cho process).
  • --tailscale <off|serve|funnel>: expose Gateway qua Tailscale.
  • --tailscale-reset-on-exit: reset Tailscale serve/funnel config khi shutdown.
  • --allow-unconfigured: cho phép gateway khởi động mà không cần gateway.mode=local trong config.
  • --dev: tạo dev config + workspace nếu thiếu (bỏ qua BOOTSTRAP.md).
  • --reset: reset dev config + credential + session + workspace (cần --dev).
  • --force: kill listener hiện tại trên port đã chọn trước khi khởi động.
  • --verbose: log chi tiết.
  • --claude-cli-logs: chỉ hiện claude-cli log trong console (và bật stdout/stderr của nó).
  • --ws-log <auto|full|compact>: kiểu log websocket (mặc định auto).
  • --compact: alias cho --ws-log compact.
  • --raw-stream: log raw model stream event ra jsonl.
  • --raw-stream-path <path>: đường dẫn jsonl cho raw stream.

Truy vấn Gateway đang chạy

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

Chế độ output:

  • Mặc định: dễ đọc cho người (có màu trong TTY).
  • --json: JSON cho máy đọc (không có styling/spinner).
  • --no-color (hoặc NO_COLOR=1): tắt ANSI nhưng giữ layout cho người.

Tùy chọn chung (nếu được hỗ trợ):

  • --url <url>: Gateway WebSocket URL.
  • --token <token>: Gateway token.
  • --password <password>: Gateway password.
  • --timeout <ms>: timeout/budget (khác nhau tùy lệnh).
  • --expect-final: đợi response “final” (agent call).

gateway health

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

gateway status

gateway status hiển thị Gateway service (launchd/systemd/schtasks) cộng với RPC probe tùy chọn.

openclaw gateway status
openclaw gateway status --json

Tùy chọn:

  • --url <url>: override probe URL.
  • --token <token>: token auth cho probe.
  • --password <password>: password auth cho probe.
  • --timeout <ms>: probe timeout (mặc định 10000).
  • --no-probe: bỏ qua RPC probe (chỉ xem service).
  • --deep: scan cả service ở system-level.

gateway probe

gateway probe là lệnh “debug mọi thứ”. Nó luôn probe:

  • remote gateway đã config của các bạn (nếu có), và
  • localhost (loopback) ngay cả khi remote đã được config.

Nếu nhiều gateway có thể kết nối được, nó sẽ in ra tất cả. Nhiều gateway được hỗ trợ khi các bạn dùng profile/port riêng biệt (ví dụ: rescue bot), nhưng hầu hết cài đặt vẫn chỉ chạy một gateway duy nhất.

openclaw gateway probe
openclaw gateway probe --json

Remote qua SSH (tương đương Mac app)

Chế độ “Remote over SSH” của macOS app dùng local port-forward để remote gateway (có thể chỉ bind với loopback) trở nên có thể kết nối tại ws://127.0.0.1:<port>.

Tương đương CLI:

openclaw gateway probe --ssh user@gateway-host

Tùy chọn:

  • --ssh <target>: user@host hoặc user@host:port (port mặc định là 22).
  • --ssh-identity <path>: identity file.
  • --ssh-auto: chọn gateway host được phát hiện đầu tiên làm SSH target (chỉ LAN/WAB).

Config (tùy chọn, dùng làm mặc định):

  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method>

Helper RPC cấp thấp.

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

Quản lý Gateway service

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

Lưu ý:

  • gateway install hỗ trợ --port, --runtime, --token, --force, --json.
  • Các lệnh lifecycle chấp nhận --json cho scripting.

Khám phá gateway (Bonjour)

gateway discover quét tìm Gateway beacon (_openclaw-gw._tcp).

  • Multicast DNS-SD: local.
  • Unicast DNS-SD (Wide-Area Bonjour): chọn một domain (ví dụ: openclaw.internal.) và setup split DNS + DNS server; xem /gateway/bonjour

Chỉ các gateway có Bonjour discovery được bật (mặc định) mới quảng bá beacon.

Bản ghi Wide-Area discovery bao gồm (TXT):

  • role (gợi ý vai trò gateway)
  • transport (gợi ý transport, ví dụ gateway)
  • gatewayPort (WebSocket port, thường là 18789)
  • sshPort (SSH port; mặc định là 22 nếu không có)
  • tailnetDns (MagicDNS hostname, khi có)
  • gatewayTls / gatewayTlsSha256 (TLS được bật + cert fingerprint)
  • cliPath (gợi ý tùy chọn cho remote install)

gateway discover

openclaw gateway discover

Tùy chọn:

  • --timeout <ms>: timeout cho mỗi lệnh (browse/resolve); mặc định 2000.
  • --json: output cho máy đọc (cũng tắt styling/spinner).

Ví dụ:

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