Summary

• Problem: gateway-backed CLI commands that advertise --json could exit on transport close/timeout without writing JSON to stdout.
• Why it matters: health-check and device automation scripts had to parse stderr even after opting into machine-readable output.
• What changed: added a shared GatewayTransportError JSON serializer and used it for JSON-mode health, gateway health, and devices list transport failures.
• What did NOT change (scope boundary): non-JSON command behavior, non-transport exceptions, gateway probe output, and local pairing fallback behavior are unchanged.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Gateway-backed --json commands emit no JSON on connection failure #79108
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: JSON-mode gateway-backed commands now emit a structured { "ok": false, "error": ..., "gateway": ... } payload when the gateway transport closes or times out before returning an RPC result.
• Real environment tested: macOS local source checkout, Node v25.8.2, pnpm v10.33.2.
• Real stopped/unavailable gateway target: ws://127.0.0.1:9 with a redacted proof token.
• Exact steps or command run after this patch:
  • OPENCLAW_GATEWAY_URL=ws://127.0.0.1:9 OPENCLAW_GATEWAY_TOKEN=proof-token pnpm openclaw health --json --timeout 500
  • pnpm openclaw gateway health --url ws://127.0.0.1:9 --token proof-token --json --timeout 500
  • pnpm openclaw devices list --url ws://127.0.0.1:9 --token proof-token --json --timeout 500
• Evidence after fix: redacted stdout from the real unavailable-gateway commands. Each command also exited non-zero (ELIFECYCLE Command failed with exit code 1).

health --json redacted output:

{
  "ok": false,
  "error": {
    "type": "gateway_transport_error",
    "kind": "closed",
    "message": "gateway closed (1006 abnormal closure (no close frame)): no close reason",
    "code": 1006,
    "reason": "no close reason"
  },
  "gateway": {
    "url": "ws://127.0.0.1:9",
    "urlSource": "env OPENCLAW_GATEWAY_URL"
  }
}

gateway health --json and devices list --json produced the same structured error shape with:

{
  "gateway": {
    "url": "ws://127.0.0.1:9",
    "urlSource": "cli --url"
  }
}

• Observed result after fix: each command wrote structured JSON to stdout and exited non-zero instead of falling through to stderr-only handling.
• What was not tested: live Windows npm install repro from the issue.

Root Cause (if applicable)

callGateway already produced typed GatewayTransportError instances, but affected JSON commands awaited the gateway RPC before reaching their success-only JSON output branch. The typed transport error escaped to the generic CLI error path, which wrote human-readable stderr and exited without stdout JSON.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • src/gateway/call.test.ts
  • src/commands/health.test.ts
  • src/cli/gateway-cli.coverage.test.ts
  • src/cli/devices-cli.test.ts
• Scenario the test should lock in: JSON-mode command paths serialize typed gateway transport close/timeout failures instead of falling through to stderr-only handling.

User-visible / Behavior Changes

When --json is requested, transport-level gateway close/timeout failures now produce stdout JSON before exiting with code 1.

Diagram (if applicable)

N/A

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local source checkout
• Model/provider: N/A
• Integration/channel (if any): Gateway CLI transport failure handling
• Relevant config (redacted): loopback gateway URL and proof token only

Steps

1. Run JSON-mode gateway-backed commands against an unavailable loopback gateway.
2. Inspect stdout JSON and exit behavior.

Expected

• Commands write structured JSON with ok: false, transport kind, message/code/timeout details, and gateway target metadata.
• Commands still exit non-zero.

Actual

• Real CLI proof above confirms the expected JSON payload and non-zero exit behavior for health --json, gateway health --json, and devices list --json.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: shared transport-error serialization, health --json, gateway health --json, devices list --json, and status/health wrapper option forwarding.
• Edge cases checked: non-transport errors are not converted, non-JSON mode keeps the existing human error path, and explicit-url device listing still skips local fallback for plain pairing errors.
• What you did not verify: live Windows shell repro.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: scripts may have expected empty stdout on JSON transport failures.
  • Mitigation: this only changes commands when --json is explicitly requested, matching the documented machine-readable contract.

Changelog

• Added an Unreleased changelog entry for JSON gateway transport failures.

Additional Validation Note

• pnpm exec vitest run src/gateway/call.test.ts src/commands/health.test.ts src/cli/gateway-cli.coverage.test.ts src/cli/devices-cli.test.ts --reporter=dot: passed (Test Files 6 passed, Tests 288 passed).
• pnpm exec vitest run src/cli/program/register.status-health-sessions.test.ts --reporter=dot: passed (Test Files 1 passed, Tests 21 passed).
• pnpm tsgo:core: passed.
• pnpm tsgo:core:test: passed.
• pnpm exec oxfmt --check --threads=1 src/gateway/call.ts src/gateway/call.test.ts src/commands/health.ts src/commands/health.test.ts src/cli/gateway-cli/call.ts src/cli/gateway-cli/register.ts src/cli/gateway-cli.coverage.test.ts src/cli/devices-cli.ts src/cli/devices-cli.test.ts CHANGELOG.md: passed.
• git diff --check: passed.