---
summary: "FAQ: quick-start and first-run setup — install, onboard, auth, subscriptions, initial failures"
read_when:
  - New install, onboarding stuck, or first-run errors
  - Choosing auth and provider subscriptions
  - Cannot access docs.openclaw.ai, cannot open dashboard, install stuck
title: "FAQ: first-run setup"
sidebarTitle: "First-run FAQ"
---

Quick-start and first-run Q&A. For everyday operations, models, auth, sessions,
and troubleshooting see the main [FAQ](/help/faq).

## Quick start and first-run setup

<AccordionGroup>
  <Accordion title="Recommended way to install and set up OpenClaw">
    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```

    The installer starts guided onboarding for you, so there is no separate
    onboarding command to run. When onboarding finishes, press **Ctrl+C** to
    stop the foreground Gateway and install the background service:

    ```bash
    openclaw gateway install
    ```

    Prefer the classic step-by-step wizard and a service install in one
    command? Run `openclaw onboard --install-daemon` instead of the two
    commands above. That flag selects the classic flow, so you do not see the
    guided **Quick start** and **Custom setup** choice.

    From source (contributors/dev):

    ```bash
    git clone https://github.com/openclaw/openclaw.git
    cd openclaw
    pnpm install
    pnpm build
    pnpm ui:build
    openclaw onboard
    ```

    No global install yet? Run `pnpm openclaw onboard` instead. If Control UI assets are
    missing, onboarding tries to build them itself, falling back to `pnpm ui:build`.

  </Accordion>

<a id="i-am-stuck" />

  <Accordion title="I am stuck, fastest way to get unstuck">
    Use a local AI agent that can **see your machine**. Most "I'm stuck" cases are
    **local config or environment issues** a remote helper cannot inspect, so this beats
    asking in Discord.

    - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/)
    - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/)

    Give the agent the full source checkout via the hackable (git) install so it can read
    code + docs and reason about the exact version you run:

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    ```

    Ask the agent to plan and supervise the fix step-by-step, then execute only the
    necessary commands - smaller diffs are easier to audit.

    Share these outputs when asking for help (in Discord or a GitHub issue):

    | Command | Shows |
    | --- | --- |
    | `openclaw status` | Gateway/agent health + basic config snapshot |
    | `openclaw status --all` | Full read-only diagnosis, pasteable |
    | `openclaw models status` | Provider auth + model availability |
    | `openclaw doctor` | Validates and repairs common config/state issues |
    | `openclaw logs --follow` | Live log tail |
    | `openclaw gateway status --deep` | Deep gateway/config/plugin health check |
    | `openclaw health --verbose` | Detailed health report |

    Found a real bug or fix? File an issue or send a PR:
    [Issues](https://github.com/openclaw/openclaw/issues) /
    [Pull requests](https://github.com/openclaw/openclaw/pulls).

    Quick debug loop: [First 60 seconds if something is broken](/help/faq#first-60-seconds-if-something-is-broken).
    Install docs: [Install](/install), [Installer flags](/install/installer), [Updating](/install/updating).

  </Accordion>

  <Accordion title="How do I open the dashboard after onboarding?">
    Onboarding opens your browser to a clean (non-tokenized) dashboard URL right after
    setup and prints the link in the summary. Keep that tab open; if it did not launch,
    copy/paste the printed URL on the same machine.
  </Accordion>

  <Accordion title="How do I authenticate the dashboard on localhost vs remote?">
    **Localhost (same machine):**

    - Open `http://127.0.0.1:18789/`.
    - If it asks for shared-secret auth, paste the configured token or password into Control UI settings.
    - Token source: `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
    - Password source: `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
    - No shared secret configured yet? Run `openclaw doctor --generate-gateway-token` (or `openclaw doctor --fix --generate-gateway-token`).

    **Not on localhost:**

    - **Tailscale Serve** (recommended): keep bind loopback, run `openclaw gateway --tailscale serve`, open `https://<magicdns>/`. With `gateway.auth.allowTailscale: true`, identity headers satisfy Control UI/WebSocket auth (no pasted shared secret, assumes a trusted gateway host); HTTP APIs still need shared-secret auth unless you deliberately use private-ingress `none` or trusted-proxy HTTP auth.
      Concurrent bad-auth Serve attempts from the same client are serialized before the failed-auth limiter records them, so a second bad retry can already show `retry later`.
    - **Identity-aware reverse proxy**: keep the Gateway behind a trusted proxy, set `gateway.auth.mode: "trusted-proxy"`, open the proxy URL. Same-host loopback proxies need explicit `gateway.auth.trustedProxy.allowLoopback: true`.
    - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@gateway-host`, then open `http://127.0.0.1:18789/`. Shared-secret auth still applies over the tunnel; paste the configured token or password if prompted.

    See [Dashboard](/web/dashboard) and [Web surfaces](/web) for bind modes and auth details.

  </Accordion>

  <Accordion title="Heartbeat keeps skipping. What do the skip reasons mean?">
    | Skip reason | Meaning |
    | --- | --- |
    | `quiet-hours` | Outside the configured active-hours window |
    | `empty-heartbeat-file` | Heartbeat monitor scratch exists but only has blank, comment, header, fence, or empty-checklist scaffolding |
    | `alerts-disabled` | All heartbeat visibility is off (`showOk`, `showAlerts`, and `useIndicator` all disabled) |

    Older heartbeat `tasks:` blocks migrate to independently scheduled cron jobs with `openclaw doctor --fix`.

    Docs: [Heartbeat](/gateway/heartbeat), [Automation](/automation).

  </Accordion>

  <Accordion title="Why are there two exec approval configs for chat approvals?">
    They control different layers:

    - `approvals.exec` - forwards approval prompts to chat destinations.
    - `channels.<channel>.execApprovals` - makes that channel a native approval client for exec approvals.

    The host exec policy is still the real approval gate; chat config only controls where
    prompts appear and how people answer them.

    You rarely need both:

    - If the chat already supports commands and replies, same-chat `/approve` works through the shared path.
    - For supported native clients, set `channels.<channel>.execApprovals.enabled: "auto"` or `true` and configure approvers or the channel's supported owner identity. Discord and Slack require explicit enablement; Telegram treats unset as `"auto"`.
    - When native approval cards/buttons are available, that UI is primary; only mention a manual `/approve` command if the tool result says chat approvals are unavailable.
    - Use `approvals.exec` only when prompts must also reach other chats or explicit ops rooms.
    - Use `channels.<channel>.execApprovals.target: "channel"` or `"both"` only when you want approval prompts posted back into the originating room/topic.
    - Plugin approvals are separate: same-chat `/approve` by default, optional `approvals.plugin` forwarding, and only some native channels keep native handling for those too.

    Short version: forwarding is for routing, native client config is for richer channel-specific UX.
    See [Exec Approvals](/tools/exec-approvals).

  </Accordion>

  <Accordion title="What runtime do I need?">
    Node **24.16+** or **26.1+** is the primary and default runtime (Node 26 recommended). `pnpm` is the repo package manager.
    Bun 1.4+ builds with WAL-reset-safe `node:sqlite` can run the CLI, Gateway, and managed node host as an explicit opt-in.
  </Accordion>

  <Accordion title="Does it run on Raspberry Pi?">
    Yes, but check RAM first: Pi 5 and Pi 4 (2 GB+) are the sweet spot; Pi 3B+ (1 GB) works but is slow; Pi Zero 2 W (512 MB) is not recommended.

    | Model | RAM | Fit |
    | --- | --- | --- |
    | Pi 5 | 4/8 GB | Best |
    | Pi 4 | 4 GB | Good |
    | Pi 4 | 2 GB | OK, add swap |
    | Pi 4 | 1 GB | Tight |
    | Pi 3B+ | 1 GB | Slow |
    | Pi Zero 2 W | 512 MB | Not recommended |

    Absolute minimum: 1 GB RAM, 1 core, 500 MB free disk, 64-bit OS. Since the Pi only runs
    the Gateway (models call out to cloud APIs), even a modest Pi handles the load.

    A small Pi/VPS can also host just the Gateway while you pair **nodes** on your
    laptop/phone for local screen/camera or command execution. A paired Mac can
    also present hosted widgets in its native panel. See [Nodes](/nodes).

    Full setup walkthrough: [Raspberry Pi](/install/raspberry-pi).

  </Accordion>

  <Accordion title="Any tips for Raspberry Pi installs?">
    - Use a **64-bit** OS; do not use 32-bit Raspberry Pi OS.
    - Add swap on 2 GB or smaller boards.
    - Prefer a **USB SSD** over an SD card for performance and longevity.
    - Prefer the hackable (git) install so you can see logs and update fast.
    - Start without channels/skills, add them one by one.
    - Weird binary failures ("exec format error") are usually a missing ARM64 build for an optional skill tool.

    Full guide: [Raspberry Pi](/install/raspberry-pi). Also see [Linux](/platforms/linux).

  </Accordion>

  <Accordion title="It is stuck on wake up my friend / onboarding will not hatch. What now?">
    That screen depends on the Gateway being reachable and authenticated. The TUI also sends
    "Wake up, my friend!" automatically on first hatch when a model provider is configured. If
    you skipped model/auth setup, onboarding shows a "Model auth missing" note and opens the
    TUI without sending anything — add a provider by running `openclaw onboard` again.
    That is the one command for changing the model provider or its authentication.
    If you see the wake-up line with **no reply** and tokens stay at 0, the agent never ran.

    1. Restart the Gateway:

    ```bash
    openclaw gateway restart
    ```

    2. Check status + auth:

    ```bash
    openclaw status
    openclaw models status
    openclaw logs --follow
    ```

    3. Still hanging? Run:

    ```bash
    openclaw doctor
    ```

    If the Gateway is remote, confirm the tunnel/Tailscale connection is up and the UI
    points at the right Gateway. See [Remote access](/gateway/remote).

  </Accordion>

  <Accordion title="Can I migrate my setup to a new machine without redoing onboarding?">
    Yes. Copy the **state directory** and **workspace**, then run Doctor once:

    1. Install OpenClaw on the new machine.
    2. Copy `$OPENCLAW_STATE_DIR` (default: `~/.openclaw`) from the old machine.
    3. Copy your workspace (default: `~/.openclaw/workspace`).
    4. Run `openclaw doctor` and restart the Gateway service.

    This preserves config, auth profiles, WhatsApp creds, sessions, and memory - it keeps
    your bot exactly the same, as long as you copy **both** locations. In remote mode, the
    gateway host owns the session store and workspace.

    **Important:** if you only commit/push your workspace to GitHub, you back up
    **memory + bootstrap files**, but not session history or auth. Those live under
    `~/.openclaw/` (for example `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`).

    Related: [Migrating](/install/migrating), [Where things live on disk](/help/faq#where-things-live-on-disk),
    [Agent workspace](/concepts/agent-workspace), [Doctor](/gateway/doctor),
    [Remote mode](/gateway/remote).

  </Accordion>

  <Accordion title="Where do I see what is new in the latest version?">
    Check the GitHub changelog:
    [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)

    Newest entries are at the top. If the top section is **Unreleased**, the next dated
    section is the latest shipped version. Entries group under **Highlights**, **Changes**,
    and **Fixes** (plus docs/other sections when needed).

  </Accordion>

  <Accordion title="Cannot access docs.openclaw.ai (SSL error)">
    Some Comcast/Xfinity connections incorrectly block `docs.openclaw.ai` via Xfinity
    Advanced Security. Disable it or allowlist `docs.openclaw.ai`, then retry. Help us
    get it unblocked: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status).

    Still blocked? Docs are mirrored on GitHub:
    [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs)

  </Accordion>

  <Accordion title="Difference between stable and beta">
    **Stable** and **beta** are **npm dist-tags**, not separate code lines:

    - `latest` = stable
    - `beta` = early build for testing (falls back to `latest` when beta is missing or older than the current stable release)

    A stable release usually lands on **beta** first, then an explicit promotion step
    moves that same version to `latest` without changing the version number. Maintainers
    can also publish straight to `latest`. That is why beta and stable can point at the
    **same version** after promotion.

    See what changed: [CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md).

    For install one-liners and the difference between beta and dev, see the next accordion.

  </Accordion>

  <Accordion title="How do I install the beta version and what is the difference between beta and dev?">
    **Beta** is the npm dist-tag `beta` (may match `latest` after promotion).
    **Dev** is the moving head of `main` (git); when published to npm it uses dist-tag `dev`.

    One-liners (macOS/Linux):

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta
    ```

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    ```

    Windows installer (PowerShell): `iwr -useb https://openclaw.ai/install.ps1 | iex`

    More detail: [Development channels](/install/development-channels) and [Installer flags](/install/installer).

  </Accordion>

  <Accordion title="How do I try the latest bits?">
    Two options:

    1. **Dev channel (existing install):**

    ```bash
    openclaw update --channel dev
    ```

    This switches to a git checkout of `main`, rebases on upstream, builds, and installs
    the CLI from that checkout.

    2. **Hackable (git) install (fresh machine):**

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    ```

    Prefer a manual clone:

    ```bash
    git clone https://github.com/openclaw/openclaw.git
    cd openclaw
    pnpm install
    pnpm build
    ```

    Docs: [Update](/cli/update), [Development channels](/install/development-channels), [Install](/install).

  </Accordion>

  <Accordion title="How long does install and onboarding usually take?">
    Rough guide:

    - **Install:** 2-5 minutes.
    - **QuickStart onboarding:** a few minutes (loopback gateway, auto token, default workspace).
    - **Advanced/full onboarding:** longer when provider sign-in, channel pairing, daemon install, network downloads, or skills need extra setup.

    The wizard shows this timeline up front. Skip optional steps and return later with
    `openclaw configure`.

    Hanging? See [I am stuck](#i-am-stuck) above.

  </Accordion>

  <Accordion title="Installer stuck? How do I get more feedback?">
    Re-run with `--verbose`:

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --verbose
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta --verbose
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
    ```

    `install.ps1` has no dedicated verbose switch; wrap it in `Set-PSDebug -Trace 1` /
    `-Trace 0` instead. Full flag reference: [Installer flags](/install/installer).

  </Accordion>

  <Accordion title="Windows install says git not found or openclaw not recognized">
    Two common Windows issues:

    **1) npm error spawn git / git not found**

    - Install **Git for Windows**, make sure `git` is on PATH.
    - Close and reopen PowerShell, then re-run the installer.

    **2) openclaw is not recognized after install**

    - Your npm global bin folder is not on PATH.
    - Check it: `npm config get prefix`.
    - Add that directory to your user PATH (no `\bin` suffix needed; on most systems it is `%AppData%\npm`).
    - Close and reopen PowerShell.

    Prefer a desktop app? Use **Windows Hub**. Terminal-only setup: the PowerShell
    installer and WSL2 Gateway paths are both supported. Docs: [Windows](/platforms/windows).

  </Accordion>

  <Accordion title="Windows exec output shows garbled Chinese text - what should I do?">
    Usually a console code page mismatch on native Windows shells.

    Symptoms: `system.run`/`exec` output renders Chinese as mojibake; the same command
    looks fine in another terminal profile.

    Workaround in PowerShell:

    ```powershell
    chcp 65001
    [Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
    [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
    $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
    ```

    Then restart the Gateway and retry:

    ```powershell
    openclaw gateway restart
    ```

    Still reproducing this on latest OpenClaw? Track/report it: [Issue #30640](https://github.com/openclaw/openclaw/issues/30640).

  </Accordion>

  <Accordion title="The docs did not answer my question - how do I get a better answer?">
    Use the hackable (git) install so you have the full source and docs locally, then ask
    your bot (or Claude/Codex) **from that folder** so it can read the repo and answer precisely.

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    ```

    More detail: [Install](/install) and [Installer flags](/install/installer).

  </Accordion>

  <Accordion title="How do I install OpenClaw on Linux?">
    - Linux quick path + service install: [Linux](/platforms/linux).
    - Full walkthrough: [Getting Started](/start/getting-started).
    - Installer + updates: [Install & updates](/install/updating).

  </Accordion>

  <Accordion title="How do I install OpenClaw on a VPS?">
    Any Linux VPS works. Install on the server, then reach the Gateway over SSH/Tailscale.

    Guides: [exe.dev](/install/exe-dev), [Hetzner](/install/hetzner), [Fly.io](/install/fly).
    Remote access: [Gateway remote](/gateway/remote).

  </Accordion>

  <Accordion title="Where are the cloud/VPS install guides?">
    Hosting hub with common providers:

    - [VPS hosting](/vps) (all providers in one place)
    - [Fly.io](/install/fly)
    - [Hetzner](/install/hetzner)
    - [exe.dev](/install/exe-dev)

    In the cloud, the **Gateway runs on the server** and you access it from your laptop/phone
    via the Control UI (or Tailscale/SSH). Your state + workspace live on the server, so
    treat the host as the source of truth and back it up.

    Pair **nodes** (Mac/iOS/Android/headless) to that cloud Gateway for local
    screen/camera or command execution on your laptop while the Gateway stays in
    the cloud.

    Hub: [Platforms](/platforms). Remote access: [Gateway remote](/gateway/remote).
    Nodes: [Nodes](/nodes), [Nodes CLI](/cli/nodes).

  </Accordion>

  <Accordion title="Can I ask OpenClaw to update itself?">
    Possible, not recommended. The update flow can restart the Gateway (dropping the
    active session), may need a clean git checkout, and can prompt for confirmation.
    Safer to run updates from a shell as the operator.

    ```bash
    openclaw update
    openclaw update status
    openclaw update --channel stable|extended-stable|beta|dev
    openclaw update --tag <dist-tag|version>
    openclaw update --no-restart
    ```

    Automating from an agent:

    ```bash
    openclaw update --yes --no-restart
    openclaw gateway restart
    ```

    Docs: [Update](/cli/update), [Updating](/install/updating).

  </Accordion>

  <Accordion title="What does onboarding actually do?">
    `openclaw onboard` is the recommended setup path. On a fresh local install it
    offers two lanes after a one-line pointer to the [security guide](/gateway/security):

    - **Quick start** detects the AI access you already have, waits for you to
      choose a connection, verifies that one choice with a real completion,
      prepares the agent workspace, and then starts the Gateway in the
      foreground and opens the browser dashboard. It uses the default agent
      name `main` and full access, and skips memory import and app
      recommendations. Choose **Skip for now** in the picker to prepare the
      local baseline and exit without starting the Gateway or AI chat.
    - **Custom setup** runs the same guided flow with the telemetry choice,
      agent name, access mode, and optional setup prompts kept as questions.

    Both lanes require an explicit provider choice before any live completion,
    provider installation, model selection, or credential write.

    The classic step-by-step wizard is still available. Run
    `openclaw onboard --classic` for its Workspace, Model/Auth, Gateway,
    Channels, Web search, Skills, Daemon, and Health check steps. The step list
    is in [Onboarding (CLI)](/start/wizard#what-classic-onboarding-configures).

    Quick start is not offered for configured installs, remote Gateway chat
    setup, non-interactive runs, or runs with `--skip-ui` or `--tui`.
    Full breakdown: [Onboarding (CLI)](/start/wizard).

  </Accordion>

  <Accordion title="Do I need a Claude or OpenAI subscription to run this?">
    No. Run OpenClaw with **API keys** (Anthropic/OpenAI/others) or **local-only models**
    so your data stays on your device. Subscriptions (Claude Pro/Max, ChatGPT/Codex) are
    optional ways to authenticate those providers.

    For Anthropic: an **API key** gives standard pay-as-you-go billing; **Claude CLI**
    reuses an existing Claude Code login on the same host. Anthropic currently treats
    Claude CLI's non-interactive `claude -p` path as Agent SDK/programmatic usage that
    still draws from your subscription's plan limits - check current Anthropic billing
    docs before relying on subscription behavior. For long-lived gateway hosts and shared
    automation, an Anthropic API key is the more predictable choice.

    OpenAI Codex OAuth (ChatGPT/Codex subscription) is fully supported for agent models.
    OpenClaw also supports hosted subscription-style options including **Qwen Cloud
    Coding Plan**, **MiniMax Coding Plan**, and **Z.AI / GLM Coding Plan**.

    Docs: [Anthropic](/providers/anthropic), [OpenAI](/providers/openai),
    [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), [Z.AI (GLM)](/providers/zai),
    [Local models](/gateway/local-models), [Models](/concepts/models).

  </Accordion>

  <Accordion title="Can I use Claude Max subscription without an API key?">
    Yes. OpenClaw supports Claude CLI reuse for Pro/Max/Team/Enterprise plans. Anthropic
    currently treats the `claude -p` path OpenClaw uses as subscription-plan usage subject
    to your plan's limits, not a separate free allowance - see
    [Anthropic](/providers/anthropic) for the current billing detail and links to
    Anthropic's own support articles. For the most predictable server-side setup, use an
    Anthropic API key instead.
  </Accordion>

  <Accordion title="Do you support Claude subscription auth (Claude Pro or Max)?">
    Yes, via Claude CLI reuse. Anthropic's billing treatment of `claude -p`/Agent SDK usage
    has changed over time; see [Anthropic](/providers/anthropic) for the current state and
    dated links to Anthropic's support articles before relying on specific billing
    behavior.

    Anthropic setup-token auth is also still a supported token path, but OpenClaw prefers
    Claude CLI reuse and `claude -p` when available. For production or multi-user
    workloads, an Anthropic API key remains the safer, more predictable choice. Other
    subscription-style hosted options: [OpenAI](/providers/openai), [Qwen Cloud](/providers/qwen),
    [MiniMax](/providers/minimax), [Z.AI (GLM)](/providers/zai).

  </Accordion>

</AccordionGroup>

<a id="why-am-i-seeing-http-429-ratelimiterror-from-anthropic"></a>

<AccordionGroup>
  <Accordion title="Why am I seeing HTTP 429 rate_limit_error from Anthropic?">
    Your **Anthropic quota/rate limit** is exhausted for the current window. On **Claude
    CLI**, wait for the window to reset or upgrade your plan. On an **Anthropic API key**,
    check usage/billing in the Anthropic Console and raise limits as needed.

    If the message is specifically `Extra usage is required for long context requests`,
    the request is trying to use Anthropic's 1M context window (a GA-capable 1M Claude 4.x
    model, or legacy `params.context1m: true` config), and your current credential is not
    eligible for long-context billing.

    Set a **fallback model** so OpenClaw keeps replying while a provider is rate-limited.
    See [Models](/cli/models), [OAuth](/concepts/oauth), and
    [Anthropic 429 extra usage required for long context](/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context).

  </Accordion>

  <Accordion title="Is AWS Bedrock supported?">
    Yes. OpenClaw has a bundled **Amazon Bedrock (Converse)** provider. With AWS env
    markers present (`AWS_ACCESS_KEY_ID`, `AWS_PROFILE`, `AWS_BEARER_TOKEN_BEDROCK`),
    OpenClaw auto-enables the implicit Bedrock provider for model discovery; otherwise
    set `plugins.entries.amazon-bedrock.config.discovery.enabled: true` or add a manual
    provider entry. See [Amazon Bedrock](/providers/bedrock) and [Model providers](/providers/models).
    An OpenAI-compatible proxy in front of Bedrock is still a valid option if you prefer a managed key flow.
  </Accordion>

  <Accordion title="How does Codex auth work?">
    OpenClaw supports **OpenAI Codex** via OAuth (ChatGPT sign-in). A fresh
    setup with no primary model uses exact `openai/gpt-5.6-sol` for
    ChatGPT/Codex subscription auth plus native Codex app-server execution.
    Reauthentication preserves an existing explicit model, including
    `openai/gpt-5.5`. If the Codex workspace does not expose GPT-5.6, select
    `openai/gpt-5.5` explicitly; OpenClaw does not silently downgrade. Legacy
    Codex-prefixed model refs are legacy config repaired by `openclaw doctor
    --fix`. Direct OpenAI API-key access remains available for non-agent OpenAI
    API surfaces and, through an ordered `openai` API-key profile, for agent
    models too. See [Model providers](/concepts/model-providers) and
    [Onboarding (CLI)](/start/wizard).
  </Accordion>

  <Accordion title="Why does OpenClaw still mention legacy OpenAI Codex prefix?">
    `openai` is the current provider and auth-profile id for both OpenAI API keys and
    ChatGPT/Codex OAuth - OpenAI Codex is folded into it. You may still see a legacy
    `openai-codex` prefix in older config and migration warnings:

    - `openai/gpt-5.6-sol` = fresh ChatGPT/Codex subscription setup with the native Codex runtime for agent turns.
    - `openai/gpt-5.5` = explicit supported selection for existing config or accounts without GPT-5.6 access.
    - Legacy `openai-codex/*` model refs = legacy route repaired by `openclaw doctor --fix`.
    - `openai/gpt-5.5` plus an ordered `openai` API-key profile = API-key auth for an OpenAI agent model.
    - Legacy `openai-codex` auth profile ids = legacy ids migrated by `openclaw doctor --fix`.

    Want direct OpenAI Platform billing? Set `OPENAI_API_KEY`. Want ChatGPT/Codex
    subscription auth? Run `openclaw models auth login --provider openai`. Keep
    model refs under the canonical `openai/*` provider. Fresh subscription
    setup uses exact `openai/gpt-5.6-sol`; doctor repairs legacy Codex-prefixed
    refs without upgrading an explicit `openai/gpt-5.5` selection.

  </Accordion>

  <Accordion title="Why can Codex OAuth limits differ from ChatGPT web?">
    Codex OAuth uses OpenAI-managed, plan-dependent quota windows that can differ from the
    ChatGPT website/app experience, even on the same account.

    `openclaw models status` shows the currently visible provider usage/quota windows, but
    does not invent or normalize ChatGPT-web entitlements into direct API access. For the
    direct OpenAI Platform billing/limit path, use `openai/*` with an API key.

  </Accordion>

  <Accordion title="Do you support OpenAI subscription auth (Codex OAuth)?">
    Yes, fully. OpenAI explicitly allows subscription OAuth usage in external
    tools/workflows like OpenClaw. Onboarding can run the OAuth flow for you.

    See [OAuth](/concepts/oauth), [Model providers](/concepts/model-providers), and [Onboarding (CLI)](/start/wizard).

  </Accordion>

  <Accordion title="Can I use Gemini CLI or Antigravity OAuth?">
    OpenClaw does not offer new Gemini CLI OAuth or Antigravity OAuth setup.
    Connect Google with an AI Studio API key or Vertex AI instead.

    The optional `google-gemini-cli` runtime remains available for advanced
    setups using a supported Google API-key profile. Existing valid legacy
    Gemini CLI OAuth profiles remain executable for compatibility, but OpenClaw
    cannot create or repair them.

    Details: [Google](/providers/google), [Model providers](/concepts/model-providers).

  </Accordion>

  <Accordion title="Is a local model OK for casual chats?">
    Usually no. OpenClaw needs large context + strong safety; small cards truncate context
    and skip provider-side safety filters. If you must, run the **largest** model build you
    can locally (LM Studio) - see [Local models](/gateway/local-models). Smaller/quantized
    models raise prompt-injection risk - see [Security](/gateway/security).
  </Accordion>

  <Accordion title="How do I keep hosted model traffic in a specific region?">
    Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi,
    and GLM; choose the US-hosted variant to keep data in-region. You can still list
    Anthropic/OpenAI alongside these with `models.mode: "merge"` so fallbacks stay
    available while respecting the regioned provider you select.
  </Accordion>

  <Accordion title="Do I have to buy a Mac Mini to install this?">
    No. OpenClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is a popular
    always-on host choice, but a small VPS, home server, or Raspberry Pi-class box works too.

    You only need a Mac **for macOS-only tools**. For iMessage, use [iMessage](/channels/imessage)
    with `imsg` on any Mac signed into Messages - if the Gateway runs on Linux or elsewhere,
    set `channels.imessage.cliPath` to an SSH wrapper that runs `imsg` on that Mac. For other
    macOS-only tools, run the Gateway on a Mac or pair a macOS node.

    Docs: [iMessage](/channels/imessage), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).

  </Accordion>

  <Accordion title="Do I need a Mac mini for iMessage support?">
    You need **some macOS device** signed into Messages - not necessarily a Mac mini, any
    Mac works. Use [iMessage](/channels/imessage) with `imsg`; the Gateway can run on that
    Mac, or elsewhere with an SSH wrapper `cliPath`.

    Common setups:

    - Gateway on Linux/VPS, `channels.imessage.cliPath` set to an SSH wrapper that runs `imsg` on a Mac signed into Messages.
    - Everything on one Mac for the simplest single-machine setup.

    Docs: [iMessage](/channels/imessage), [Nodes](/nodes), [Mac remote mode](/platforms/mac/remote).

  </Accordion>

  <Accordion title="If I buy a Mac mini to run OpenClaw, can I connect it to my MacBook Pro?">
    Yes. The **Mac mini can run the Gateway**, and your MacBook Pro connects as a **node**
    (companion device). Nodes do not run the Gateway - they add capabilities like
    screen/camera and `system.run` on that device. A Mac node can also present
    hosted widgets in its native panel.

    Common pattern: Gateway on the always-on Mac mini; MacBook Pro runs the macOS app or a
    node host and pairs to the Gateway. Check with `openclaw nodes status` / `openclaw nodes list`.

    Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes).

  </Accordion>

  <Accordion title="Can I use Bun?">
    Yes. Node remains the primary, default, and recommended runtime, but Bun 1.4+
    with WAL-reset-safe `node:sqlite` can run the CLI, Gateway, and managed node
    host as an explicit opt-in. Bun can also run package scripts; use
    `pnpm install` for dependency installation.
  </Accordion>

  <Accordion title="Telegram: what goes in allowFrom?">
    `channels.telegram.allowFrom` is the **human sender's Telegram user ID** (numeric),
    not the bot username. Setup asks for numeric user IDs only; `openclaw doctor --fix`
    can try to resolve legacy `@username` entries.

    Safer (no third-party bot): DM your bot, run `openclaw logs --follow`, read `from.id`.

    Official Bot API: DM your bot, call `https://api.telegram.org/bot<bot_token>/getUpdates`, read `message.from.id`.

    Third-party (less private): DM `@userinfobot` or `@getidsbot`.

    See [Telegram access control](/channels/telegram#access-control-and-activation).

  </Accordion>

  <Accordion title="Can multiple people use one WhatsApp number with different OpenClaw instances?">
    Yes, via **multi-agent routing**. Bind each sender's WhatsApp DM (`peer: { kind: "direct", id: "+15551234567" }`) to a different `agentId`, giving each person their own workspace and session store. Replies still come from the **same WhatsApp account**; DM access control (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) is global per account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/channels/whatsapp).
  </Accordion>

  <Accordion title='Can I run a "fast chat" agent and an "Opus for coding" agent?'>
    Yes. Use multi-agent routing: give each agent its own default model, then bind inbound
    routes (provider account or specific peers) to each agent. Example config:
    [Multi-Agent Routing](/concepts/multi-agent). See also [Models](/concepts/models) and
    [Configuration](/gateway/configuration).
  </Accordion>

  <Accordion title="Does Homebrew work on Linux?">
    Yes, via Linuxbrew:

    ```bash
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
    brew install <formula>
    ```

    Running OpenClaw via systemd: make sure the service PATH includes
    `/home/linuxbrew/.linuxbrew/bin` (or your brew prefix) so `brew`-installed tools
    resolve in non-login shells. Recent builds also prepend common user bin dirs on Linux
    systemd services (for example `~/.local/bin`, `~/.npm-global/bin`,
    `~/.local/share/pnpm`, `~/.bun/bin`) and honor `PNPM_HOME`, `NPM_CONFIG_PREFIX`,
    `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR`, and `FNM_DIR` when set.

  </Accordion>

  <Accordion title="Difference between the hackable git install and npm install">
    - **Hackable (git) install:** full source checkout, editable, best for contributors. You build locally and can patch code/docs.
    - **npm install:** global CLI install, no repo, best for "just run it." Updates come from npm dist-tags.

    Docs: [Getting started](/start/getting-started), [Updating](/install/updating).

  </Accordion>

  <Accordion title="Can I switch between npm and git installs later?">
    Yes, with `openclaw update --channel ...` on an existing install. This does **not
    delete your data** - only the OpenClaw code install changes. State (`~/.openclaw`) and
    workspace (`~/.openclaw/workspace`) stay untouched.

    npm to git:

    ```bash
    openclaw update --channel dev
    ```

    git to npm:

    ```bash
    openclaw update --channel stable
    ```

    Add `--dry-run` to preview the planned mode switch first. The updater runs Doctor
    follow-ups, refreshes plugin sources for the target channel, and restarts the gateway
    unless you pass `--no-restart`.

    The installer can force either mode too:

    ```bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method npm
    ```

    Backup tips: [Where things live on disk](/help/faq#where-things-live-on-disk).

  </Accordion>

  <Accordion title="Should I run the Gateway on my laptop or a VPS?">
    Want 24/7 reliability? Use a **VPS**. Want the lowest friction and you are OK with
    sleep/restarts? Run it locally.

    **Laptop (local Gateway)**

    - **Pros:** no server cost, direct access to local files, a live browser window.
    - **Cons:** sleep/network drops disconnect it, OS updates/reboots interrupt it, must stay awake.

    **VPS / cloud**

    - **Pros:** always-on, stable network, no laptop sleep issues, easier to keep running.
    - **Cons:** often headless (use screenshots), remote file access only, SSH needed for updates.

    WhatsApp/Telegram/Slack/Mattermost/Discord all work fine from a VPS - the real
    trade-off is headless browser vs a visible window. See [Browser](/tools/browser).

    Default recommendation: VPS if you have had gateway disconnects before; local is great
    when you are actively using the Mac and want local file access or visible-browser UI
    automation.

  </Accordion>

  <Accordion title="How important is it to run OpenClaw on a dedicated machine?">
    Not required, but recommended for reliability and isolation.

    - **Dedicated host (VPS/Mac mini/Raspberry Pi):** always-on, fewer sleep/reboot interruptions, cleaner permissions, easier to keep running.
    - **Shared laptop/desktop:** fine for testing and active use, but expect pauses when the machine sleeps or updates.

    Best of both worlds: keep the Gateway on a dedicated host and pair your laptop as a
    **node** for local screen/camera/exec tools. See [Nodes](/nodes) and [Security](/gateway/security).

  </Accordion>

  <Accordion title="What are the minimum VPS requirements and recommended OS?">
    - **Absolute minimum:** 1 vCPU, 1 GB RAM, ~500 MB disk.
    - **Recommended:** 1-2 vCPU, 2 GB+ RAM for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.

    OS: **Ubuntu LTS** (or any modern Debian/Ubuntu) - the best-tested Linux install path.

    Docs: [Linux](/platforms/linux), [VPS hosting](/vps).

  </Accordion>

  <Accordion title="Can I run OpenClaw in a VM and what are the requirements?">
    Yes. Treat a VM like a VPS: it needs to be always on, reachable, and have enough RAM
    for the Gateway and any channels you enable.

    - **Absolute minimum:** 1 vCPU, 1 GB RAM.
    - **Recommended:** 2 GB+ RAM for multiple channels, browser automation, or media tools.
    - **OS:** Ubuntu LTS or another modern Debian/Ubuntu.

    On Windows, use **Windows Hub** for desktop setup, or WSL2 for a Linux-style Gateway VM
    with broad tooling compatibility. See [Windows](/platforms/windows), [VPS hosting](/vps).
    Running macOS in a VM: see [macOS VM](/install/macos-vm).

  </Accordion>
</AccordionGroup>

## Related

- [FAQ](/help/faq) - the main FAQ (models, sessions, gateway, security, more)
- [Install overview](/install)
- [Getting started](/start/getting-started)
- [Troubleshooting](/help/troubleshooting)