Skip to main content
Provider auth, model, hardware, and hosting Q&A. For install, onboarding, and first-run failures see FAQ: quick start and first-run setup.
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, OAuth, and Anthropic 429 extra usage required for long context.
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 and Model providers. An OpenAI-compatible proxy in front of Bedrock is still a valid option if you prefer a managed key flow.
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 and Onboarding (CLI).
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.
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.
Yes, fully. OpenAI explicitly allows subscription OAuth usage in external tools/workflows like OpenClaw. Onboarding can run the OAuth flow for you.See OAuth, Model providers, and Onboarding (CLI).
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, Model providers.
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. Smaller/quantized models raise prompt-injection risk - see Security.
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.
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 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, Nodes, Mac remote mode.
You need some macOS device signed into Messages - not necessarily a Mac mini, any Mac works. Use 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, Nodes, Mac remote mode.
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 CLI.
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.
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.
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 and WhatsApp.
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. See also Models and Configuration.
Yes, via Linuxbrew:
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.
  • 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, Updating.
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:
git to npm:
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:
Backup tips: Where things live on disk.
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.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.
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 and Security.
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, VPS hosting. Running macOS in a VM: see macOS VM.