On this page
On this page
CLI commands
Triage
openclaw triage
Collect sanitized diagnostics and open a coding agent on this machine to diagnose, repair, and verify this OpenClaw installation.
In an interactive terminal, triage starts the first directly launchable agent on PATH in this detection order: Codex (codex), Claude Code (claude), Pi (pi), OpenCode (opencode), Muse Code (muse), Grok Build (grok), Cursor (cursor-agent), Kimi Code (kimi), Qwen Code (qwen), then Google Antigravity CLI (agy). When both Codex and Claude Code are available, Codex takes priority unless you select an agent with --agent. An explicit openclaw triage invocation prints the selected agent and passes a bounded repair prompt directly, without a picker or launch confirmation. The agent uses its existing authentication and native execution policy.
Google Antigravity CLI uses agy --prompt-interactive to start with the repair prompt and keep the session open. Install and sign in to the official CLI first. Triage uses Antigravity's existing authentication and permission settings; it does not import Google credentials or bypass tool approvals.
Cursor selection uses --agent cursor and requires the cursor-agent alias installed by Cursor's CLI installer. Triage does not use the cursor editor command or the generic agent alias, which Grok also installs.
Kimi Code uses kimi --prompt for a single repair turn. Its native prompt mode uses automatic permissions without approval prompts; triage prints this policy before launch or manual handoff. Kimi Code does not expose an interactive initial-prompt flag. Qwen Code uses qwen --prompt-interactive to start with the repair prompt and keep the interactive session open, including its normal tool approvals.
Claude Code starts with --safe-mode when supported, which disables custom hooks, plugins, skills, MCP servers, and project instructions while retaining authentication and built-in tools. This prevents project startup hooks, such as dependency installation, from delaying the repair prompt. When the installed CLI does not advertise safe-mode support, triage prints a notice and runs claude -p with normal customization settings. Printed manual commands also use Claude's normal customization settings, including plugins and MCP servers.
Choose a particular agent with --agent, or collect diagnostics without starting one with --json or --non-interactive:
The prompt includes the OpenClaw version, platform, Node.js version, prioritized Doctor findings with repair hints, and the diagnostics archive path. The archive contains sanitized config, best-effort Gateway status and health snapshots, operational log summaries, and available stability diagnostics. For a custom state directory or config path that does not select a native Gateway service, triage skips the native service status snapshot. If the Gateway is unreachable, triage still writes the archive with available local diagnostics and records snapshot failures inside it. Doctor or export failures are recorded in the prompt so the agent can still investigate.
The diagnostics archive excludes secrets, tokens, raw chat payloads, and raw logs. Failed-update prompts include bounded, sanitized diagnostic excerpts, with secrets and local paths redacted before truncation. Paths inside the prompt are shown relative to ~ or $OPENCLAW_STATE_DIR. The saved prompt path, archive path, and printed handoff commands retain the real absolute paths needed by your shell. Diagnostic collection is read-only. A launched agent is asked to repair autonomously within its existing permissions and preserve configuration, history, and databases.
The archive's config summary counts agent, plugin, and channel entries declared in the saved file. Shared channel settings and $include directives are excluded from those counts. Diagnostics do not expand included files.
In sanitized config and snapshots, map keys recognized as private identifiers (such as phone numbers, email addresses, user/chat IDs, and tokens) become opaque numbered placeholders. Known private config maps, including per-DM overrides (dms), also hide identifiers without a recognizable text pattern. Repeated identifier keys share a placeholder within the archive; ordinary field names remain intact. Placeholders contain no hash or recoverable portion of the identifier.
Failed update recovery
Interactive update recovery uses this same handoff after the updater releases its maintenance state. It starts from the captured update failure. It defers fresh Doctor checks and archive collection to the repair agent, so checks against the broken installation do not delay the handoff. The agent starts in the operator's captured working directory, or their OS home if that directory was removed or became inaccessible. Absolute installation selectors still identify the state, config, and default workspace to repair, even when the state directory cannot be accessed or created.
Before an automatic interactive launch, OpenClaw shows what it will run. It shows the selected binary, or the embedded OpenClaw agent using your configured model. It also shows the saved prompt path when available, and a notice that it uses your own account or tokens. OpenClaw then asks for confirmation. Only an affirmative Yes starts the agent. Enter, n, cancellation, or 30 seconds without an answer skips the launch, prints one manual next step for the selected agent, and preserves diagnostics and the failed update's exit status. To choose another external agent, run openclaw triage --agent codex or another supported --agent value. This replaces the earlier timeout-as-Yes default; explicit standalone triage keeps its existing behavior.
The prompt preserves the original error, before and after versions, and recorded recovery state ahead of current Doctor findings. It includes up to three failed or interrupted steps, excluding advisory Doctor results, with bounded excerpts from both stderr and stdout. It also retains bounded plugin failures and the terminal Doctor warning. The failure record is limited to 4 KiB and the whole prompt to 8 KiB. A healthy Doctor check does not erase the failed attempt, and an absent restart-safety verdict remains unknown.
Updates using --yes, JSON output, or a session without a TTY never start a repair agent. They save triage diagnostics and print the explicit opt-in command openclaw triage --run --update-result <path>. Managed handoff updates and foreground gateway run startup failures also collect diagnostics only. Initial argument, ownership, and installation refusals retain their existing output. Standalone diagnostics preserve a pending failed-update notification as context. Embedded validation selects current ledger history through the resolution owner. These reads do not consume the notification or create a state database. Delivery routes and continuation instructions are excluded.
Use --update-result <path> to include an updater's saved failure artifact. Triage requires a regular file (or a symlink to one), rejects FIFOs without waiting for a writer, and reads at most 8 KiB of valid UTF-8 JSON before validating the failure record. Its printed embedded handoff command uses a sanitized support export, so it remains usable after a temporary updater input is deleted. Interactive handoffs with a captured failure defer fresh diagnostics. JSON and forced non-interactive runs still collect them.
The repair prompt directs the agent to preserve migrated state, investigate before rolling back or restarting, and verify the intended installation plus Gateway health and RPC connectivity after repair. A successful agent exit does not change the original updater failure into a successful update.
Installation target and embedded handoff
Triage captures the diagnosed installation's resolved state directory, exact config path, and default workspace, including custom paths and named profiles. Local shell commands receive these as OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, and OPENCLAW_WORKSPACE_DIR. Archive references and default workspace checks therefore resolve against the diagnosed installation, even when its selectors were implicit. An authored workspace in the installation's config still takes precedence over its default workspace. The embedded agent keeps its own config snapshot, sessions, execution cwd, and temporary run state separate. In-process config and session tools refer to that temporary run. Use local shell commands to inspect or repair the diagnosed installation.
openclaw triage --run requests up to one bounded embedded repair turn in an interactive terminal. Inference uses the system-agent owner's default model, then its configured model.fallbacks, then other configured agents' authenticated routes. Models that explicitly lack tool support and routes without usable authentication are skipped. If no route works, triage reports that embedded repair is unavailable. Use a saved handoff command, or repair model setup with openclaw onboard.
For standalone installation triage, the loop runs Doctor lint before and after the turn, using the number of error findings to measure improvement. An initially healthy installation prints already resolved without starting inference. Triage allows one turn, ten minutes total, five minutes for the turn, and 40 tool calls. More error findings after a turn report the installation as unrepaired.
For a recorded update failure, including Doctor finalization, clean Doctor lint is insufficient. Triage requires a completed updater outcome and verifies the installed package or Git runtime, Doctor findings, and the managed Gateway's installation and readiness. An explicitly supplied failure artifact keeps strict checks against its recorded target. Plain triage accepts a later successful update to the same or a newer version and verifies that current completion's installation, so historical failures do not pin an installation to an older release. Plugin failures also require plugin health. A later verified rollback to the same or a newer version also preserves that recovery: plain triage checks the rollback run's own previous and restored identities, recorded package restoration, and current installation. Explicit artifacts still require rollback to their original version. Triage preserves historical failed runs; it never treats the surviving after.version in a failed result as the requested target.
Package updates record their resolved registry version. Git updates record the selected commit and available manifest version during target inspection, before candidate validation or activation. Triage can verify a Git target with either recorded identity; it checks all identities that are present. A legacy Git record containing only channel/tag selectors such as dev/latest does not establish a resolved target.
Plain triage --run validates update history through the resolution owner, even when no restart notification remains or newer previews appear. Repair acknowledgements clear historical abandoned-run blockers but still require fresh Doctor checks; they cannot hide current configuration errors. Later previews and acknowledged abandoned runs cannot replace a completed update either. Doctor/config failures require the same updater-recorded completion as other update failures. Pending plugin state migrations remain unresolved and appear in the verdict until their migration owner records completion, including after a newer successful update and when no restart notification remains.
An explicit --update-result artifact or pending notification without a run identity or recorded target remains unrepaired, including Doctor/config failures. Triage reports that it cannot establish the update target and directs you to inspect openclaw update status --json, then run openclaw update repair. It never falls back to a healthy Doctor verdict for an uncorrelated update failure. An intentionally stopped or unmanaged Gateway cannot supply managed-service verification. When the initial checks prove resolution, the human output says already resolved; after a repair turn, it says repaired only when the same checks pass. The worker protocol retains its existing repaired and unrepaired statuses. An agent's successful exit or claim that it fixed the problem is not evidence of resolution.
Pending package activation also prevents triage from reporting resolution, even
when Doctor passes, the last run succeeded, and no recovery sets are listed.
For a missing or changed handoff lease database after a reboot, triage directs you
to openclaw update repair before retrying the update. Run repair from a CLI
containing the lease recovery fix;
an older blocked CLI may need the manual installation hop described there.
If triage has no resolution predicate for a recorded failure, it says so and names
openclaw update repair as the next step.
Post-turn Doctor checks run only after the executor confirms cleanup. If cleanup fails or times out, repair reports failure, retains execution state, and refuses another repair in that CLI process. Inspect the diagnostics and stop any remaining work before retrying from a new process.
The operator owns the update or the explicit --run request. Embedded repair therefore replaces interactive exec approval with a prompt-free run, scoped to the installation or staged candidate root (fs.workspaceOnly: true). It preserves safe-bin and tool allowlists. It never overrides explicit exec or repair-tool denies. It refuses configured sandbox, node, and remote execution routes instead of redirecting them onto the host, and does not launch external coding-agent CLIs. An explicit deny reports exec-denied-by-policy. Use openclaw triage for an external handoff. The saved execution policy is unchanged.
The repair prompt instructs the agent to change only the installation or staged candidate root and use the pinned OpenClaw state for diagnostics. It forbids editing credentials or auth stores, deleting state or databases, package-manager writes outside the target root, and starting, stopping, or restarting services or the Gateway. Filesystem tools enforce the workspace boundary. Host commands follow the prompt's scope contract and are not an OS sandbox. Allowed checks include openclaw doctor --lint --json, openclaw doctor --fix, and openclaw health --json. The repair loop does not activate updates, restart services, take snapshots, or undo files.
Each turn is asked to end with a machine-readable line:
The status may be fixed, partial, or not-fixed. A missing or malformed line falls back to a bounded summary of the final text. Owner validation remains authoritative. The failure context and repair instructions share the 8 KiB prompt limit.
On Windows, recognized npm .cmd and .bat shims launch their Node.js or native executable entrypoint directly, preserving the interactive terminal. Node.js entrypoints require the running Node.js runtime or node.exe on PATH. Custom wrappers that require a shell remain manual handoffs. An explicit --agent that is missing or manual-only exits non-zero without selecting a different agent.
Manual handoff
Non-interactive sessions save diagnostics without starting an agent. Human output prints one next step for the explicitly selected or first detected coding agent. If no coding agent is detected, it explains how to install one and rerun triage. Windows wrappers that require a shell remain available as manual commands. JSON output retains all external handoff commands and the explicit embedded route. Saved external prompts are read from stdin or, for Grok and Muse, with --prompt-file. Kimi Code and Antigravity CLI receive a short instruction to read the saved prompt rather than piping it to stdin. On macOS and Linux, the commands look like this:
A captured update failure adds --update-result <saved-failure-path> to the embedded command. The external commands use their agent's native tool policy, including Kimi Code's automatic permissions. Antigravity's saved command starts an interactive session. Triage adds no permission overrides. Use openclaw triage --agent <name> to start a session; Kimi Code remains a single prompt run.
Printed Windows commands target PowerShell, including Windows PowerShell 5.1. They read saved prompts as UTF-8, preserve literal paths, and restore your installation selectors after the command completes. WSL uses POSIX shell commands.
JSON output also includes detectedAgents, listing the external agents found on PATH. Standalone triage with JSON output, non-TTY sessions, or --non-interactive never starts an agent, even with --agent. The Codex command works outside a Git checkout. It does not change Codex sandbox or approval settings.
Unattended failure diagnostics
Unattended updates, managed update handoffs, and recorded foreground Gateway startup failures save diagnostics without starting an agent. Update settlement and service recovery run first. After package replacement, the installed CLI collects diagnostics with --non-interactive or --json. The failure output and original exit status remain unchanged. Diagnostics go to stderr when the update uses JSON output.
The output names the saved failure artifact and the explicit opt-in command:
Run that command in an interactive terminal on the Gateway host, preserving the printed installation selectors. It uses your configured inference and the existing embedded repair behavior. Interactive updates still offer Diagnose update failure and require an affirmative Yes before starting the agent.
A missing or incompatible installed CLI leaves the saved failure artifact and manual guidance. Existing ownership, schema, startup cleanup, and cancellation refusals retain their behavior. A native recovery handoff admitted by an older version keeps its authority and cleanup checks across an upgrade, but the new CLI collects diagnostics only. Live or uncertain claims are left for their lifecycle owner; do not delete them while prior work may still be running.
Output and exit codes
The prompt is written to logs/support/ inside the state directory with owner-only permissions, alongside the diagnostics archive and sanitized update failure when available. Prompt and archive paths are printed, and --json returns them plus finding counts by severity and handoff commands.
If a support artifact cannot be saved, triage reports the storage error. It still passes the in-memory prompt to an available interactive agent, including an explicitly requested embedded turn. It does not report a saved prompt path for a failed write. Standalone JSON output, non-interactive sessions, and sessions without a launchable handoff retain a non-zero artifact failure. These explicit diagnostic runs never start an agent automatically.
A launched external agent inherits the current environment with the captured installation's state, config, and default workspace selectors pinned. The printed commands pin the same selectors and preserve shell quoting. External agents still control their own shell environment and execution policy. Keep the handoff on this machine. Triage exits with the launched agent's exit code. If the agent cannot start, triage prints its manual command and exits non-zero. It does not try another provider. A failed embedded inference check, unsupported execution route, or --run without an interactive terminal also exits non-zero. Saved prompts and manual handoff commands remain available.
Embedded repair exits with 0 when its validation proves resolution, 2 when a time budget stops the run, and 1 for other incomplete or unavailable repairs. An improvement that leaves errors or an unverified update is still incomplete.
Options
| Option | Effect |
|---|---|
--json |
Emit prompt and archive paths, finding counts, detected agents, and commands. |
--no-export |
Skip the diagnostics archive; still prepare the prompt and use the selected handoff route. |
--agent <name> |
Select agy, claude, codex, cursor, grok, kimi, muse, opencode, pi, or qwen instead of automatic detection. |
--run |
Run one bounded embedded repair turn with installation or update-resolution validation. |
--non-interactive |
Prepare diagnostics without prompting or starting an agent, including on a terminal. |
--update-result <path> |
Include the bounded update-failure JSON diagnostics artifact written by the updater. |
--run cannot be combined with --json, --non-interactive, or --agent.
Related: Doctor, Gateway, and Troubleshooting.
