The ClawDocx OpenClaw Command Reference

#CLI Overview

The openclaw command-line interface is your primary tool for managing your OpenClaw agent. It provides commands for controlling the Gateway, managing skills, scheduling tasks, diagnosing issues, and configuring every aspect of your agent.

#Global Options

The CLI reference documents these global flags, and notes that "Place command-specific options after their command name, for example openclaw status --json. Global options such as --profile can precede the command."

There is no global --workspace, --verbose or --quiet flag in that table. <command> --help still prints the authoritative current command surface, and the CLI reference sends you there for the current command list: "Run <command> --help for the authoritative, current list." State isolation is --profile <name> rather than a workspace path, and --json is a per-command flag: "On bounded reporting commands, --json reserves stdout for one JSON document." Individual commands define their own verbosity, for example openclaw health --verbose and openclaw status --verbose.

#openclaw gateway

The gateway command runs and manages the Gateway, which the docs describe as "OpenClaw's WebSocket server (channels, nodes, sessions, hooks)." Five pages document it, one per reader job: running, restart and supervision, query, service and discovery.

#gateway start

openclaw gateway install "installs and starts the service", and openclaw gateway start starts a service that is already installed. To run the Gateway in the foreground instead, use openclaw gateway or its "equivalent, explicit form" openclaw gateway run.

Options on the foreground run form:

There is no --foreground or --host flag. Foreground is the openclaw gateway run form, and the bind address is --bind plus gateway.customBindHost. The service subcommand start takes --json only.

Examples:

# Run the Gateway in the foreground
openclaw gateway run
# Run in the foreground on a custom port
openclaw gateway run --port 18800
# Install and start the managed service
openclaw gateway install
openclaw gateway start

#gateway stop

Stop the running Gateway. gateway stop "remains available when plugin configuration needs Doctor migration."

Options: --force, --json and --disable, which is "launchd only: suppress KeepAlive/RunAtLoad until next start". There is no --timeout <seconds> flag on stop.

#gateway restart

Stop and restart the Gateway.

Options: --force, --safe, --skip-deferral, --wait <duration>, --preserve-definition and --json. The safe form "asks the running Gateway to preflight active work and schedule one coalesced restart after work drains, bounded to 5 minutes." --preserve-definition "restarts only an inspectable native service, skips automatic definition repair, and checks health at the installed launcher's port", and it "cannot be combined with --safe or external supervision". There is no --clear-cache flag.

#gateway status

"Shows the Gateway service (launchd/systemd/schtasks) plus an optional connectivity/auth probe."

Options:

For the wider picture, openclaw status covers channels and sessions, and openclaw gateway health reads the Gateway's own HTTP probes: "/healthz is a liveness probe: it returns as soon as the server can answer HTTP", while "/readyz is stricter and stays red while startup plugin sidecars, channels, or configured hooks are still settling."

#Reading Gateway logs

There is no openclaw gateway logs. Logs have their own top-level command, openclaw logs, which will "Tail Gateway file logs over RPC. Works in remote mode."

Options:

There are no --last, --filter, --level or --since flags.

Examples:

# Stream live logs
openclaw logs --follow
# Read more history than the default
openclaw logs --limit 500 --max-bytes 500000
# Line-delimited JSON for tooling
openclaw logs --json

#openclaw doctor

"Health checks and quick fixes for the gateway, channels, plugins, skills, model routing, local state, and config migrations."

Options:

There is no --check <component> flag and no list of named components such as system, api or heartbeat to pass to one. Check selection is by check id under --lint, with --only and --skip. There is no --channel <name> flag either: "For channel-specific permissions, use the channel probes instead of doctor".

Examples:

# Full diagnostic
openclaw doctor
# Apply the recommended repairs
openclaw doctor --fix
# Read-only findings for a CI gate
openclaw doctor --lint --severity-min warning
# Machine-readable output for scripts
openclaw doctor --json
# Probe one channel instead
openclaw channels status --probe

#openclaw health

"Fetch a health snapshot from the running Gateway over WebSocket RPC (no direct channel sockets from the CLI)."

Options:

There are no --test-api <provider>, --all-workspaces or --quiet flags, and the page documents no table of healthy, unhealthy and degraded exit codes. What it documents instead is the snapshot's own field: "Top-level ok: true means the health RPC succeeded and the Gateway produced a snapshot. Queue warnings do not change it to false."

Without --verbose, "the Gateway can return a cached snapshot and refresh it in the background for the next caller."

Examples:

# Quick health check
openclaw health
# Force a live probe across every account and agent
openclaw health --verbose
# Machine-readable snapshot for scripts
openclaw health --json

#openclaw skills

Manage installed skills and interact with ClawHub.

#skills list

list is the "Default action when no subcommand is provided", so bare openclaw skills prints the same table. list, info and check "request the selected Gateway's authoritative skill inventory" rather than reading a directory directly.

Options:

There are no --category, --enabled or --disabled flags, and no built-in, community or custom categories. Skills are grouped by the root they were discovered in, from the workspace skills/ folder down to plugin skills.

#skills info

Print one skill's details.

info "resolves an exact skill name before a metadata key. Key, case-insensitive, and separator-normalized matches must identify one skill; ambiguous selectors fail instead of choosing discovery order." It also takes --json and --agent <id>.

#skills check

Report missing prerequisites.

check "reports missing prerequisites independently of agent exclusion: a skill excluded by the agent allowlist can also appear under Missing requirements." With --agent <id> it "Checks the selected agent's workspace and reports which ready skills are actually visible to that agent's prompt or command surface."

#skills search

Search ClawHub for skills.

Options:

Argument: [query...] is optional, and the skills CLI describes leaving it out as "Optional query; omit it to browse the ClawHub Trending skills feed."

There are no --category, --sort or --verified flags on openclaw skills search. Browse-style listing lives in the standalone ClawHub CLI: clawhub explore "Lists newest skills" and takes --limit <n> (1-200, default 25) and --sort newest|updated|rating|downloads|trending.

Examples:

# Search for weather skills
openclaw skills search weather
# Cap the result count and take machine-readable output
openclaw skills search --limit 20 --json
# Browse the ClawHub Trending feed
openclaw skills search
# Browse newest or trending skills with the ClawHub CLI
clawhub explore --sort trending --limit 20

#skills install

By default install, update and verify "target the active workspace skills/ directory; with --global, they target the shared managed skills directory."

Options:

There is no --local, --git, --skip-audit or --dry-run flag. Local and Git sources are expressed in the ref itself, and both "expect SKILL.md at the source root".

Examples:

# Install the latest version from ClawHub
openclaw skills install @owner/hacker-news-digest
# Install a specific version
openclaw skills install @owner/hacker-news-digest --version 2.0.0
# Install from a local directory containing SKILL.md
openclaw skills install ./my-skills/hacker-news-digest --as hn-digest
# Install from Git, optionally pinned to a ref
openclaw skills install git:owner/repo@main
# Install into the shared managed skills directory
openclaw skills install @owner/hacker-news-digest --global

#Removing a skill

There is no openclaw skills remove. The skills CLI page routes removal to the standalone ClawHub CLI: "Use the standalone ClawHub CLI to remove a ClawHub-tracked skill."

npm i -g clawhub
clawhub uninstall @owner/hacker-news-digest
clawhub --workdir ~/.openclaw uninstall @owner/hacker-news-digest

uninstall "Removes <workdir>/<dir>/<slug> and deletes the lockfile entry." It asks for confirmation interactively and requires --yes under --no-input. Point --workdir at the same root the skill was installed into: the agent workspace, or the state directory for a --global install.

#Enabling and disabling a skill

There are no openclaw skills enable or openclaw skills disable subcommands. Disabling is a config change under skills.entries.<name>.enabled in openclaw.json, where false "disables the skill even when bundled or installed."

{
  skills: {
    entries: {
      "hacker-news-digest": { enabled: false },
    },
  },
}

#skills update

openclaw skills update "updates ClawHub-tracked installs only."

Options:

There is no --check flag.

#skills verify

Ask ClawHub for a skill's trust envelope. This is the documented stand-in for the preview command older tutorials show.

verify "Prints ClawHub's clawhub.skill.verify.v1 JSON envelope by default", and --card "Prints the generated Skill Card Markdown instead of JSON", exiting non-zero when ClawHub returns a failing decision. It "reads the stored scan and does not start another scan", and for an installed skill it "uses .clawhub/origin.json for installed ClawHub skills, so it verifies the installed version against the registry it came from."

To read the files themselves before installing, use the ClawHub CLI's inspect, which "Fetches skill metadata and version files without installing":

clawhub inspect @owner/hacker-news-digest
clawhub inspect @owner/hacker-news-digest --files
clawhub inspect @owner/hacker-news-digest --file SKILL.md

#Validating a SKILL.md

There is no openclaw skills validate subcommand. The skills CLI page documents search, install, update, verify, list, info, check, curator, library and workshop, and no validate among them, so there is no documented way to lint a SKILL.md before OpenClaw reads it.

What the docs give you instead is a load and an inspection:

openclaw skills list
openclaw skills info hacker-news-digest
openclaw skills check

If the skill stops appearing in list after an edit, its file was rejected as invalid: "Invalid skill files are reported and skipped; valid siblings can still load." Before publishing, clawhub skill publish ./my-skill --dry-run "resolves the publish without uploading", which is the closest documented pre-flight check.

#Comparing versions

There is no openclaw skills diff. Version history and file contents come from the ClawHub CLI's inspect: --versions will "list version history (first page)", --limit <n> caps it, and --file <path> will "fetch raw file bytes".

clawhub inspect @owner/hacker-news-digest --versions
clawhub inspect @owner/hacker-news-digest --version 2.0.0 --file SKILL.md

#Refreshing skills after an edit

There is no openclaw skills reload. OpenClaw "watches SKILL.md files under skills roots by default", and the refreshed list "is picked up on the next agent turn in the same session." When the watcher is disabled or you are continuing an existing session, the creating-skills page tells you to "start a new one so the agent receives the refreshed list", with /new from chat or openclaw gateway restart as the two routes.

#Publishing to ClawHub

There is no openclaw skills publish. Publishing belongs to the standalone clawhub CLI, whose reference names the package: "CLI package: clawhub, bin: clawhub."

npm i -g clawhub
clawhub login
clawhub skill publish ./hacker-news-digest --dry-run
clawhub skill publish ./hacker-news-digest --owner <handle> --changelog "First release"

Options:

Versions are assigned for you: "New skills default to 1.0.0; changed skills default to the next patch version." clawhub login "prints a one-time code and verification URL" rather than opening a browser, and publishing "means it is released under MIT-0 on ClawHub."

#Listing installed and published skills

There is no openclaw skills mine, and no documented statistics subcommand. clawhub list reads the workdir lockfile and shows what is installed, marking pinned next to skills frozen with clawhub pin. Download counts are only exposed as a sort order: clawhub explore --sort downloads.

clawhub list

#skills library, curator and workshop

Three further documented subcommand groups round out openclaw skills. library "manages the identified caller's skills on the selected Gateway", curator status requests Workshop inventory, and workshop drives the proposal queue between the agent and its Workshop directory.

openclaw skills library list --scope mine --json
openclaw skills library create ./my-skill --slug my-skill
openclaw skills curator status --json
openclaw skills workshop list

#openclaw cron

Manage scheduled tasks. "The command registers as openclaw cron with openclaw automations as an alias. Every subcommand below works with either spelling."

#cron add

The documented creation form puts the schedule first and the prompt second.

Options:

There is no --schedule <expr> flag and no --enabled flag. The schedule is the first positional argument or one of --cron, --at, --every, --on-exit and --stream-command, and a job's enabled state is changed with the enable and disable subcommands.

Examples:

# Daily morning briefing
openclaw cron add "0 8 * * *" "Summarize my emails" --name "Morning brief"
# Weekday standup prep with a specific model
openclaw cron add "0 9 * * 1-5" "Prepare standup notes" --model openrouter/gpt-4.1-mini
# Hourly check announced on Discord
openclaw cron add "0 * * * *" "Check for alerts" --announce --channel discord

#cron list

openclaw automations list "shows enabled jobs across agents by default, including jobs whose owner cannot be resolved. Pass --all to include disabled jobs, or --agent <id> to filter by the effective normalized agent ID."

#cron remove

remove is the spelling the page uses in prose, listing it among the mutations that "require operator.admin" alongside add/create, edit and run. rm and delete are the same command: the docs name the group "rm/remove/delete".

#cron enable and cron disable

There are no cron pause or cron resume subcommands. Pausing and resuming a job are disable and enable: "Use openclaw automations enable <job-id> to resume scheduled runs."

#The rest of the subcommand set

Beyond the six above, the page documents create ("openclaw automations create is an alias for openclaw automations add"), get, show, run, status and scratch. get "returns the stored job JSON directly", and the docs say to "Use automations show <job-id> when you want the human-readable view with delivery-route preview."

#cron runs

There is no cron history. Run history is runs: "automations runs is the preferred spelling. cron runs and the leaf-local --id <job-id> form remain supported compatibility aliases."

Options:

There is no --last <duration> flag, and the documented status values are not success, failed and timeout.

openclaw cron runs <job-id> --limit 50 --json
openclaw cron runs <job-id> --status error --query timeout

#openclaw security

"Security tools: audit plus optional safe fixes."

#security audit

audit is the only documented openclaw security subcommand. It audits the deployment's configuration and state rather than a skill bundle. Plain security audit "stays on the cold config/filesystem/read-only path: it does not discover plugin runtime security collectors, so routine audits do not load every installed plugin runtime", while "--deep adds best-effort live Gateway probes and plugin-owned security audit collectors".

Options:

There is no skill-name argument and no --verbose flag. --token and --password "only override deep-probe auth for that command invocation; they do not rewrite config or SecretRef mappings." When Gateway password auth was supplied only at startup, the page tells you to "pass the same value with --auth password --password <password> so the audit can check it against hooks.token."

Read the report before you act on --fix. It does not "rotate tokens/passwords/API keys", does not disable tools, does not change gateway bind, auth or network exposure choices, and does not "remove or rewrite plugins/skills".

Examples:

# Audit the deployment
openclaw security audit
# Add live Gateway probes and plugin collectors
openclaw security audit --deep
# Apply the safe remediations
openclaw security audit --fix
# Machine-readable summary
openclaw security audit --json | jq '.summary'

Accept a standing finding in configuration rather than with a flag. Each entry under security.audit.suppressions "matches an exact checkId and can be narrowed with case-insensitive titleIncludes and/or detailIncludes substrings".

#Reviewing a skill before you install it

There is no openclaw security review. Pre-install review of a ClawHub skill is openclaw skills verify, covered above: it prints ClawHub's trust envelope, or the generated Skill Card with --card. See Skill Security for the full vetting pass.

#Reporting a malicious skill

There is no openclaw security report. Reporting is a ClawHub surface, not an openclaw subcommand: "Signed-in users can report skills, plugins, and packages" and the moderation page directs you to "Use the Report skill button on a skill page, or the package reporting command/API for packages."

#Security advisories

There is no openclaw security advisories. The documented drift check for your own installation is openclaw security audit, and openclaw status --all folds the same audit into its wider report: --all is a "Full diagnosis (read-only, pasteable). Includes security audit, plugin compatibility, and memory-vector probes." See Auditing a skill for how that fits a post-install review.

#openclaw config

Configuration management. openclaw config with no subcommand "opens the same wizard" as openclaw configure, and the docs add: "Use openclaw config get|set|unset for non-interactive edits."

#config get

#config set

#config unset

#config patch

#config validate

#config file and config schema

There is no openclaw config edit. To find the file your editor should open, use config file, which "Prints the active config file path". config schema "Prints the generated JSON schema for openclaw.json to stdout", which is what editor tooling reads. The read-only set is named on the config page: "Read-only commands (config get, config file, config schema, config validate) still work; config writers refuse."

#Resetting configuration

There is no openclaw config reset. Resetting is the top-level openclaw reset command, covered below.

#openclaw dashboard

"Open the Control UI with a short-lived, one-time owner pairing link."

Options:

There is no --port or --no-browser flag. The port comes from the Gateway configuration, and the print-only flag is --no-open. The command needs a reachable Gateway: "The dashboard needs a running Gateway, which can also run in a terminal."

#openclaw pairing

"Approve or inspect DM pairing requests for channels that support pairing". It is not a channel setup wizard: "openclaw channels add configures channel accounts after the baseline exists."

#pairing list

"List pending pairing requests for one channel."

Options: [channel], --channel <channel>, --account <accountId> and --json.

#pairing approve

"Approve a pending pairing code and allow that sender."

Options: --channel <channel>, --account <accountId> and --notify.

There is no openclaw pairing <channel> form that prompts for credentials, and the docs do not publish a fixed list of pairing-capable channels: "If multiple pairing-capable channels are configured, pass a channel positionally or with --channel. Extension channels work as long as the channel id is valid." Approval is also not a privilege grant: "Pairing only lets a sender talk to the agent."

#openclaw status --usage

There is no openclaw usage command in the CLI reference. Provider usage and quota are reported by openclaw status: "openclaw status --usage prints a full per-provider usage/quota breakdown."

Options on openclaw status:

#gateway usage-cost

Cost totals are a separate documented command. openclaw gateway usage-cost will "Fetch usage-cost summaries from session logs."

Options:

There are no --last <duration>, --breakdown <type> or --trend flags on either command. The chat command /usage cost gives a "local cost summary aggregated from OpenClaw session logs".

Examples:

# Provider usage and quota windows
openclaw status --usage
# Usage and quota for one agent
openclaw status --usage --agent work
# Cost summary for the last week
openclaw gateway usage-cost --days 7
# Cost across every configured agent, as JSON
openclaw gateway usage-cost --all-agents --json

#openclaw system heartbeat

There is no openclaw heartbeat command. Heartbeat control lives under openclaw system, whose documented subcommands are system event, system heartbeat last|enable|disable and system presence.

#system heartbeat last

last will "show the last heartbeat event". There is no heartbeat history subcommand and no --last <duration> flag on it. Per-job run history belongs to openclaw cron runs.

#system heartbeat enable and disable

enable will "turn heartbeats back on" and disable will "pause heartbeats".

#Triggering a heartbeat by hand

There is no openclaw heartbeat trigger. The documented way to wake the agent now is a system event with --mode now, which will "trigger the heartbeat immediately"; next-heartbeat is the default and waits for the next scheduled tick.

--text <text> is the "required system event text", and --session-key <sessionKey> targets one agent session instead of the main one.

All system subcommands "use Gateway RPC and accept the shared client flags": --url, --port, --token, --password, --timeout <ms>, --expect-final and --json.

#SOUL.md

There is no openclaw soul command. The CLI reference lists no soul group, so there is no documented soul edit or soul show. SOUL.md is a workspace file that onboarding writes alongside the other bootstrap files: openclaw onboard --skip-bootstrap "skips creating AGENTS.md, SOUL.md, IDENTITY.md, USER.md, and BOOTSTRAP.md."

Edit it as you would any other file in the agent workspace. For the configuration file rather than the workspace files, openclaw config file "Prints the active config file path".

#openclaw update

"Update OpenClaw and switch between stable/extended-stable/beta/dev channels."

Options:

There is no --check, --version <version> or --force flag. To inspect without installing, use --dry-run or the status subcommand; the documented subcommands are status, repair, cleanup and wizard.

openclaw update status
openclaw update --dry-run
openclaw update --channel beta

#openclaw reset

"Reset local config/state (keeps the CLI installed)."

Options:

There are no --conversations, --skills, --config, --cache or --full flags. What to remove is one value passed to --scope, and "Without --scope, openclaw reset prompts interactively for the scope to remove."

#Installing the Gateway as a service

There is no top-level openclaw --install-daemon or openclaw --uninstall-daemon flag, and no --daemon-name option. The system service is managed by the gateway subcommands, with openclaw daemon kept as a legacy alias that "maps to the same service-control commands as openclaw gateway ...".

openclaw gateway install "installs and starts the service", and --force "reinstalls an existing install and may restart a running Gateway."

Options on install: --port, --runtime, --runtime-path <path>, --token, --wrapper <path>, --force and --json. uninstall takes --json. On the runtime choice, "Node is the primary, default, and recommended service runtime."

--install-daemon does exist, but as a flag on onboarding rather than a command of its own: it "starts the managed gateway install path first."

#openclaw onboard

The documented command is onboard, not onboarding. "openclaw setup and openclaw onboard verify inference first, then start OpenClaw for Gateway, workspace, channels, skills, and health setup."

There are no --soul-only or --channels-only flags. Two documented commands cover the narrower jobs:

• openclaw setup --baseline "creates the baseline config and workspace without walking the guided onboarding flow."
• openclaw configure "changes targeted parts of an existing setup: model auth, gateway, channels, plugins, or skills." Its repeatable --section <section> filter takes workspace, model, web, gateway, daemon, channels, plugins, skills or health.

openclaw setup --baseline
openclaw configure --section channels
openclaw configure --section model --section channels

#Configuration File Reference (openclaw.json)

One file holds the whole configuration. The gateway configuration page states where it lives and what happens without it: "OpenClaw reads an optional JSON5 config from ~/.openclaw/openclaw.json", and "If the file is missing, OpenClaw uses safe defaults." The configuration reference gives the same two rules for the contents: "Config format is JSON5 (comments + trailing commas allowed). All fields are optional; OpenClaw uses safe defaults when omitted."

Two file-level constraints are documented alongside that. "The active config path must be a regular file", and "OpenClaw-owned writes replace it atomically (rename onto the path), so a symlinked openclaw.json gets its target replaced rather than written through". If you keep the file somewhere else, the same page says to "point OPENCLAW_CONFIG_PATH directly at the real file".

The layout follows one documented rule: "Configuration follows a two-bucket rule: root siblings hold infrastructure and cross-agent defaults, while agents.defaults holds agent-loop behavior." Per-agent overrides sit under agents.entries, which "may override either bucket where the schema supports a per-agent override".

#How to read and write it

The configuration page documents four routes into the file: the guided wizard, CLI one-liners, the Control UI Config tab, and a direct edit. The CLI is the non-interactive route, described on the openclaw config page as "Non-interactive helpers for openclaw.json: get/set/patch/unset a value by path, print the schema, validate, or print the active file path." Each command below is taken verbatim from that page.

openclaw config file
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config validate
openclaw config schema

The subcommand detail, including behavior under OPENCLAW_CONFIG_READONLY=1, is in the openclaw config section above. For an editor instead, the configuration page describes the direct route: "Edit ~/.openclaw/openclaw.json directly. The Gateway watches the file and applies changes automatically". The Control UI route is the Config tab, where "The Control UI renders a form from the live config schema" with "a Raw JSON editor as an escape hatch". openclaw onboard and openclaw configure edit the same file through prompts.

#What happens when the file is wrong

Validation is strict: "OpenClaw only accepts configurations that fully match the schema", and "The only root-level exception is $schema (string), so editors can attach JSON Schema metadata." A key the schema does not define is therefore not ignored. When validation still fails after the eligible startup migrations, the configuration page lists the result: "The Gateway does not boot", "Only diagnostic commands work (openclaw doctor, openclaw logs, openclaw health, openclaw status)", and "Run openclaw doctor to see exact issues". The repair path is openclaw doctor --fix. The Gateway "keeps a trusted last-known-good copy after each successful startup", but the page is explicit that "startup and hot reload do not restore it automatically" and only that command does.

gateway

Gateway runtime keys. port is the "local Gateway bind port, multiplexing WS + HTTP", resolved in a documented order: "Precedence: --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789." bind accepts auto, loopback (the documented default), lan, tailnet or custom, and authentication stops being optional once you leave loopback: "Non-loopback binds require gateway auth."

// ~/.openclaw/openclaw.json
{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

mode is "local (run gateway) or remote (connect to remote gateway)", and the same line adds that the "Gateway refuses to start unless local." If both a token and a password are configured, the docs require you to "set gateway.auth.mode explicitly to token or password".

agents.defaults

Agent-loop behavior. workspace has a documented default of "OPENCLAW_WORKSPACE_DIR when set, otherwise <state-dir>/workspace", and "An explicit agents.defaults.workspace value takes precedence over OPENCLAW_WORKSPACE_DIR." model "accepts either a string" or an object, where "Object form sets primary plus ordered failover models." heartbeat.every is a "duration string (ms/s/m/h)" whose default is "30m (API-key auth) or 1h (OAuth auth)".

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      heartbeat: {
        every: "30m", // 0m disables recurring cadence
      },
    },
  },
}

The heartbeat block rejects anything else: "The heartbeat object is strict. Its supported fields are agentId, every, activeHours, model, session, target, directPolicy, to, accountId, prompt, timeoutSeconds, lightContext, and isolatedSession."

models

Provider registration and catalog behavior. models.providers is the "custom provider map keyed by provider id" and models.mode is "provider catalog behavior (merge or replace)". The runtime basics page states no default for it; the custom providers page is where merge is marked as the default. A provider key accepts a SecretRef object instead of a literal, in the shape the environment variables page prints.

{
  models: {
    mode: "merge", // merge (default) | replace
    catalogRefresh: {
      enabled: true,
    },
    providers: {
      openai: {
        apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
      },
    },
  },
}

models.catalogRefresh.enabled "controls the hosted model catalog refresh" and defaults to true; set it to false to "prevent all remote catalog requests". OpenClaw API Key Setup covers where the credential itself belongs.

skills

Skill discovery and per-skill settings. "entries.<skillKey>.enabled: false disables a skill even if bundled/installed", and allowBundled is an "optional allowlist for bundled skills only (managed/workspace skills unaffected)".

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    entries: {
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

entries.<skillKey>.apiKey is documented as the "convenience for skills declaring a primary env var (plaintext string or SecretRef object)". Skill Security walks through the SecretRef form.

session

How conversations map to sessions and when they reset. scope is the "base session grouping strategy for group-chat contexts", defaulting to per-sender, where "each sender gets an isolated session within a channel context". dmScope sets "how DMs are grouped": main means "all DMs share the main session", while per-channel-peer is "recommended for multi-user inboxes".

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    groupScope: "per-group", // main | per-group
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
  },
}

agents.defaults.sandbox

"Optional sandboxing for the embedded agent." The documented mode values are off (default), non-main and all; backend takes docker (default), openshell, podman or ssh; and workspaceAccess takes none (default), ro or rw.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off (default) | non-main | all
        backend: "docker", // docker (default) | openshell | podman | ssh
        workspaceAccess: "none", // none (default) | ro | rw
      },
    },
  },
}

secrets

secrets.egressProxy is the "Default-off Gateway-owned substitution for shared-store secret entries used by agent exec subprocesses". Its enabled flag "starts the loopback proxy and ephemeral CA at Gateway startup", defaults to false, and "Changing it requires a Gateway restart."

{
  secrets: {
    egressProxy: {
      enabled: false,
      allowedHosts: ["api.example.com"],
    },
  },
}

logging

Log level, log file and the audit ledger. The audit block has moved: "A root-level audit block is retired; the canonical path is logging.audit. The root config object is strict, so an old top-level audit block is rejected." logging.audit.enabled means "record new audit events" and defaults to true; messages is the "message metadata scope" and defaults to off.

{
  logging: {
    level: "info",
    audit: {
      enabled: true,
      messages: "off", // off | direct | all
    },
  },
}

env

Inline environment variables and the optional login-shell import. "Inline env vars are only applied if the process env is missing the key."

{
  env: {
    vars: {
      OPENROUTER_API_KEY: "sk-or-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

#Other documented top-level sections

The configuration reference indexes the rest by name: channels, multiAgent, messages, talk, tools, mcp, plugins, browser, ui, desktop, hooks, cron, discovery, update, acp, wizard, worktreeRoot, cloudWorkers, auth, diagnostics and telemetry. The runtime basics page adds worktreeAcceleration. The hot reload page adds approvals.exec, approvals.plugin, security.installPolicy and security.audit.suppressions in its approval and install policy row.

#The keys most configurations set

#Environment Variables

OpenClaw's environment page draws a hard line around which variables count: "The variables below are the supported environment contract for operators. Undocumented OPENCLAW_* variables are internal implementation details and may disappear without notice." The same page adds that "OpenClaw only reads OPENCLAW_* environment variables. The legacy CLAWDBOT_* and MOLTBOT_* prefixes from earlier releases are silently ignored." Rename any of those you still have, because "The old names take no effect."

#Where OpenClaw reads them from

The gateway environment variables page names the sources: "OpenClaw reads env vars from the parent process plus" a ".env from the current working directory (if present)" and "~/.openclaw/.env (global fallback)". "Neither file overrides existing env vars."

The environment page gives the full precedence from highest to lowest: the process environment, a .env in the current working directory, the global .env at ~/.openclaw/.env, the config env block, and last the optional login-shell import. Its one-line summary of the rule is "never override existing values". A workspace .env is treated differently from the rest: "Workspace .env files are a lower-trust source: OpenClaw ignores provider credentials and protected runtime controls from workspace .env before applying precedence."

Path handling differs by variable, and the page spells out which: "OPENCLAW_WORKSPACE_DIR does not expand a leading ~ either, because it goes straight to path.resolve. OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH do expand ~."

#The operator contract variables

The environment page groups them under four headings, reproduced below.

#Paths and instances

#Gateway and authentication

#Logging and diagnostics

#Feature and runtime toggles

One more OPENCLAW_* name is documented outside that contract: the CLI reference lists OPENCLAW_CONTAINER as the default for the global --container <name> flag.

#Provider credentials

Provider keys are a separate documented list. "Core and bundled provider plugins recognize the following credential and provider-selection variables", and the list includes ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY and GROQ_API_KEY among many more. The page's advice is to scope them instead of exporting one value everywhere: "Prefer each provider's config or SecretRef fields when you need scoped credentials rather than one process-wide value."

A project directory is the wrong home for them. OpenClaw blocks provider credentials from a workspace .env, "plus any key ending in _API_HOST, _BASE_URL, _ENDPOINT, or _HOMESERVER, and the entire OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_*, and OPENAI_API_KEY_* namespaces."

#Using a variable inside the config file

Instead of duplicating a value, the gateway environment variables page documents ${VAR_NAME} substitution in "any config string value". The page's rules: "Only uppercase names matched: [A-Z_][A-Z0-9_]*"; missing or empty vars "stay visibly unresolved, emit a warning, and are unavailable to consumers that require the value"; "Escape with $${VAR} to produce a literal ${VAR} value"; it "Works inside $include files"; and inline substitution turns "${BASE}/v1" into "https://api.example.com/v1".

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

A SecretRef goes one step further and points at a provider instead of holding the value. The same page offers it "For fields that support SecretRef objects", and the environment, secrets and includes page gives "one object shape" with source, provider and id, where source is env, file, exec or store. OpenClaw API Key Setup covers which fields accept one.

#Variables older tutorials use that the docs do not define

Three names in circulation are absent from OpenClaw's operator contract: OPENCLAW_PORT, OPENCLAW_HOST and OPENCLAW_WORKSPACE. The documented equivalents are OPENCLAW_GATEWAY_PORT for the port and OPENCLAW_WORKSPACE_DIR for the workspace, and the bind interface is a config key, gateway.bind, rather than an environment variable at all.

#Next Steps

• Getting Started on Mac Mini: Initial setup
• Security Hardening: Secure your configuration
• Cost Optimization: Optimize your spending
• Troubleshooting: Fix common issues