OpenClaw Triage: Sanitized Diagnostics and Agent Handoff
Learn how to run openclaw triage for non-destructive Doctor checks, generate sanitized diagnostics archives, and create size-limited Markdown prompts for debugging agents. Ideal for OpenClaw operators troubleshooting their setup.
Read this when
- OpenClaw is misbehaving and you want an agent-ready debugging prompt
- An update failed and you want a local coding agent to repair it
- You need a sanitized diagnostics bundle without starting an agent
openclaw triage
Use triage to execute non-destructive Doctor checks, pull together the current sanitized diagnostics archive, and produce a size-limited Markdown prompt intended for an agent that is debugging this OpenClaw setup.
openclaw triage
Within the prompt, you get the OpenClaw version, the platform, the Node.js version, the prioritized Doctor findings along with repair suggestions, and the path to the diagnostics archive. That archive holds sanitized configuration, Gateway status and health snapshots, operational log summaries, and any available stability diagnostics. Even when the Gateway cannot be reached, triage still writes the prompt and notes why the archive is missing.
Secrets, tokens, raw chat payloads, and raw logs are left out. Paths shown in the prompt are relative to ~ or $OPENCLAW_STATE_DIR; the saved prompt path, the archive path, and the printed handoff commands keep the real absolute paths your shell needs. Doctor checks are only advisory and never apply fixes.
Agent handoff
When run in an interactive terminal, triage detects which agent handoff routes exist on the current machine and asks you to pick one. A configured OpenClaw embedded agent is listed first, then Claude Code if claude is on PATH, Codex CLI if codex is on PATH, and finally an option that simply prints the commands.
Selecting Claude Code or Codex launches its interactive session directly with the generated prompt. Picking the embedded agent first verifies the configured model through a live inference check, then executes a single OpenClaw agent turn. --run explicitly requests that same verified embedded route.
On Windows, agents installed only as .cmd or .bat command shims show up in the manual handoff commands rather than in the direct-launch picker.
For non-interactive sessions and the print-only choice, these manual handoff commands are provided instead:
claude "$(cat '<prompt-path>')"
codex exec - < '<prompt-path>'
openclaw triage --run
JSON output also contains detectedAgents, which lists the external agents found on PATH. Neither JSON output nor non-interactive sessions ever start an agent.
Output and exit codes
The prompt gets written to logs/support/ inside the state directory with owner-only permissions, next to the diagnostics archive when one was generated. Both paths are printed, and --json returns them along with finding counts broken down by severity.
A launched agent inherits the current environment, so it examines the same installation the prompt describes, including a custom OPENCLAW_STATE_DIR. Triage exits with the launched agent's exit code. If the agent fails to start, triage prints its manual command and exits non-zero. Choosing the embedded agent without a configured model reports the missing model and exits non-zero without running a turn.
Options
| Option | Effect |
|---|---|
--json | Output the prompt and archive paths, finding counts, detected agents, and commands. |
--no-export | Skip the diagnostics archive and only produce the debugging prompt. |
--run | Run one embedded agent turn after verifying the model in an interactive terminal. |
--json cannot be used together with --run.
Related: Doctor, Gateway, and Troubleshooting.