FAQ

FAQ 문서는 OpenClaw 공식 문서(help/faq)를 한국어로 정리한 가이드입니다. Frequently asked questions about OpenClaw setup, configuration, and usage 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Frequently asked questions about OpenClaw setup, configuration, and usage

한국어 가이드 범위: help/faq 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

First 60 seconds if something is broken
Quick start and first-run setup
What is OpenClaw?
Skills and automation
Sandboxing and memory
Where things live on disk
Config basics
Remote gateways and nodes
Env vars and .env loading
Sessions and multiple chats
Models, failover, and auth profiles
Gateway: ports, "already running", and remote mode
Logging and debugging
Media and attachments
Security and access control
Chat commands, aborting tasks, and "it will not stop"
Miscellaneous
관련 문서

상세 내용

본문

Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see Troubleshooting. For the full config reference, see Configuration.

First 60 seconds if something is broken

Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when the gateway is reachable).

openclaw status

openclaw status --all

openclaw gateway status

openclaw status --deep

Quick start and first-run setup

First-run Q&A - install, onboard, auth routes, subscriptions, initial failures - lives on the First-run FAQ.

What is OpenClaw?

OpenClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (Discord, Google Chat, iMessage, Mattermost, Signal, Slack, Telegram, WebChat, WhatsApp, and bundled channel plugins such as QQ Bot) and can also do voice plus a live Canvas on supported platforms. The Gateway is the always-on control plane; the assistant is the product.

주요 항목:

Your devices, your data: run the Gateway wherever you want (Mac, Linux, VPS) and keep the workspace and session history local.
Real channels, not a web sandbox: Discord/iMessage/Signal/Slack/Telegram/WhatsApp/etc, plus mobile voice and Canvas on supported platforms.
Model-agnostic: use Anthropic, MiniMax, OpenAI, OpenRouter, etc., with per-agent routing and failover.
Local-only option: run local models so all data can stay on your device.
Multi-agent routing: separate agents per channel, account, or task, each with its own workspace and defaults.
Open source and hackable: inspect, extend, and self-host without vendor lock-in.
Personal briefings: summaries of inbox, calendar, and news you care about.
Research and drafting: quick research, summaries, and first drafts for emails or docs.
Reminders and follow-ups: cron- or heartbeat-driven nudges and checklists.
Browser automation: filling forms, collecting data, repeating web tasks.
Cross-device coordination: send a task from your phone, let the Gateway run it on a server, get the result back in chat.
Persistent memory and workspace across sessions.
Multi-platform access (Telegram, WhatsApp, TUI, WebChat).
Tool orchestration (browser, files, scheduling, hooks).
Always-on Gateway (run on a VPS, interact from anywhere).
Nodes for local browser/screen/camera/exec.

Skills and automation

Use managed overrides instead of editing the repo copy. Put changes in ~/.openclaw/skills//SKILL.md (or add a folder via skills.load.extraDirs in ~/.openclaw/openclaw.json). Precedence: /skills -> /.agents/skills -> ~/.agents/skills -> ~/.openclaw/skills -> bundled -> skills.load.extraDirs, so managed overrides win over bundled skills without touching git. To install globally but limit visibility to some agents, keep the shared copy in ~/.openclaw/skills and control visibility with agents.defaults.skills / agents.entries.*.skills. Only upstream-worthy edits should go out as PRs against the repo copy.

주요 항목:

Cron jobs: isolated jobs can set a model override per job.
Agents: route tasks to separate agents with different default models, thinking levels, and stream params.
On-demand switch: /model switches the current session model at any time.
Spawn with sessions_spawn using thread: true (optionally mode: "session" for persistent follow-up).
Or bind manually with /focus <target>.
/agents inspects binding state.
/session idle <duration|off> and /session max-age <duration|off> control auto-unfocus.
/unfocus detaches the thread.
Completion-mode subagent delivery prefers a bound thread or conversation route when one exists.
If the completion origin only carries a channel, OpenClaw falls back to the requester session's stored route (lastChannel / lastTo / lastAccountId) so direct delivery can still succeed.
No bound route and no usable stored route: direct delivery can fail and the result falls back to queued session delivery instead of posting immediately.
Invalid or stale targets can also force queue fallback or final delivery failure.
If the child's last visible assistant reply is exactly NO_REPLY / no_reply or ANNOUNCE_SKIP, OpenClaw intentionally suppresses the announce instead of posting stale earlier progress.
Confirm cron is enabled (cron.enabled) and OPENCLAW_SKIP_CRON is not set.
Confirm the Gateway is running 24/7 (no sleep/restarts).
Verify job timezone (--tz vs host timezone).
--no-deliver / delivery.mode: "none": no runner fallback send is expected.
Missing or invalid announce target (channel / to): the runner skipped outbound delivery.
Channel auth failures (unauthorized, Forbidden): the runner tried to deliver but credentials blocked it.
A silent isolated result (NO_REPLY / no_reply only) is treated as intentionally non-deliverable, so queued fallback delivery is also suppressed.
Cron jobs for scheduled or recurring tasks (persist across restarts).
Heartbeat for main-session periodic checks.
Isolated jobs for autonomous agents that post summaries or deliver to chats.
Custom skill / plugin: best for reliable API access (both have APIs).
Browser automation: works without code but is slower and more fragile.

{
      agents: {
        list: [
          {
            id: "coder",
            model: "xiaomi/mimo-v2.5-pro",
            thinkingDefault: "high",
            params: { temperature: 0.1 },
          },
          {
            id: "chat",
            model: "xiaomi/mimo-v2.5-pro",
            thinkingDefault: "off",
            params: { temperature: 0.8 },
          },
        ],
      },
    }

openclaw cron run <jobId>
    openclaw cron runs --id <jobId> --limit 50

openclaw cron runs --id <jobId> --limit 50
    openclaw tasks show <lookup>

openclaw cron runs --id <jobId> --limit 50

Sandboxing and memory

Yes: Sandboxing. For Docker-specific setup (full gateway in Docker or sandbox images), see Docker.

주요 항목:

Persist /home/node with OPENCLAW_HOME_VOLUME so caches survive.
Bake system deps into the image with OPENCLAW_IMAGE_APT_PACKAGES.
Install Playwright browsers via the bundled CLI: node /app/node_modules/playwright-core/cli.js install chromium.
Set PLAYWRIGHT_BROWSERS_PATH and persist that path.

Where things live on disk

No: OpenClaw's own state is local, but external services still see what you send them.

주요 항목:

Local by default: sessions, memory files, config, and workspace live on the Gateway host (~/.openclaw plus your workspace directory).
Remote by necessity: messages sent to model providers (Anthropic/OpenAI/etc.) go to their APIs, and chat platforms (Slack/Telegram/WhatsApp/etc.) store message data on their servers.
You control the footprint: local models keep prompts on your machine, but channel traffic still goes through the channel's servers.
Workspace (per agent): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, optional HEARTBEAT.md. Lowercase root memory.md is legacy repair input only; openclaw doctor --fix can merge it into MEMORY.md when both exist.
State dir (~/.openclaw): config, channel/provider state, auth profiles, sessions, logs, shared skills (~/.openclaw/skills).

{
      agents: { defaults: { workspace: "~/.openclaw/workspace" } },
    }

{
      agents: {
        defaults: {
          bootstrapMaxChars: 50000,
          bootstrapTotalMaxChars: 300000,
        },
      },
    }

{
      agents: {
        defaults: {
          workspace: "~/Projects/my-repo",
        },
      },
    }

Config basics

OpenClaw reads an optional JSON5 config from $OPENCLAW_CONFIG_PATH (default: ~/.openclaw/openclaw.json). If the file is missing, it uses safe-ish defaults, including a default workspace of ~/.openclaw/workspace.

주요 항목:

gateway.remote.token / .password do not enable local gateway auth by themselves; local call paths can use gateway.remote.* as fallback only when gateway.auth.* is unset.
For password auth, set gateway.auth.mode: "password" plus gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
If gateway.auth.token / .password is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
Shared-secret Control UI setups authenticate via connect.params.auth.token or connect.params.auth.password (stored in app/UI settings). Identity-bearing modes such as Tailscale Serve or trusted-proxy use request headers instead - avoid putting shared secrets in URLs.
With gateway.auth.mode: "trusted-proxy", same-host loopback reverse proxies require explicit gateway.auth.trustedProxy.allowLoopback = true and a loopback entry in gateway.trustedProxies.
Allowlists: add web_search/web_fetch/x_search, or group:web for all three.
web_fetch is enabled by default.
If tools.web.fetch.provider is omitted, OpenClaw auto-detects the first ready fetch fallback provider from available credentials; the official Firecrawl plugin provides that fallback.
Daemons read env vars from ~/.openclaw/.env (or the service environment).
OpenClaw-owned config writes validate the full post-change config before writing.
Invalid or destructive OpenClaw-owned writes are rejected and saved as openclaw.json.rejected.*.
A direct edit that breaks startup or hot reload makes the Gateway fail closed or skip the reload; it does not rewrite openclaw.json.
openclaw doctor --fix owns repair, can restore last-known-good, and saves the rejected file as openclaw.json.clobbered.*.
Check openclaw logs --follow for Invalid config at, Config write rejected:, or config reload skipped (invalid config).
Inspect the newest openclaw.json.clobbered.* or openclaw.json.rejected.* beside the active config.
Run openclaw config validate and openclaw doctor --fix.
Copy only the intended keys back with openclaw config set or config.patch.
No last-known-good or rejected payload: restore from backup, or re-run openclaw doctor and reconfigure channels/models.
Unexpected loss: file a bug with your last known config or a backup. A local coding agent can often reconstruct a working config from logs or history.
Gateway (central): owns channels (Signal/WhatsApp), routing, sessions.
Nodes (devices): Macs/iOS/Android connect as peripherals and expose local tools (system.run, canvas, camera).
Agents (workers): separate brains/workspaces for special roles (for example ops vs personal data).
Sub-agents: spawn background work from a main agent for parallelism.
TUI: connect to the Gateway and switch agents/sessions.

{
      gateway: {
        bind: "lan",
        auth: {
          mode: "token",
          token: "replace-me",
        },
      },
    }

{
      plugins: {
        entries: {
          brave: {
            config: {
              webSearch: {
                apiKey: "BRAVE_API_KEY_HERE",
              },
            },
          },
        },
      },
      tools: {
        web: {
          search: {
            enabled: true,
            provider: "brave",
            maxResults: 5,
          },
          fetch: {
            enabled: true,
            provider: "firecrawl", // optional; omit for auto-detect
          },
        },
      },
    }

{
      browser: { headless: true },
      agents: {
        defaults: {
          sandbox: { browser: { headless: true } },
        },
      },
    }

Remote gateways and nodes

Telegram messages are handled by the gateway, which runs the agent and only then calls nodes over the Gateway WebSocket when a node tool is needed:

주요 항목:

No inbound SSH required - nodes connect out to the Gateway WebSocket via device pairing.
Safer execution controls - system.run is gated by node allowlists/approvals on that laptop.
More device tools - nodes expose canvas, camera, and screen in addition to system.run.
Local browser automation - keep the Gateway on a VPS but run Chrome locally through a node host, or attach to local Chrome via Chrome MCP.
config.schema.lookup: inspect one config subtree with its shallow schema node, matched UI hint, and immediate child summaries before writing.
config.get: fetch the current snapshot plus hash.
config.patch: safe partial update (preferred for most RPC edits); hot-reloads when possible, restarts when required.
config.apply: validate and replace the full config; hot-reloads when possible, restarts when required.
The agent-facing gateway runtime tool still refuses to rewrite tools.exec.ask / tools.exec.security; legacy tools.bash.* aliases normalize to the same protected paths.

openclaw devices list
       openclaw devices approve <requestId>

openclaw gateway status
    openclaw status
    openclaw channels status

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

{
      agents: { defaults: { workspace: "~/.openclaw/workspace" } },
      channels: { whatsapp: { allowFrom: ["+15555550123"] } },
    }

Env vars and .env loading

OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:

주요 항목:

.env from the current working directory.
a global fallback .env from ~/.openclaw/.env ($OPENCLAW_STATE_DIR/.env).

{
      env: {
        OPENROUTER_API_KEY: "sk-or-...",
        vars: { GROQ_API_KEY: "gsk-..." },
      },
    }

{
         env: {
           shellEnv: {
             enabled: true,
             timeoutMs: 15000,
           },
         },
       }

openclaw models status

Sessions and multiple chats

Send /new or /reset as a standalone message. See Session management.

주요 항목:

Ask the bot to summarize current state and write it to a file.
Use /compact before long tasks, /new when switching topics.
Keep important context in the workspace and ask the bot to read it back.
Use sub-agents for long or parallel work so the main chat stays smaller.
Pick a model with a larger context window if this happens often.
Compact (keeps the conversation, summarizes older turns): /compact or /compact <instructions> to guide the summary.
Reset (fresh session ID for the same chat key): /new or /reset.
Disk growth: active sessions and transcripts live in the per-agent SQLite database; legacy/archive artifacts can still accumulate under ~/.openclaw/agents/<agentId>/sessions/.
Token cost: more agents means more concurrent model usage.
Ops overhead: per-agent auth profiles, workspaces, and channel routing.

{
      session: {
        reset: { mode: "daily", atHour: 4 },
        resetByType: {
          group: { mode: "idle", idleMinutes: 120 },
          thread: { mode: "daily", atHour: 6 },
        },
        resetByChannel: {
          discord: { mode: "idle", idleMinutes: 10080 },
        },
      },
    }

openclaw reset

openclaw reset --scope full --yes --non-interactive

openclaw onboard --install-daemon

Models, failover, and auth profiles

Model Q&A - defaults, selection, aliases, switching, failover, auth profiles - lives on the Models FAQ.

Gateway: ports, "already running", and remote mode

gateway.port controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.). Precedence:

주요 항목:

openclaw gateway only starts when gateway.mode is local (or you pass an override flag).
The macOS app watches the config file and switches modes live when these values change.
gateway.remote.token / .password are client-side remote credentials only; they do not enable local gateway auth by themselves.
The Control UI keeps the token in sessionStorage, scoped to the current browser tab and selected gateway URL, so same-tab refreshes keep working without long-lived localStorage token persistence.
On AUTH_TOKEN_MISMATCH, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
That cached-token retry reuses the cached approved scopes stored with the device token; explicit deviceToken / explicit scopes callers keep their requested scope set instead of inheriting cached scopes.
Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit deviceToken, then stored device token, then bootstrap token.
Built-in setup-code bootstrap returns a node device token with scopes: [] plus a bounded operator handoff token for trusted mobile onboarding. The operator handoff can read setup-time native configuration but does not grant pairing mutation scopes or operator.admin.
Fastest: openclaw dashboard (prints + copies the dashboard URL, tries to open; shows an SSH hint if headless).
No token yet: openclaw doctor --generate-gateway-token.
Remote: tunnel first with ssh -N -L 18789:127.0.0.1:18789 user@host, then open http://127.0.0.1:18789/.
Shared-secret mode: set gateway.auth.token / OPENCLAW_GATEWAY_TOKEN or gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, then paste the matching secret in Control UI settings.
Tailscale Serve mode: confirm gateway.auth.allowTailscale is enabled and you are opening the Serve URL, not a raw loopback/tailnet URL that bypasses Tailscale identity headers.
Trusted-proxy mode: confirm you are coming through the configured identity-aware proxy. Same-host loopback proxies also need gateway.auth.trustedProxy.allowLoopback = true.
Mismatch persists after the one retry: rotate/re-approve the paired device token:
Rotate denied: paired-device sessions can rotate only their own device unless they also have operator.admin, and explicit --scope values cannot exceed the caller's current operator scopes.
Still stuck: openclaw status --all plus Troubleshooting. See Dashboard for auth details.

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

openclaw gateway install --force

{
      gateway: {
        mode: "remote",
        remote: {
          url: "ws://gateway.tailnet:18789",
          token: "your-token",
          password: "your-password",
        },
      },
    }

openclaw devices list
      openclaw devices rotate --device <id> --role operator

Logging and debugging

File logs (structured): /tmp/openclaw/openclaw-YYYY-MM-DD.log for the default profile, or /tmp/openclaw/openclaw--YYYY-MM-DD.log for a named profile. Set a stable path via logging.file; file log level via logging.level; console verbosity via --verbose and logging.consoleLevel.

주요 항목:

macOS launchd stdout: ~/Library/Logs/openclaw/gateway.log (profiles use gateway-<profile>.log; stderr is suppressed).
Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager.
Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST.
BOT_COMMANDS_TOO_MUCH: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries may still be dropped. Reduce plugin/skill/custom commands, or disable channels.telegram.commands.native if you do not need the menu.
TypeError: fetch failed, Network request for 'setMyCommands' failed!, or similar network errors: on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for api.telegram.org.

openclaw logs --follow

openclaw gateway status
    openclaw gateway restart

wsl
    openclaw gateway status
    openclaw gateway restart

openclaw gateway status
    openclaw gateway restart

Media and attachments

Outbound attachments from the agent must use structured media fields such as media, mediaUrl, path, or filePath. See OpenClaw assistant setup and Agent send.

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

Security and access control

Treat inbound DMs as untrusted input. Defaults reduce risk:

주요 항목:

Default behavior on DM-capable channels is pairing: unknown senders receive a pairing code and their message is not processed. Approve with openclaw pairing approve --channel <channel> [--account <id>] <code>. Pending requests are capped at 3 per channel; check openclaw pairing list --channel <channel> [--account <id>] if a code did not arrive.
Opening DMs publicly requires explicit opt-in (dmPolicy: "open" and allowlist "*").
use a read-only or tool-disabled "reader" agent to summarize untrusted content
keep web_search / web_fetch / browser off for tool-enabled agents
treat decoded file/document text as untrusted too: OpenResponses input_file and media-attachment extraction both wrap extracted text in explicit external-content boundary markers instead of passing raw file text
sandbox and use strict tool allowlists

openclaw security audit --deep
    openclaw gateway status

openclaw pairing list telegram

openclaw pairing approve whatsapp <code>
    openclaw pairing list whatsapp

Chat commands, aborting tasks, and "it will not stop"

Most internal/tool messages only appear when verbose, trace, or reasoning is enabled for that session.

주요 항목:

steer (default) - guide the active run at the next model boundary.
followup - queue messages and run them one at a time after the current run ends.
collect - queue compatible messages and reply once after the current run ends.
interrupt - abort the current run and start fresh.

/verbose off
    /trace off
    /reasoning off

process action:kill sessionId:XXX

{
      tools: {
        message: {
          crossContext: {
            allowAcrossProviders: true,
            marker: { enabled: true, prefix: "[from {channel}] " },
          },
        },
      },
    }

Miscellaneous

Credentials and model selection are separate. Setting ANTHROPIC_API_KEY (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in agents.defaults.model.primary (for example anthropic/claude-sonnet-4-6 or anthropic/claude-opus-4). No credentials found for profile "anthropic:default" means the Gateway could not find Anthropic credentials in the expected auth-profiles.json for the running agent.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/help/faq
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw status

openclaw status --all

openclaw gateway status

openclaw status --deep

openclaw logs --follow

tail -f "/tmp/openclaw/openclaw-$(date +%F).log"
    # Named profile example:
    tail -f "/tmp/openclaw/openclaw-dev-$(date +%F).log"

FAQ

핵심 요약

Frequently asked questions about OpenClaw setup, configuration, and usage

한국어 가이드 범위: help/faq 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

First 60 seconds if something is broken
Quick start and first-run setup
What is OpenClaw?
Skills and automation
Sandboxing and memory
Where things live on disk
Config basics
Remote gateways and nodes
Env vars and .env loading
Sessions and multiple chats
Models, failover, and auth profiles
Gateway: ports, "already running", and remote mode
Logging and debugging
Media and attachments
Security and access control
Chat commands, aborting tasks, and "it will not stop"
Miscellaneous
관련 문서

상세 내용

본문

First 60 seconds if something is broken

Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when the gateway is reachable).

openclaw status

openclaw status --all

openclaw gateway status

openclaw status --deep

Quick start and first-run setup

First-run Q&A - install, onboard, auth routes, subscriptions, initial failures - lives on the First-run FAQ.

What is OpenClaw?

주요 항목:

Your devices, your data: run the Gateway wherever you want (Mac, Linux, VPS) and keep the workspace and session history local.
Real channels, not a web sandbox: Discord/iMessage/Signal/Slack/Telegram/WhatsApp/etc, plus mobile voice and Canvas on supported platforms.
Model-agnostic: use Anthropic, MiniMax, OpenAI, OpenRouter, etc., with per-agent routing and failover.
Local-only option: run local models so all data can stay on your device.
Multi-agent routing: separate agents per channel, account, or task, each with its own workspace and defaults.
Open source and hackable: inspect, extend, and self-host without vendor lock-in.
Personal briefings: summaries of inbox, calendar, and news you care about.
Research and drafting: quick research, summaries, and first drafts for emails or docs.
Reminders and follow-ups: cron- or heartbeat-driven nudges and checklists.
Browser automation: filling forms, collecting data, repeating web tasks.
Cross-device coordination: send a task from your phone, let the Gateway run it on a server, get the result back in chat.
Persistent memory and workspace across sessions.
Multi-platform access (Telegram, WhatsApp, TUI, WebChat).
Tool orchestration (browser, files, scheduling, hooks).
Always-on Gateway (run on a VPS, interact from anywhere).
Nodes for local browser/screen/camera/exec.

Skills and automation

주요 항목:

Cron jobs: isolated jobs can set a model override per job.
Agents: route tasks to separate agents with different default models, thinking levels, and stream params.
On-demand switch: /model switches the current session model at any time.
Spawn with sessions_spawn using thread: true (optionally mode: "session" for persistent follow-up).
Or bind manually with /focus <target>.
/agents inspects binding state.
/session idle <duration|off> and /session max-age <duration|off> control auto-unfocus.
/unfocus detaches the thread.
Completion-mode subagent delivery prefers a bound thread or conversation route when one exists.
If the completion origin only carries a channel, OpenClaw falls back to the requester session's stored route (lastChannel / lastTo / lastAccountId) so direct delivery can still succeed.
No bound route and no usable stored route: direct delivery can fail and the result falls back to queued session delivery instead of posting immediately.
Invalid or stale targets can also force queue fallback or final delivery failure.
If the child's last visible assistant reply is exactly NO_REPLY / no_reply or ANNOUNCE_SKIP, OpenClaw intentionally suppresses the announce instead of posting stale earlier progress.
Confirm cron is enabled (cron.enabled) and OPENCLAW_SKIP_CRON is not set.
Confirm the Gateway is running 24/7 (no sleep/restarts).
Verify job timezone (--tz vs host timezone).
--no-deliver / delivery.mode: "none": no runner fallback send is expected.
Missing or invalid announce target (channel / to): the runner skipped outbound delivery.
Channel auth failures (unauthorized, Forbidden): the runner tried to deliver but credentials blocked it.
A silent isolated result (NO_REPLY / no_reply only) is treated as intentionally non-deliverable, so queued fallback delivery is also suppressed.
Cron jobs for scheduled or recurring tasks (persist across restarts).
Heartbeat for main-session periodic checks.
Isolated jobs for autonomous agents that post summaries or deliver to chats.
Custom skill / plugin: best for reliable API access (both have APIs).
Browser automation: works without code but is slower and more fragile.

{
      agents: {
        list: [
          {
            id: "coder",
            model: "xiaomi/mimo-v2.5-pro",
            thinkingDefault: "high",
            params: { temperature: 0.1 },
          },
          {
            id: "chat",
            model: "xiaomi/mimo-v2.5-pro",
            thinkingDefault: "off",
            params: { temperature: 0.8 },
          },
        ],
      },
    }

openclaw cron run <jobId>
    openclaw cron runs --id <jobId> --limit 50

openclaw cron runs --id <jobId> --limit 50
    openclaw tasks show <lookup>

openclaw cron runs --id <jobId> --limit 50

Sandboxing and memory

Yes: Sandboxing. For Docker-specific setup (full gateway in Docker or sandbox images), see Docker.

주요 항목:

Persist /home/node with OPENCLAW_HOME_VOLUME so caches survive.
Bake system deps into the image with OPENCLAW_IMAGE_APT_PACKAGES.
Install Playwright browsers via the bundled CLI: node /app/node_modules/playwright-core/cli.js install chromium.
Set PLAYWRIGHT_BROWSERS_PATH and persist that path.

Where things live on disk

No: OpenClaw's own state is local, but external services still see what you send them.

주요 항목:

Local by default: sessions, memory files, config, and workspace live on the Gateway host (~/.openclaw plus your workspace directory).
Remote by necessity: messages sent to model providers (Anthropic/OpenAI/etc.) go to their APIs, and chat platforms (Slack/Telegram/WhatsApp/etc.) store message data on their servers.
You control the footprint: local models keep prompts on your machine, but channel traffic still goes through the channel's servers.
Workspace (per agent): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, optional HEARTBEAT.md. Lowercase root memory.md is legacy repair input only; openclaw doctor --fix can merge it into MEMORY.md when both exist.
State dir (~/.openclaw): config, channel/provider state, auth profiles, sessions, logs, shared skills (~/.openclaw/skills).

{
      agents: { defaults: { workspace: "~/.openclaw/workspace" } },
    }

{
      agents: {
        defaults: {
          bootstrapMaxChars: 50000,
          bootstrapTotalMaxChars: 300000,
        },
      },
    }

{
      agents: {
        defaults: {
          workspace: "~/Projects/my-repo",
        },
      },
    }

Config basics

주요 항목:

gateway.remote.token / .password do not enable local gateway auth by themselves; local call paths can use gateway.remote.* as fallback only when gateway.auth.* is unset.
For password auth, set gateway.auth.mode: "password" plus gateway.auth.password (or OPENCLAW_GATEWAY_PASSWORD).
If gateway.auth.token / .password is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
Shared-secret Control UI setups authenticate via connect.params.auth.token or connect.params.auth.password (stored in app/UI settings). Identity-bearing modes such as Tailscale Serve or trusted-proxy use request headers instead - avoid putting shared secrets in URLs.
With gateway.auth.mode: "trusted-proxy", same-host loopback reverse proxies require explicit gateway.auth.trustedProxy.allowLoopback = true and a loopback entry in gateway.trustedProxies.
Allowlists: add web_search/web_fetch/x_search, or group:web for all three.
web_fetch is enabled by default.
If tools.web.fetch.provider is omitted, OpenClaw auto-detects the first ready fetch fallback provider from available credentials; the official Firecrawl plugin provides that fallback.
Daemons read env vars from ~/.openclaw/.env (or the service environment).
OpenClaw-owned config writes validate the full post-change config before writing.
Invalid or destructive OpenClaw-owned writes are rejected and saved as openclaw.json.rejected.*.
A direct edit that breaks startup or hot reload makes the Gateway fail closed or skip the reload; it does not rewrite openclaw.json.
openclaw doctor --fix owns repair, can restore last-known-good, and saves the rejected file as openclaw.json.clobbered.*.
Check openclaw logs --follow for Invalid config at, Config write rejected:, or config reload skipped (invalid config).
Inspect the newest openclaw.json.clobbered.* or openclaw.json.rejected.* beside the active config.
Run openclaw config validate and openclaw doctor --fix.
Copy only the intended keys back with openclaw config set or config.patch.
No last-known-good or rejected payload: restore from backup, or re-run openclaw doctor and reconfigure channels/models.
Unexpected loss: file a bug with your last known config or a backup. A local coding agent can often reconstruct a working config from logs or history.
Gateway (central): owns channels (Signal/WhatsApp), routing, sessions.
Nodes (devices): Macs/iOS/Android connect as peripherals and expose local tools (system.run, canvas, camera).
Agents (workers): separate brains/workspaces for special roles (for example ops vs personal data).
Sub-agents: spawn background work from a main agent for parallelism.
TUI: connect to the Gateway and switch agents/sessions.

{
      gateway: {
        bind: "lan",
        auth: {
          mode: "token",
          token: "replace-me",
        },
      },
    }

{
      plugins: {
        entries: {
          brave: {
            config: {
              webSearch: {
                apiKey: "BRAVE_API_KEY_HERE",
              },
            },
          },
        },
      },
      tools: {
        web: {
          search: {
            enabled: true,
            provider: "brave",
            maxResults: 5,
          },
          fetch: {
            enabled: true,
            provider: "firecrawl", // optional; omit for auto-detect
          },
        },
      },
    }

{
      browser: { headless: true },
      agents: {
        defaults: {
          sandbox: { browser: { headless: true } },
        },
      },
    }

Remote gateways and nodes

Telegram messages are handled by the gateway, which runs the agent and only then calls nodes over the Gateway WebSocket when a node tool is needed:

주요 항목:

No inbound SSH required - nodes connect out to the Gateway WebSocket via device pairing.
Safer execution controls - system.run is gated by node allowlists/approvals on that laptop.
More device tools - nodes expose canvas, camera, and screen in addition to system.run.
Local browser automation - keep the Gateway on a VPS but run Chrome locally through a node host, or attach to local Chrome via Chrome MCP.
config.schema.lookup: inspect one config subtree with its shallow schema node, matched UI hint, and immediate child summaries before writing.
config.get: fetch the current snapshot plus hash.
config.patch: safe partial update (preferred for most RPC edits); hot-reloads when possible, restarts when required.
config.apply: validate and replace the full config; hot-reloads when possible, restarts when required.
The agent-facing gateway runtime tool still refuses to rewrite tools.exec.ask / tools.exec.security; legacy tools.bash.* aliases normalize to the same protected paths.

openclaw devices list
       openclaw devices approve <requestId>

openclaw gateway status
    openclaw status
    openclaw channels status

openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>

{
      agents: { defaults: { workspace: "~/.openclaw/workspace" } },
      channels: { whatsapp: { allowFrom: ["+15555550123"] } },
    }

Env vars and .env loading

OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:

주요 항목:

.env from the current working directory.
a global fallback .env from ~/.openclaw/.env ($OPENCLAW_STATE_DIR/.env).

{
      env: {
        OPENROUTER_API_KEY: "sk-or-...",
        vars: { GROQ_API_KEY: "gsk-..." },
      },
    }

{
         env: {
           shellEnv: {
             enabled: true,
             timeoutMs: 15000,
           },
         },
       }

openclaw models status

Sessions and multiple chats

Send /new or /reset as a standalone message. See Session management.

주요 항목:

Ask the bot to summarize current state and write it to a file.
Use /compact before long tasks, /new when switching topics.
Keep important context in the workspace and ask the bot to read it back.
Use sub-agents for long or parallel work so the main chat stays smaller.
Pick a model with a larger context window if this happens often.
Compact (keeps the conversation, summarizes older turns): /compact or /compact <instructions> to guide the summary.
Reset (fresh session ID for the same chat key): /new or /reset.
Disk growth: active sessions and transcripts live in the per-agent SQLite database; legacy/archive artifacts can still accumulate under ~/.openclaw/agents/<agentId>/sessions/.
Token cost: more agents means more concurrent model usage.
Ops overhead: per-agent auth profiles, workspaces, and channel routing.

{
      session: {
        reset: { mode: "daily", atHour: 4 },
        resetByType: {
          group: { mode: "idle", idleMinutes: 120 },
          thread: { mode: "daily", atHour: 6 },
        },
        resetByChannel: {
          discord: { mode: "idle", idleMinutes: 10080 },
        },
      },
    }

openclaw reset

openclaw reset --scope full --yes --non-interactive

openclaw onboard --install-daemon

Models, failover, and auth profiles

Model Q&A - defaults, selection, aliases, switching, failover, auth profiles - lives on the Models FAQ.

Gateway: ports, "already running", and remote mode

gateway.port controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.). Precedence:

주요 항목:

openclaw gateway only starts when gateway.mode is local (or you pass an override flag).
The macOS app watches the config file and switches modes live when these values change.
gateway.remote.token / .password are client-side remote credentials only; they do not enable local gateway auth by themselves.
The Control UI keeps the token in sessionStorage, scoped to the current browser tab and selected gateway URL, so same-tab refreshes keep working without long-lived localStorage token persistence.
On AUTH_TOKEN_MISMATCH, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token).
That cached-token retry reuses the cached approved scopes stored with the device token; explicit deviceToken / explicit scopes callers keep their requested scope set instead of inheriting cached scopes.
Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit deviceToken, then stored device token, then bootstrap token.
Built-in setup-code bootstrap returns a node device token with scopes: [] plus a bounded operator handoff token for trusted mobile onboarding. The operator handoff can read setup-time native configuration but does not grant pairing mutation scopes or operator.admin.
Fastest: openclaw dashboard (prints + copies the dashboard URL, tries to open; shows an SSH hint if headless).
No token yet: openclaw doctor --generate-gateway-token.
Remote: tunnel first with ssh -N -L 18789:127.0.0.1:18789 user@host, then open http://127.0.0.1:18789/.
Shared-secret mode: set gateway.auth.token / OPENCLAW_GATEWAY_TOKEN or gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD, then paste the matching secret in Control UI settings.
Tailscale Serve mode: confirm gateway.auth.allowTailscale is enabled and you are opening the Serve URL, not a raw loopback/tailnet URL that bypasses Tailscale identity headers.
Trusted-proxy mode: confirm you are coming through the configured identity-aware proxy. Same-host loopback proxies also need gateway.auth.trustedProxy.allowLoopback = true.
Mismatch persists after the one retry: rotate/re-approve the paired device token:
Rotate denied: paired-device sessions can rotate only their own device unless they also have operator.admin, and explicit --scope values cannot exceed the caller's current operator scopes.
Still stuck: openclaw status --all plus Troubleshooting. See Dashboard for auth details.

--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789

openclaw gateway install --force

{
      gateway: {
        mode: "remote",
        remote: {
          url: "ws://gateway.tailnet:18789",
          token: "your-token",
          password: "your-password",
        },
      },
    }

openclaw devices list
      openclaw devices rotate --device <id> --role operator

Logging and debugging

주요 항목:

macOS launchd stdout: ~/Library/Logs/openclaw/gateway.log (profiles use gateway-<profile>.log; stderr is suppressed).
Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager.
Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST.
BOT_COMMANDS_TOO_MUCH: the Telegram menu has too many entries. OpenClaw already trims to the Telegram limit and retries with fewer commands, but some menu entries may still be dropped. Reduce plugin/skill/custom commands, or disable channels.telegram.commands.native if you do not need the menu.
TypeError: fetch failed, Network request for 'setMyCommands' failed!, or similar network errors: on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works for api.telegram.org.

openclaw logs --follow

openclaw gateway status
    openclaw gateway restart

wsl
    openclaw gateway status
    openclaw gateway restart

openclaw gateway status
    openclaw gateway restart

Media and attachments

Outbound attachments from the agent must use structured media fields such as media, mediaUrl, path, or filePath. See OpenClaw assistant setup and Agent send.

openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png

Security and access control

Treat inbound DMs as untrusted input. Defaults reduce risk:

주요 항목:

Default behavior on DM-capable channels is pairing: unknown senders receive a pairing code and their message is not processed. Approve with openclaw pairing approve --channel <channel> [--account <id>] <code>. Pending requests are capped at 3 per channel; check openclaw pairing list --channel <channel> [--account <id>] if a code did not arrive.
Opening DMs publicly requires explicit opt-in (dmPolicy: "open" and allowlist "*").
use a read-only or tool-disabled "reader" agent to summarize untrusted content
keep web_search / web_fetch / browser off for tool-enabled agents
treat decoded file/document text as untrusted too: OpenResponses input_file and media-attachment extraction both wrap extracted text in explicit external-content boundary markers instead of passing raw file text
sandbox and use strict tool allowlists

openclaw security audit --deep
    openclaw gateway status

openclaw pairing list telegram

openclaw pairing approve whatsapp <code>
    openclaw pairing list whatsapp

Chat commands, aborting tasks, and "it will not stop"

Most internal/tool messages only appear when verbose, trace, or reasoning is enabled for that session.

주요 항목:

steer (default) - guide the active run at the next model boundary.
followup - queue messages and run them one at a time after the current run ends.
collect - queue compatible messages and reply once after the current run ends.
interrupt - abort the current run and start fresh.

/verbose off
    /trace off
    /reasoning off

process action:kill sessionId:XXX

{
      tools: {
        message: {
          crossContext: {
            allowAcrossProviders: true,
            marker: { enabled: true, prefix: "[from {channel}] " },
          },
        },
      },
    }

Miscellaneous

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/help/faq
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw status

openclaw status --all

openclaw gateway status

openclaw status --deep

openclaw logs --follow

tail -f "/tmp/openclaw/openclaw-$(date +%F).log"
    # Named profile example:
    tail -f "/tmp/openclaw/openclaw-dev-$(date +%F).log"

FAQ

핵심 요약

문서 구성

상세 내용

본문

First 60 seconds if something is broken

Quick start and first-run setup

What is OpenClaw?

Skills and automation

Sandboxing and memory

Where things live on disk

Config basics

Remote gateways and nodes

Env vars and .env loading

Sessions and multiple chats

Models, failover, and auth profiles

Gateway: ports, "already running", and remote mode

Logging and debugging

Media and attachments

Security and access control

Chat commands, aborting tasks, and "it will not stop"

Miscellaneous

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

FAQ

핵심 요약

문서 구성

상세 내용

본문

First 60 seconds if something is broken

Quick start and first-run setup

What is OpenClaw?

Skills and automation

Sandboxing and memory

Where things live on disk

Config basics

Remote gateways and nodes

Env vars and .env loading

Sessions and multiple chats

Models, failover, and auth profiles

Gateway: ports, "already running", and remote mode

Logging and debugging

Media and attachments

Security and access control

Chat commands, aborting tasks, and "it will not stop"

Miscellaneous

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드