openclaw/docs/cli/crestodian.md

summary, read_when, title

summary	read_when	title
CLI reference and security model for Crestodian, the configless-safe setup and repair helper	You run openclaw with no command after setup and want to understand Crestodian You need a configless-safe way to inspect or repair OpenClaw You are designing or enabling message-channel rescue mode	Crestodian

openclaw crestodian

Crestodian is OpenClaw's local setup, repair, and configuration helper. It stays reachable when the normal agent path is broken: it can run when openclaw.json is missing or invalid, the Gateway is down, plugin command registration is unavailable, or no agent is configured yet.

When it starts

Running openclaw with no subcommand routes based on config state:

• Config missing, or exists with no authored settings (empty, or only $schema/meta keys): starts classic onboarding.
• Config exists but fails validation: starts Crestodian.
• Config exists and is valid: opens the normal agent TUI (against a reachable configured Gateway, or locally if none is reachable). Use /crestodian inside the TUI, or run openclaw crestodian directly, to reach Crestodian.

Running openclaw crestodian always starts Crestodian explicitly, regardless of config state. openclaw --help and openclaw --version keep their normal fast paths.

Noninteractive bare openclaw (no TTY) exits with a short message instead of printing root help: it points to non-interactive onboarding on a fresh install, to openclaw crestodian --message "status" when config is invalid, or to openclaw agent --local ... when config is valid.

openclaw onboard --modern starts Crestodian as the modern onboarding preview. Plain openclaw onboard keeps classic onboarding.

What Crestodian shows

Interactive Crestodian opens the same TUI shell as openclaw tui, with a Crestodian chat backend. The startup greeting covers:

• config validity and the default agent
• the model or deterministic planner path Crestodian is using
• Gateway reachability from the first startup probe
• the next recommended debug action

It does not dump secrets or load plugin CLI commands just to start.

Use status for the detailed inventory: config path, docs/source paths, local CLI probes, API-key presence, agents, model, and Gateway details.

Crestodian uses the same reference discovery as regular agents: in a Git checkout it points at local docs/ and the source tree; in an npm install it uses bundled docs and links to https://github.com/openclaw/openclaw, with guidance to check source when docs are not enough.

Examples

openclaw
openclaw crestodian
openclaw crestodian --json
openclaw crestodian --message "models"
openclaw crestodian --message "validate config"
openclaw crestodian --message "setup workspace ~/Projects/work model openai/gpt-5.5" --yes
openclaw crestodian --message "set default model openai/gpt-5.5" --yes
openclaw onboard --modern

Inside the Crestodian TUI:

status
health
doctor
doctor fix
validate config
setup
setup workspace ~/Projects/work model openai/gpt-5.5
config set gateway.port 19001
config set-ref gateway.auth.token env OPENCLAW_GATEWAY_TOKEN
gateway status
restart gateway
agents
create agent work workspace ~/Projects/work
models
set default model openai/gpt-5.5
plugins list
plugins search slack
plugin install clawhub:openclaw-codex-app-server
plugin uninstall openclaw-codex-app-server
talk to work agent
talk to agent for ~/Projects/work
audit
quit

Operations and approval

Crestodian uses typed operations instead of editing config ad hoc.

Read-only, run immediately: show overview, list agents, list installed plugins, search ClawHub plugins, show model/backend status, run status/health checks, check Gateway reachability, run doctor without interactive fixes, validate config, show the audit-log path.

Persistent, require conversational approval (or --yes for a direct command): write config, config set, config set-ref, setup/onboarding bootstrap, change the default model, start/stop/restart the Gateway, create agents, install or uninstall plugins, run doctor repairs that rewrite config or state.

Applied writes are recorded in ~/.openclaw/audit/crestodian.jsonl. Discovery is not audited; only applied operations and writes are.

Setup bootstrap

setup is the chat-first onboarding bootstrap. It writes only through typed config operations and asks for approval first.

setup
setup workspace ~/Projects/work
setup workspace ~/Projects/work model openai/gpt-5.5

When no model is configured, setup picks the first usable backend in this order and tells you what it chose:

1. Existing explicit model, if already configured.
2. OPENAI_API_KEY -> openai/gpt-5.5
3. ANTHROPIC_API_KEY -> anthropic/claude-opus-4-8
4. Claude Code CLI -> claude-cli/claude-opus-4-8
5. Codex -> openai/gpt-5.5 through the Codex app-server harness

If none are available, setup still writes the default workspace and leaves the model unset. Install or log into Codex/Claude Code, or expose OPENAI_API_KEY/ANTHROPIC_API_KEY, then run setup again.

Model-assisted planner

Crestodian always starts in deterministic mode. For fuzzy commands the deterministic parser does not understand, it can make one bounded planner turn through OpenClaw's normal runtime paths, using the configured OpenClaw model. If none is usable yet, it falls back to a local runtime already present on the machine:

• Claude Code CLI: claude-cli/claude-opus-4-8
• Codex app-server harness: openai/gpt-5.5

The planner cannot mutate config directly; it must translate the request into one of Crestodian's typed commands, and normal approval/audit rules apply. Crestodian prints the model it used and the interpreted command before running anything. Fallback planner turns are temporary, tool-disabled where the runtime supports it, and use a temporary workspace/session.

Message-channel rescue mode never uses the model-assisted planner. Remote rescue stays deterministic so a broken or compromised normal agent path cannot be used as a config editor.

Switching to an agent

Use a natural-language selector to leave Crestodian and open the normal TUI:

talk to agent
talk to work agent
switch to main agent

openclaw tui, openclaw chat, and openclaw terminal open the normal agent TUI directly; they do not start Crestodian. After switching into the normal TUI, /crestodian returns to Crestodian, optionally with a follow-up request:

/crestodian
/crestodian restart gateway

Message rescue mode

Message rescue mode is the message-channel entrypoint for Crestodian: use it when your normal agent is dead but a trusted channel (for example WhatsApp) still receives commands.

Supported command: /crestodian <request>.

You, in a trusted owner DM: /crestodian status
OpenClaw: Crestodian rescue mode. Gateway reachable: no. Config valid: no.
You: /crestodian restart gateway
OpenClaw: Plan: restart the Gateway. Reply /crestodian yes to apply.
You: /crestodian yes
OpenClaw: Applied. Audit entry written.

Agent creation can also be queued locally or via rescue:

create agent work workspace ~/Projects/work model openai/gpt-5.5
/crestodian create agent work workspace ~/Projects/work

Remote rescue is an admin surface and must be treated like remote config repair, not normal chat.

Security contract for remote rescue:

• Disabled when sandboxing is active for the agent/session; Crestodian refuses remote rescue and points to local CLI repair.
• Default effective state is auto: allow remote rescue only in trusted YOLO operation, where the runtime already has unsandboxed local authority (tools.exec.security resolves to full and tools.exec.ask resolves to off, with sandbox mode off).
• Requires an explicit owner identity; no wildcard sender rules, open group policy, unauthenticated webhooks, or anonymous channels.
• Owner DMs only by default; group/channel rescue needs explicit opt-in.
• Plugin search and list are read-only. Plugin install is always local-only (blocked in rescue, even when otherwise enabled) because it downloads executable code. Plugin uninstall can be approved as a persistent rescue operation.
• Remote rescue cannot open the local TUI or switch into an interactive agent session; use local openclaw for agent handoff.
• Persistent writes still require approval, even in rescue mode.
• Every applied rescue operation is audited. Message-channel rescue records channel, account, sender, and source-address metadata; config-mutating operations also record config hashes before and after.
• Secrets are never echoed. SecretRef inspection reports availability, not values.
• If the Gateway is alive, rescue prefers Gateway typed operations; if it is dead, rescue uses only the minimal local repair surface that does not depend on the normal agent loop.

Config shape:

{
  "crestodian": {
    "rescue": {
      "enabled": "auto",
      "ownerDmOnly": true,
      "pendingTtlMinutes": 15,
    },
  },
}

• enabled: "auto" (default) allows rescue only when the effective runtime is YOLO and sandboxing is off; false never allows message-channel rescue; true explicitly allows rescue when owner/channel checks pass (still subject to the sandboxing denial).
• ownerDmOnly: restrict rescue to owner direct messages. Default true.
• pendingTtlMinutes: how long a pending rescue write stays open for /crestodian yes approval before expiring. Default 15.

Remote rescue is covered by the Docker lane:

pnpm test:docker:crestodian-rescue

Configless local planner fallback is covered by:

pnpm test:docker:crestodian-planner

An opt-in live channel command-surface smoke checks /crestodian status plus a persistent approval roundtrip through the rescue handler:

pnpm test:live:crestodian-rescue-channel

Configless setup through explicit Crestodian commands is covered by:

pnpm test:docker:crestodian-first-run

That lane starts with an empty state dir, verifies the modern onboard Crestodian entrypoint, sets the default model, creates an additional agent, configures Discord through a plugin enablement plus token SecretRef, validates config, and checks the audit log. QA Lab has a repo-backed scenario for the same Ring 0 flow:

pnpm openclaw qa suite --scenario crestodian-ring-zero-setup

Related

• CLI reference
• Doctor
• TUI
• Sandbox
• Security