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.
HTTP 429: rate_limit_error from Anthropic?allowFrom?gateway.bind: "lan" (or "tailnet") and now nothing listens / the UI says unauthorized/new?coderclaw gateway status say Runtime: running but RPC probe: failed?coderclaw gateway status show Config (cli) and Config (service) different?gateway.bind: "tailnet" but it can’t bind / nothing listenscoderclaw gateway restart vs coderclaw gateway/start in Telegram but didn’t get a pairing codeQuick status (first check)
coderclaw status
Fast local summary: OS + update, gateway/service reachability, agents/sessions, provider config + runtime issues (when gateway is reachable).
Pasteable report (safe to share)
coderclaw status --all
Read-only diagnosis with log tail (tokens redacted).
Daemon + port state
coderclaw gateway status
Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used.
Deep probes
coderclaw status --deep
Runs gateway health checks + provider probes (requires a reachable gateway). See Health.
Tail the latest log
coderclaw logs --follow
If RPC is down, fall back to:
tail -f "$(ls -t /tmp/coderclaw/coderclaw-*.log | head -1)"
File logs are separate from service logs; see Logging and Troubleshooting.
Run the doctor (repairs)
coderclaw doctor
Repairs/migrates config/state + runs health checks. See Doctor.
Gateway snapshot
coderclaw health --json
coderclaw health --verbose # shows the target URL + config path on errors
Asks the running gateway for a full snapshot (WS-only). See Health.
Use a local AI agent that can see your machine. That is far more effective than asking in Discord, because most “I’m stuck” cases are local config or environment issues that remote helpers cannot inspect.
These tools can read the repo, run commands, inspect logs, and help fix your machine-level setup (PATH, services, permissions, auth files). Give them the full source checkout via the hackable (git) install:
curl -fsSL https://coderclaw.ai/install.sh | bash -s -- --install-method git
This installs CoderClaw from a git checkout, so the agent can read the code + docs and
reason about the exact version you are running. You can always switch back to stable later
by re-running the installer without --install-method git.
Tip: ask the agent to plan and supervise the fix (step-by-step), then execute only the necessary commands. That keeps changes small and easier to audit.
If you discover a real bug or fix, please file a GitHub issue or send a PR: https://github.com/SeanHogg/coderClaw/issues https://github.com/SeanHogg/coderClaw/pulls
Start with these commands (share outputs when asking for help):
coderclaw status
coderclaw models status
coderclaw doctor
What they do:
coderclaw status: quick snapshot of gateway/agent health + basic config.coderclaw models status: checks provider auth + model availability.coderclaw doctor: validates and repairs common config/state issues.Other useful CLI checks: coderclaw status --all, coderclaw logs --follow,
coderclaw gateway status, coderclaw health --verbose.
Quick debug loop: First 60 seconds if something’s broken. Install docs: Install, Installer flags, Updating.
The repo recommends running from source and using the onboarding wizard:
curl -fsSL https://coderclaw.ai/install.sh | bash
coderclaw onboard --install-daemon
The wizard can also build UI assets automatically. After onboarding, you typically run the Gateway on port 18789.
From source (contributors/dev):
git clone https://github.com/SeanHogg/coderClaw.git
cd coderClaw
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
coderclaw onboard
If you don’t have a global install yet, run it via pnpm coderclaw onboard.
The wizard opens your browser with a clean (non-tokenized) dashboard URL right after onboarding and also prints the link in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine.
Localhost (same machine):
http://127.0.0.1:18789/.gateway.auth.token (or CODERCLAW_GATEWAY_TOKEN) into Control UI settings.coderclaw config get gateway.auth.token (or generate one: coderclaw doctor --generate-gateway-token).Not on localhost:
coderclaw gateway --tailscale serve, open https://<magicdns>/. If gateway.auth.allowTailscale is true, identity headers satisfy auth (no token).coderclaw gateway --bind tailnet --token "<token>", open http://<tailscale-ip>:18789/, paste token in dashboard settings.ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/ and paste the token in Control UI settings.See Dashboard and Web surfaces for bind modes and auth details.
Node >= 22 is required. pnpm is recommended. Bun is not recommended for the Gateway.
Yes. The Gateway is lightweight - docs list 512MB-1GB RAM, 1 core, and about 500MB disk as enough for personal use, and note that a Raspberry Pi 4 can run it.
If you want extra headroom (logs, media, other services), 2GB is recommended, but it’s not a hard minimum.
Tip: a small Pi/VPS can host the Gateway, and you can pair nodes on your laptop/phone for local screen/camera/canvas or command execution. See Nodes.
Short version: it works, but expect rough edges.
That screen depends on the Gateway being reachable and authenticated. The TUI also sends “Wake up, my friend!” automatically on first hatch. If you see that line with no reply and tokens stay at 0, the agent never ran.
coderclaw gateway restart
coderclaw status
coderclaw models status
coderclaw logs --follow
coderclaw doctor
If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI is pointed at the right Gateway. See Remote access.
Yes. Copy the state directory and workspace, then run Doctor once. This keeps your bot “exactly the same” (memory, session history, auth, and channel state) as long as you copy both locations:
$CODERCLAW_STATE_DIR (default: ~/.coderclaw) from the old machine.~/.coderclaw/workspace).coderclaw doctor and restart the Gateway service.That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you’re in remote mode, remember the gateway host owns the session store and workspace.
Important: if you only commit/push your workspace to GitHub, you’re backing
up memory + bootstrap files, but not session history or auth. Those live
under ~/.coderclaw/ (for example ~/.coderclaw/agents/<agentId>/sessions/).
Related: Migrating, Where things live on disk, Agent workspace, Doctor, Remote mode.
Check the GitHub changelog: https://github.com/SeanHogg/coderClaw/blob/main/CHANGELOG.md
Newest entries are at the top. If the top section is marked Unreleased, the next dated section is the latest shipped version. Entries are grouped by Highlights, Changes, and Fixes (plus docs/other sections when needed).
Some Comcast/Xfinity connections incorrectly block docs.coderclaw.ai via Xfinity
Advanced Security. Disable it or allowlist docs.coderclaw.ai, then retry. More
detail: Troubleshooting.
Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status.
If you still can’t reach the site, the docs are mirrored on GitHub: https://github.com/SeanHogg/coderClaw/tree/main/docs
Stable and beta are npm dist-tags, not separate code lines:
latest = stablebeta = early build for testingWe ship builds to beta, test them, and once a build is solid we promote
that same version to latest. That’s why beta and stable can point at the
same version.
See what changed: https://github.com/SeanHogg/coderClaw/blob/main/CHANGELOG.md
Beta is the npm dist-tag beta (may match latest).
Dev is the moving head of main (git); when published, it uses the npm dist-tag dev.
One-liners (macOS/Linux):
curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash -s -- --beta
curl -fsSL --proto '=https' --tlsv1.2 https://coderclaw.ai/install.sh | bash -s -- --install-method git
Windows installer (PowerShell): https://coderclaw.ai/install.ps1
More detail: Development channels and Installer flags.
Rough guide:
If it hangs, use Installer stuck and the fast debug loop in Im stuck.
Two options:
coderclaw update --channel dev
This switches to the main branch and updates from source.
curl -fsSL https://coderclaw.ai/install.sh | bash -s -- --install-method git
That gives you a local repo you can edit, then update via git.
If you prefer a clean clone manually, use:
git clone https://github.com/SeanHogg/coderClaw.git
cd coderClaw
pnpm install
pnpm build
Docs: Update, Development channels, Install.
Re-run the installer with verbose output:
curl -fsSL https://coderclaw.ai/install.sh | bash -s -- --verbose
Beta install with verbose:
curl -fsSL https://coderclaw.ai/install.sh | bash -s -- --beta --verbose
For a hackable (git) install:
curl -fsSL https://coderclaw.ai/install.sh | bash -s -- --install-method git --verbose
Windows (PowerShell) equivalent:
# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://coderclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
More options: Installer flags.
Two common Windows issues:
1) npm error spawn git / git not found
git is on your PATH.2) coderclaw is not recognized after install
Check the path:
npm config get prefix
<prefix>\\bin is on PATH (on most systems it is %AppData%\\npm).If you want the smoothest Windows setup, use WSL2 instead of native Windows. Docs: Windows.
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.
curl -fsSL https://coderclaw.ai/install.sh | bash -s -- --install-method git
More detail: Install and Installer flags.
Short answer: follow the Linux guide, then run the onboarding wizard.
Any Linux VPS works. Install on the server, then use SSH/Tailscale to reach the Gateway.
Guides: exe.dev, Hetzner, Fly.io. Remote access: Gateway remote.
We keep a hosting hub with the common providers. Pick one and follow the guide:
How it works 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.
You can pair nodes (Mac/iOS/Android/headless) to that cloud Gateway to access local screen/camera/canvas or run commands on your laptop while keeping the Gateway in the cloud.
Hub: Platforms. Remote access: Gateway remote. Nodes: Nodes, Nodes CLI.
Short answer: possible, not recommended. The update flow can restart the Gateway (which drops the active session), may need a clean git checkout, and can prompt for confirmation. Safer: run updates from a shell as the operator.
Use the CLI:
coderclaw update
coderclaw update status
coderclaw update --channel stable|beta|dev
coderclaw update --tag <dist-tag|version>
coderclaw update --no-restart
If you must automate from an agent:
coderclaw update --yes --no-restart
coderclaw gateway restart
coderclaw onboard is the recommended setup path. In local mode it walks you through:
It also warns if your configured model is unknown or missing auth.
No. You can run CoderClaw with API keys (Anthropic/OpenAI/others) or with local-only models so your data stays on your device. Subscriptions (Claude Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
Docs: Anthropic, OpenAI, Local models, Models.
Yes. You can authenticate with a setup-token instead of an API key. This is the subscription path.
Claude Pro/Max subscriptions do not include an API key, so this is the correct approach for subscription accounts. Important: you must verify with Anthropic that this usage is allowed under their subscription policy and terms. If you want the most explicit, supported path, use an Anthropic API key.
claude setup-token generates a token string via the Claude Code CLI (it is not available in the web console). You can run it on any machine. Choose Anthropic token (paste setup-token) in the wizard or paste it with coderclaw models auth paste-token --provider anthropic. The token is stored as an auth profile for the anthropic provider and used like an API key (no auto-refresh). More detail: OAuth.
It is not in the Anthropic Console. The setup-token is generated by the Claude Code CLI on any machine:
claude setup-token
Copy the token it prints, then choose Anthropic token (paste setup-token) in the wizard. If you want to run it on the gateway host, use coderclaw models auth setup-token --provider anthropic. If you ran claude setup-token elsewhere, paste it on the gateway host with coderclaw models auth paste-token --provider anthropic. See Anthropic.
Yes - via setup-token. CoderClaw no longer reuses Claude Code CLI OAuth tokens; use a setup-token or an Anthropic API key. Generate the token anywhere and paste it on the gateway host. See Anthropic and OAuth.
Note: Claude subscription access is governed by Anthropic’s terms. For production or multi-user workloads, API keys are usually the safer choice.
That means your Anthropic quota/rate limit is exhausted for the current window. If you use a Claude subscription (setup-token or Claude Code OAuth), wait for the window to reset or upgrade your plan. If you use an Anthropic API key, check the Anthropic Console for usage/billing and raise limits as needed.
Tip: set a fallback model so CoderClaw can keep replying while a provider is rate-limited. See Models and OAuth.
Yes - via pi-ai’s Amazon Bedrock (Converse) provider with manual config. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See Amazon Bedrock and Model providers. If you prefer a managed key flow, an OpenAI-compatible proxy in front of Bedrock is still a valid option.
CoderClaw supports OpenAI Code (Codex) via OAuth (ChatGPT sign-in). The wizard can run the OAuth flow and will set the default model to openai-codex/gpt-5.3-codex when appropriate. See Model providers and Wizard.
Yes. CoderClaw fully supports OpenAI Code (Codex) subscription OAuth. The onboarding wizard can run the OAuth flow for you.
See OAuth, Model providers, and Wizard.
Gemini CLI uses a plugin auth flow, not a client id or secret in coderclaw.json.
Steps:
coderclaw plugins enable google-gemini-cli-authcoderclaw models auth login --provider google-gemini-cli --set-defaultThis stores OAuth tokens in auth profiles on the gateway host. Details: Model providers.
Usually no. CoderClaw needs large context + strong safety; small cards truncate and leak. If you must, run the largest MiniMax M2.1 build you can locally (LM Studio) and see /gateway/local-models. Smaller/quantized models increase 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 by using models.mode: "merge" so fallbacks stay available while respecting the regioned provider you select.
No. CoderClaw runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people buy one as an always-on host, 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 BlueBubbles (recommended) - the BlueBubbles server runs on any Mac, and the Gateway can run on Linux or elsewhere. If you want other macOS-only tools, run the Gateway on a Mac or pair a macOS node.
Docs: BlueBubbles, Nodes, Mac remote mode.
You need some macOS device signed into Messages. It does not have to be a Mac mini - any Mac works. Use BlueBubbles (recommended) for iMessage - the BlueBubbles server runs on macOS, while the Gateway can run on Linux or elsewhere.
Common setups:
Docs: BlueBubbles, Nodes, Mac remote mode.
Yes. The Mac mini can run the Gateway, and your MacBook Pro can connect as a
node (companion device). Nodes don’t run the Gateway - they provide extra
capabilities like screen/camera/canvas and system.run on that device.
Common pattern:
coderclaw nodes status / coderclaw nodes list to see it.Bun is not recommended. We see runtime bugs, especially with WhatsApp and Telegram. Use Node for stable gateways.
If you still want to experiment with Bun, do it on a non-production gateway without WhatsApp/Telegram.
channels.telegram.allowFrom is the human sender’s Telegram user ID (numeric). It is not the bot username.
The onboarding wizard accepts @username input and resolves it to a numeric ID, but CoderClaw authorization uses numeric IDs only.
Safer (no third-party bot):
coderclaw logs --follow and read from.id.Official Bot API:
https://api.telegram.org/bot<bot_token>/getUpdates and read message.from.id.Third-party (less private):
@userinfobot or @getidsbot.See /channels/telegram.
Yes, via multi-agent routing. Bind each sender’s WhatsApp DM (peer kind: "direct", sender E.164 like +15551234567) to a different agentId, so each person gets their own workspace and session store. Replies still come from the same WhatsApp account, and DM access control (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) is global per WhatsApp 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 lives in Multi-Agent Routing. See also Models and Configuration.
Yes. Homebrew supports Linux (Linuxbrew). Quick setup:
/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>
If you run CoderClaw via systemd, ensure 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.
Docs: Getting started, Updating.
Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
This does not delete your data - it only changes the CoderClaw code install. Your state
(~/.coderclaw) and workspace (~/.coderclaw/workspace) stay untouched.
From npm → git:
git clone https://github.com/SeanHogg/coderClaw.git
cd coderClaw
pnpm install
pnpm build
coderclaw doctor
coderclaw gateway restart
From git → npm:
npm install -g coderclaw@latest
coderclaw doctor
coderclaw gateway restart
Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use --repair in automation).
Backup tips: see Backup strategy.
Short answer: if you want 24/7 reliability, use a VPS. If you want the lowest friction and you’re okay with sleep/restarts, run it locally.
Laptop (local Gateway)
VPS / cloud
CoderClaw-specific note: WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord all work fine from a VPS. The only real trade-off is headless browser vs a visible window. See Browser.
Recommended default: VPS if you had gateway disconnects before. Local is great when you’re actively using the Mac and want local file access or UI automation with a visible browser.
Not required, but recommended for reliability and isolation.
If you want the 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. For security guidance, read Security.
CoderClaw is lightweight. For a basic Gateway + one chat channel:
OS: use Ubuntu LTS (or any modern Debian/Ubuntu). The Linux install path is best tested there.
Docs: Linux, VPS hosting.
Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough RAM for the Gateway and any channels you enable.
Baseline guidance:
If you are on Windows, WSL2 is the easiest VM style setup and has the best tooling compatibility. See Windows, VPS hosting. If you are running macOS in a VM, see macOS VM.
CoderClaw is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The Gateway is the always-on control plane; the assistant is the product.
CoderClaw is not “just a Claude wrapper.” It’s a local-first control plane that lets you run a capable assistant on your own hardware, reachable from the chat apps you already use, with stateful sessions, memory, and tools - without handing control of your workflows to a hosted SaaS.
Highlights:
Docs: Gateway, Channels, Multi-agent, Memory.
Good first projects:
It can handle large tasks, but it works best when you split them into phases and use sub agents for parallel work.
Everyday wins usually look like:
Yes for research, qualification, and drafting. It can scan sites, build shortlists, summarize prospects, and write outreach or ad copy drafts.
For outreach or ad runs, keep a human in the loop. Avoid spam, follow local laws and platform policies, and review anything before it is sent. The safest pattern is to let CoderClaw draft and you approve.
Docs: Security.
CoderClaw is a personal assistant and coordination layer, not an IDE replacement. Use Claude Code or Codex for the fastest direct coding loop inside a repo. Use CoderClaw when you want durable memory, cross-device access, and tool orchestration.
Advantages:
Showcase: https://coderclaw.ai/showcase
Use managed overrides instead of editing the repo copy. Put your changes in ~/.coderclaw/skills/<name>/SKILL.md (or add a folder via skills.load.extraDirs in ~/.coderclaw/coderclaw.json). Precedence is <workspace>/skills > ~/.coderclaw/skills > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs.
Yes. Add extra directories via skills.load.extraDirs in ~/.coderclaw/coderclaw.json (lowest precedence). Default precedence remains: <workspace>/skills → ~/.coderclaw/skills → bundled → skills.load.extraDirs. clawhub installs into ./skills by default, which CoderClaw treats as <workspace>/skills.
Today the supported patterns are:
model override per job./model to switch the current session model at any time.See Cron jobs, Multi-Agent Routing, and Slash commands.
Use sub-agents for long or parallel tasks. Sub-agents run in their own session, return a summary, and keep your main chat responsive.
Ask your bot to “spawn a sub-agent for this task” or use /subagents.
Use /status in chat to see what the Gateway is doing right now (and whether it is busy).
Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a
cheaper model for sub-agents via agents.defaults.subagents.model.
Docs: Sub-agents.
Cron runs inside the Gateway process. If the Gateway is not running continuously, scheduled jobs will not run.
Checklist:
cron.enabled) and CODERCLAW_SKIP_CRON is not set.--tz vs host timezone).Debug:
coderclaw cron run <jobId> --force
coderclaw cron runs --id <jobId> --limit 50
Docs: Cron jobs, Cron vs Heartbeat.
Use ClawHub (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux. Browse skills at https://clawhub.com.
Install the ClawHub CLI (pick one package manager):
npm i -g clawhub
pnpm add -g clawhub
Yes. Use the Gateway scheduler:
Docs: Cron jobs, Cron vs Heartbeat, Heartbeat.
Not directly. macOS skills are gated by metadata.coderclaw.os plus required binaries, and skills only appear in the system prompt when they are eligible on the Gateway host. On Linux, darwin-only skills (like apple-notes, apple-reminders, things-mac) will not load unless you override the gating.
You have three supported patterns:
Option A - run the Gateway on a Mac (simplest). Run the Gateway where the macOS binaries exist, then connect from Linux in remote mode or over Tailscale. The skills load normally because the Gateway host is macOS.
Option B - use a macOS node (no SSH).
Run the Gateway on Linux, pair a macOS node (menubar app), and set Node Run Commands to “Always Ask” or “Always Allow” on the Mac. CoderClaw can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the nodes tool. If you choose “Always Ask”, approving “Always Allow” in the prompt adds that command to the allowlist.
Option C - proxy macOS binaries over SSH (advanced). Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
Create an SSH wrapper for the binary (example: memo for Apple Notes):
#!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
PATH on the Linux host (for example ~/bin/memo).Override the skill metadata (workspace or ~/.coderclaw/skills) to allow Linux:
---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS.
metadata: { "coderclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---
Not built-in today.
Options:
If you want to keep context per client (agency workflows), a simple pattern is:
If you want a native integration, open a feature request or build a skill targeting those APIs.
Install skills:
clawhub install <skill-slug>
clawhub update --all
ClawHub installs into ./skills under your current directory (or falls back to your configured CoderClaw workspace); CoderClaw treats that as <workspace>/skills on the next session. For shared skills across agents, place them in ~/.coderclaw/skills/<name>/SKILL.md. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See Skills and ClawHub.
Use the built-in installer, then load the unpacked extension in Chrome:
coderclaw browser extension install
coderclaw browser extension path
Then Chrome → chrome://extensions → enable “Developer mode” → “Load unpacked” → pick that folder.
Full guide (including remote Gateway + security notes): Chrome extension
If the Gateway runs on the same machine as Chrome (default setup), you usually do not need anything extra. If the Gateway runs elsewhere, run a node host on the browser machine so the Gateway can proxy browser actions. You still need to click the extension button on the tab you want to control (it doesn’t auto-attach).
Yes. See Sandboxing. For Docker-specific setup (full gateway in Docker or sandbox images), see Docker.
The default image is security-first and runs as the node user, so it does not
include system packages, Homebrew, or bundled browsers. For a fuller setup:
/home/node with CODERCLAW_HOME_VOLUME so caches survive.CODERCLAW_DOCKER_APT_PACKAGES.node /app/node_modules/playwright-core/cli.js install chromiumPLAYWRIGHT_BROWSERS_PATH and ensure the path is persisted.Can I keep DMs personal but make groups public sandboxed with one agent
Yes - if your private traffic is DMs and your public traffic is groups.
Use agents.defaults.sandbox.mode: "non-main" so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via tools.sandbox.tools.
Setup walkthrough + example config: Groups: personal DMs + public groups
Key config reference: Gateway configuration
Set agents.defaults.sandbox.docker.binds to ["host:path:mode"] (e.g., "/home/user/src:/src:ro"). Global + per-agent binds merge; per-agent binds are ignored when scope: "shared". Use :ro for anything sensitive and remember binds bypass the sandbox filesystem walls. See Sandboxing and Sandbox vs Tool Policy vs Elevated for examples and safety notes.
CoderClaw memory is just Markdown files in the agent workspace:
memory/YYYY-MM-DD.mdMEMORY.md (main/private sessions only)CoderClaw also runs a silent pre-compaction memory flush to remind the model to write durable notes before auto-compaction. This only runs when the workspace is writable (read-only sandboxes skip it). See Memory.
Ask the bot to write the fact to memory. Long-term notes belong in MEMORY.md,
short-term context goes into memory/YYYY-MM-DD.md.
This is still an area we are improving. It helps to remind the model to store memories; it will know what to do. If it keeps forgetting, verify the Gateway is using the same workspace on every run.
Docs: Memory, Agent workspace.
Only if you use OpenAI embeddings. Codex OAuth covers chat/completions and
does not grant embeddings access, so signing in with Codex (OAuth or the
Codex CLI login) does not help for semantic memory search. OpenAI embeddings
still need a real API key (OPENAI_API_KEY or models.providers.openai.apiKey).
If you don’t set a provider explicitly, CoderClaw auto-selects a provider when it
can resolve an API key (auth profiles, models.providers.*.apiKey, or env vars).
It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key
resolves. If neither key is available, memory search stays disabled until you
configure it. If you have a local model path configured and present, CoderClaw
prefers local.
If you’d rather stay local, set memorySearch.provider = "local" (and optionally
memorySearch.fallback = "none"). If you want Gemini embeddings, set
memorySearch.provider = "gemini" and provide GEMINI_API_KEY (or
memorySearch.remote.apiKey). We support OpenAI, Gemini, or local embedding
models - see Memory for the setup details.
Memory files live on disk and persist until you delete them. The limit is your storage, not the model. The session context is still limited by the model context window, so long conversations can compact or truncate. That is why memory search exists - it pulls only the relevant parts back into context.
No - CoderClaw’s state is local, but external services still see what you send them.
~/.coderclaw + your workspace directory).Related: Agent workspace, Memory.
Everything lives under $CODERCLAW_STATE_DIR (default: ~/.coderclaw):
| Path | Purpose |
|---|---|
$CODERCLAW_STATE_DIR/coderclaw.json |
Main config (JSON5) |
$CODERCLAW_STATE_DIR/credentials/oauth.json |
Legacy OAuth import (copied into auth profiles on first use) |
$CODERCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json |
Auth profiles (OAuth + API keys) |
$CODERCLAW_STATE_DIR/agents/<agentId>/agent/auth.json |
Runtime auth cache (managed automatically) |
$CODERCLAW_STATE_DIR/credentials/ |
Provider state (e.g. whatsapp/<accountId>/creds.json) |
$CODERCLAW_STATE_DIR/agents/ |
Per-agent state (agentDir + sessions) |
$CODERCLAW_STATE_DIR/agents/<agentId>/sessions/ |
Conversation history & state (per agent) |
$CODERCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json |
Session metadata (per agent) |
Legacy single-agent path: ~/.coderclaw/agent/* (migrated by coderclaw doctor).
Your workspace (AGENTS.md, memory files, skills, etc.) is separate and configured via agents.defaults.workspace (default: ~/.coderclaw/workspace).
These files live in the agent workspace, not ~/.coderclaw.
AGENTS.md, SOUL.md, IDENTITY.md, USER.md,
MEMORY.md (or memory.md), memory/YYYY-MM-DD.md, optional HEARTBEAT.md.~/.coderclaw): config, credentials, auth profiles, sessions, logs,
and shared skills (~/.coderclaw/skills).Default workspace is ~/.coderclaw/workspace, configurable via:
{
agents: { defaults: { workspace: "~/.coderclaw/workspace" } },
}
If the bot “forgets” after a restart, confirm the Gateway is using the same workspace on every launch (and remember: remote mode uses the gateway host’s workspace, not your local laptop).
Tip: if you want a durable behavior or preference, ask the bot to write it into AGENTS.md or MEMORY.md rather than relying on chat history.
See Agent workspace and Memory.
Put your agent workspace in a private git repo and back it up somewhere private (for example GitHub private). This captures memory + AGENTS/SOUL/USER files, and lets you restore the assistant’s “mind” later.
Do not commit anything under ~/.coderclaw (credentials, sessions, tokens).
If you need a full restore, back up both the workspace and the state directory
separately (see the migration question above).
Docs: Agent workspace.
See the dedicated guide: Uninstall.
Yes. The workspace is the default cwd and memory anchor, not a hard sandbox.
Relative paths resolve inside the workspace, but absolute paths can access other
host locations unless sandboxing is enabled. If you need isolation, use
agents.defaults.sandbox or per-agent sandbox settings. If you
want a repo to be the default working directory, point that agent’s
workspace to the repo root. The CoderClaw repo is just source code; keep the
workspace separate unless you intentionally want the agent to work inside it.
Example (repo as default cwd):
{
agents: {
defaults: {
workspace: "~/Projects/my-repo",
},
},
}
Session state is owned by the gateway host. If you’re in remote mode, the session store you care about is on the remote machine, not your local laptop. See Session management.
CoderClaw reads an optional JSON5 config from $CODERCLAW_CONFIG_PATH (default: ~/.coderclaw/coderclaw.json):
$CODERCLAW_CONFIG_PATH
If the file is missing, it uses safe-ish defaults (including a default workspace of ~/.coderclaw/workspace).
Non-loopback binds require auth. Configure gateway.auth.mode + gateway.auth.token (or use CODERCLAW_GATEWAY_TOKEN).
{
gateway: {
bind: "lan",
auth: {
mode: "token",
token: "replace-me",
},
},
}
Notes:
gateway.remote.token is for remote CLI calls only; it does not enable local gateway auth.connect.params.auth.token (stored in app/UI settings). Avoid putting tokens in URLs.The wizard generates a gateway token by default (even on loopback) so local WS clients must authenticate. This blocks other local processes from calling the Gateway. Paste the token into the Control UI settings (or your client config) to connect.
If you really want open loopback, remove gateway.auth from your config. Doctor can generate a token for you any time: coderclaw doctor --generate-gateway-token.
The Gateway watches the config and supports hot-reload:
gateway.reload.mode: "hybrid" (default): hot-apply safe changes, restart for critical oneshot, restart, off are also supportedweb_fetch works without an API key. web_search requires a Brave Search API
key. Recommended: run coderclaw configure --section web to store it in
tools.web.search.apiKey. Environment alternative: set BRAVE_API_KEY for the
Gateway process.
{
tools: {
web: {
search: {
enabled: true,
apiKey: "BRAVE_API_KEY_HERE",
maxResults: 5,
},
fetch: {
enabled: true,
},
},
},
}
Notes:
web_search/web_fetch or group:web.web_fetch is enabled by default (unless explicitly disabled).~/.coderclaw/.env (or the service environment).Docs: Web tools.
The common pattern is one Gateway (e.g. Raspberry Pi) plus nodes and agents:
system.run, canvas, camera).Docs: Nodes, Remote access, Multi-Agent Routing, Sub-agents, TUI.
Yes. It’s a config option:
{
browser: { headless: true },
agents: {
defaults: {
sandbox: { browser: { headless: true } },
},
},
}
Default is false (headful). Headless is more likely to trigger anti-bot checks on some sites. See Browser.
Headless uses the same Chromium engine and works for most automation (forms, clicks, scraping, logins). The main differences:
Set browser.executablePath to your Brave binary (or any Chromium-based browser) and restart the Gateway.
See the full config examples in Browser.
Telegram messages are handled by the gateway. The gateway runs the agent and only then calls nodes over the Gateway WebSocket when a node tool is needed:
Telegram → Gateway → Agent → node.* → Node → Gateway → Telegram
Nodes don’t see inbound provider traffic; they only receive node RPC calls.
Short answer: pair your computer as a node. The Gateway runs elsewhere, but it can
call node.* tools (screen, camera, system) on your local machine over the Gateway WebSocket.
Typical setup:
Approve the node on the Gateway:
coderclaw nodes pending
coderclaw nodes approve <requestId>
No separate TCP bridge is required; nodes connect over the Gateway WebSocket.
Security reminder: pairing a macOS node allows system.run on that machine. Only
pair devices you trust, and review Security.
Docs: Nodes, Gateway protocol, macOS remote mode, Security.
Check the basics:
coderclaw gateway statuscoderclaw statuscoderclaw channels statusThen verify auth and routing:
gateway.auth.allowTailscale is set correctly.Docs: Tailscale, Remote access, Channels.
Yes. There is no built-in “bot-to-bot” bridge, but you can wire it up in a few reliable ways:
Simplest: use a normal chat channel both bots can access (Telegram/Slack/WhatsApp). Have Bot A send a message to Bot B, then let Bot B reply as usual.
CLI bridge (generic): run a script that calls the other Gateway with
coderclaw agent --message ... --deliver, targeting a chat where the other bot
listens. If one bot is on a remote VPS, point your CLI at that remote Gateway
via SSH/Tailscale (see Remote access).
Example pattern (run from a machine that can reach the target Gateway):
coderclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>
Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel allowlists, or a “do not reply to bot messages” rule).
Docs: Remote access, Agent CLI, Agent send.
No. One Gateway can host multiple agents, each with its own workspace, model defaults, and routing. That is the normal setup and it is much cheaper and simpler than running one VPS per agent.
Use separate VPSes only when you need hard isolation (security boundaries) or very different configs that you do not want to share. Otherwise, keep one Gateway and use multiple agents or sub-agents.
Yes - nodes are the first-class way to reach your laptop from a remote Gateway, and they unlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common setup is an always-on host plus your laptop as a node.
system.run is gated by node allowlists/approvals on that laptop.canvas, camera, and screen in addition to system.run.SSH is fine for ad-hoc shell access, but nodes are simpler for ongoing agent workflows and device automation.
Docs: Nodes, Nodes CLI, Chrome extension.
If you only need local tools (screen/camera/exec) on the second laptop, add it as a node. That keeps a single Gateway and avoids duplicated config. Local node tools are currently macOS-only, but we plan to extend them to other OSes.
Install a second Gateway only when you need hard isolation or two fully separate bots.
Docs: Nodes, Nodes CLI, Multiple gateways.
No. Only one gateway should run per host unless you intentionally run isolated profiles (see Multiple gateways). Nodes are peripherals that connect to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app). For headless node hosts and CLI control, see Node host CLI.
A full restart is required for gateway, discovery, and canvasHost changes.
Yes. config.apply validates + writes the full config and restarts the Gateway as part of the operation.
config.apply replaces the entire config. If you send a partial object, everything
else is removed.
Recover:
~/.coderclaw/coderclaw.json).coderclaw doctor and reconfigure channels/models.Avoid it:
coderclaw config set for small changes.coderclaw configure for interactive edits.Docs: Config, Configure, Doctor.
{
agents: { defaults: { workspace: "~/.coderclaw/workspace" } },
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
This sets your workspace and restricts who can trigger the bot.
Minimal steps:
Install + login on the VPS
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
ssh [email protected]ws://your-vps.tailnet-xxxx.ts.net:18789If you want the Control UI without SSH, use Tailscale Serve on the VPS:
coderclaw gateway --tailscale serve
This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See Tailscale.
Serve exposes the Gateway Control UI + WS. Nodes connect over the same Gateway WS endpoint.
Recommended setup:
Approve the node on the gateway:
coderclaw nodes pending
coderclaw nodes approve <requestId>
Docs: Gateway protocol, Discovery, macOS remote mode.
CoderClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:
.env from the current working directory.env from ~/.coderclaw/.env (aka $CODERCLAW_STATE_DIR/.env)Neither .env file overrides existing env vars.
You can also define inline env vars in config (applied only if missing from the process env):
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: { GROQ_API_KEY: "gsk-..." },
},
}
See /environment for full precedence and sources.
Two common fixes:
~/.coderclaw/.env so they’re picked up even when the service doesn’t inherit your shell env.{
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000,
},
},
}
This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
CODERCLAW_LOAD_SHELL_ENV=1, CODERCLAW_SHELL_ENV_TIMEOUT_MS=15000.
coderclaw models status reports whether shell env import is enabled. “Shell env: off”
does not mean your env vars are missing - it just means CoderClaw won’t load
your login shell automatically.
If the Gateway runs as a service (launchd/systemd), it won’t inherit your shell environment. Fix by doing one of these:
Put the token in ~/.coderclaw/.env:
COPILOT_GITHUB_TOKEN=...
env.shellEnv.enabled: true).env block (applies only if missing).Then restart the gateway and recheck:
coderclaw models status
Copilot tokens are read from COPILOT_GITHUB_TOKEN (also GH_TOKEN / GITHUB_TOKEN).
See /concepts/model-providers and /environment.
Send /new or /reset as a standalone message. See Session management.
Yes. Sessions expire after session.idleMinutes (default 60). The next
message starts a fresh session id for that chat key. This does not delete
transcripts - it just starts a new session.
{
session: {
idleMinutes: 240,
},
}
Yes, via multi-agent routing and sub-agents. You can create one coordinator agent and several worker agents with their own workspaces and models.
That said, this is best seen as a fun experiment. It is token heavy and often less efficient than using one bot with separate sessions. The typical model we envision is one bot you talk to, with different sessions for parallel work. That bot can also spawn sub-agents when needed.
Docs: Multi-agent routing, Sub-agents, Agents CLI.
Session context is limited by the model window. Long chats, large tool outputs, or many files can trigger compaction or truncation.
What helps:
/compact before long tasks, and /new when switching topics.Use the reset command:
coderclaw reset
Non-interactive full reset:
coderclaw reset --scope full --yes --non-interactive
Then re-run onboarding:
coderclaw onboard --install-daemon
Notes:
--profile / CODERCLAW_PROFILE), reset each state dir (defaults are ~/.coderclaw-<profile>).coderclaw gateway --dev --reset (dev-only; wipes dev config + credentials + sessions + workspace).Use one of these:
Compact (keeps the conversation but summarizes older turns):
/compact
or /compact <instructions> to guide the summary.
Reset (fresh session ID for the same chat key):
/new
/reset
If it keeps happening:
agents.defaults.contextPruning) to trim old tool output.Docs: Compaction, Session pruning, Session management.
This is a provider validation error: the model emitted a tool_use block without the required
input. It usually means the session history is stale or corrupted (often after long threads
or a tool/schema change).
Fix: start a fresh session with /new (standalone message).
Heartbeats run every 30m by default. Tune or disable them:
{
agents: {
defaults: {
heartbeat: {
every: "2h", // or "0m" to disable
},
},
},
}
If HEARTBEAT.md exists but is effectively empty (only blank lines and markdown
headers like # Heading), CoderClaw skips the heartbeat run to save API calls.
If the file is missing, the heartbeat still runs and the model decides what to do.
Per-agent overrides use agents.list[].heartbeat. Docs: Heartbeat.
No. CoderClaw runs on your own account, so if you’re in the group, CoderClaw can see it.
By default, group replies are blocked until you allow senders (groupPolicy: "allowlist").
If you want only you to be able to trigger group replies:
{
channels: {
whatsapp: {
groupPolicy: "allowlist",
groupAllowFrom: ["+15551234567"],
},
},
}
Option 1 (fastest): tail logs and send a test message in the group:
coderclaw logs --follow --json
Look for chatId (or from) ending in @g.us, like:
[email protected].
Option 2 (if already configured/allowlisted): list groups from config:
coderclaw directory groups list --channel whatsapp
Docs: WhatsApp, Directory, Logs.
Two common causes:
mentionPatterns).channels.whatsapp.groups without "*" and the group isn’t allowlisted.See Groups and Group messages.
Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See Groups and Group messages.
No hard limits. Dozens (even hundreds) are fine, but watch for:
~/.coderclaw/agents/<agentId>/sessions/.Tips:
agents.defaults.workspace).coderclaw doctor to spot stray workspaces and profile mismatches.Yes. Use Multi-Agent Routing to run multiple isolated agents and route inbound messages by channel/account/peer. Slack is supported as a channel and can be bound to specific agents.
Browser access is powerful but not “do anything a human can” - anti-bot, CAPTCHAs, and MFA can still block automation. For the most reliable browser control, use the Chrome extension relay on the machine that runs the browser (and keep the Gateway anywhere).
Best-practice setup:
Docs: Multi-Agent Routing, Slack, Browser, Chrome extension, Nodes.
CoderClaw’s default model is whatever you set as:
agents.defaults.model.primary
Models are referenced as provider/model (example: anthropic/claude-opus-4-6). If you omit the provider, CoderClaw currently assumes anthropic as a temporary deprecation fallback - but you should still explicitly set provider/model.
Recommended default: anthropic/claude-opus-4-6.
Good alternative: anthropic/claude-sonnet-4-5.
Reliable (less character): openai/gpt-5.2 - nearly as good as Opus, just less personality.
Budget: zai/glm-4.7.
MiniMax M2.1 has its own docs: MiniMax and Local models.
Rule of thumb: use the best model you can afford for high-stakes work, and a cheaper model for routine chat or summaries. You can route models per agent and use sub-agents to parallelize long tasks (each sub-agent consumes tokens). See Models and Sub-agents.
Strong warning: weaker/over-quantized models are more vulnerable to prompt injection and unsafe behavior. See Security.
More context: Models.
Yes. If your local server exposes an OpenAI-compatible API, you can point a custom provider at it. Ollama is supported directly and is the easiest path.
Security note: smaller or heavily quantized models are more vulnerable to prompt injection. We strongly recommend large models for any bot that can use tools. If you still want small models, enable sandboxing and strict tool allowlists.
Docs: Ollama, Local models, Model providers, Security, Sandboxing.
Use model commands or edit only the model fields. Avoid full config replaces.
Safe options:
/model in chat (quick, per-session)coderclaw models set ... (updates just model config)coderclaw configure --section model (interactive)agents.defaults.model in ~/.coderclaw/coderclaw.jsonAvoid config.apply with a partial object unless you intend to replace the whole config.
If you did overwrite config, restore from backup or re-run coderclaw doctor to repair.
Docs: Models, Configure, Config, Doctor.
anthropic/claude-opus-4-6) - see Anthropic.minimax/MiniMax-M2.1) - see MiniMax.Use the /model command as a standalone message:
/model sonnet
/model haiku
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
You can list available models with /model, /model list, or /model status.
/model (and /model list) shows a compact, numbered picker. Select by number:
/model 3
You can also force a specific auth profile for the provider (per session):
/model opus@anthropic:default
/model opus@anthropic:work
Tip: /model status shows which agent is active, which auth-profiles.json file is being used, and which auth profile will be tried next.
It also shows the configured provider endpoint (baseUrl) and API mode (api) when available.
How do I unpin a profile I set with profile
Re-run /model without the @profile suffix:
/model anthropic/claude-opus-4-6
If you want to return to the default, pick it from /model (or send /model <default provider/model>).
Use /model status to confirm which auth profile is active.
Yes. Set one as default and switch as needed:
/model gpt-5.2 for daily tasks, /model gpt-5.3-codex for coding.agents.defaults.model.primary to openai/gpt-5.2, then switch to openai-codex/gpt-5.3-codex when coding (or the other way around).See Models and Slash commands.
If agents.defaults.models is set, it becomes the allowlist for /model and any
session overrides. Choosing a model that isn’t in that list returns:
Model "provider/model" is not allowed. Use /model to list available models.
That error is returned instead of a normal reply. Fix: add the model to
agents.defaults.models, remove the allowlist, or pick a model from /model list.
This means the provider isn’t configured (no MiniMax provider config or auth profile was found), so the model can’t be resolved. A fix for this detection is in 2026.1.12 (unreleased at the time of writing).
Fix checklist:
main), then restart the gateway.minimax/MiniMax-M2.1 or
minimax/MiniMax-M2.1-lightning.Run:
coderclaw models list
and pick from the list (or /model list in chat).
Yes. Use MiniMax as the default and switch models per session when needed.
Fallbacks are for errors, not “hard tasks,” so use /model or a separate agent.
Option A: switch per session
{
env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "minimax/MiniMax-M2.1" },
models: {
"minimax/MiniMax-M2.1": { alias: "minimax" },
"openai/gpt-5.2": { alias: "gpt" },
},
},
},
}
Then:
/model gpt
Option B: separate agents
/agent to switchDocs: Models, Multi-Agent Routing, MiniMax, OpenAI.
Yes. CoderClaw ships a few default shorthands (only applied when the model exists in agents.defaults.models):
opus → anthropic/claude-opus-4-6sonnet → anthropic/claude-sonnet-4-5gpt → openai/gpt-5.2gpt-mini → openai/gpt-5-minigemini → google/gemini-3-pro-previewgemini-flash → google/gemini-3-flash-previewIf you set your own alias with the same name, your value wins.
Aliases come from agents.defaults.models.<modelId>.alias. Example:
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-6" },
models: {
"anthropic/claude-opus-4-6": { alias: "opus" },
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
"anthropic/claude-haiku-4-5": { alias: "haiku" },
},
},
},
}
Then /model sonnet (or /<alias> when supported) resolves to that model ID.
OpenRouter (pay-per-token; many models):
{
agents: {
defaults: {
model: { primary: "openrouter/anthropic/claude-sonnet-4-5" },
models: { "openrouter/anthropic/claude-sonnet-4-5": {} },
},
},
env: { OPENROUTER_API_KEY: "sk-or-..." },
}
Z.AI (GLM models):
{
agents: {
defaults: {
model: { primary: "zai/glm-4.7" },
models: { "zai/glm-4.7": {} },
},
},
env: { ZAI_API_KEY: "..." },
}
If you reference a provider/model but the required provider key is missing, you’ll get a runtime auth error (e.g. No API key found for provider "zai").
No API key found for provider after adding a new agent
This usually means the new agent has an empty auth store. Auth is per-agent and stored in:
~/.coderclaw/agents/<agentId>/agent/auth-profiles.json
Fix options:
coderclaw agents add <id> and configure auth during the wizard.auth-profiles.json from the main agent’s agentDir into the new agent’s agentDir.Do not reuse agentDir across agents; it causes auth/session collisions.
Failover happens in two stages:
agents.defaults.model.fallbacks.Cooldowns apply to failing profiles (exponential backoff), so CoderClaw can keep responding even when a provider is rate-limited or temporarily failing.
No credentials found for profile "anthropic:default"
It means the system attempted to use the auth profile ID anthropic:default, but could not find credentials for it in the expected auth store.
~/.coderclaw/agents/<agentId>/agent/auth-profiles.json~/.coderclaw/agent/* (migrated by coderclaw doctor)ANTHROPIC_API_KEY in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in ~/.coderclaw/.env or enable env.shellEnv.auth-profiles.json files.coderclaw models status to see configured models and whether providers are authenticated.Fix checklist for No credentials found for profile anthropic
This means the run is pinned to an Anthropic auth profile, but the Gateway can’t find it in its auth store.
claude setup-token, then paste it with coderclaw models auth setup-token --provider anthropic.coderclaw models auth paste-token --provider anthropic.ANTHROPIC_API_KEY in ~/.coderclaw/.env on the gateway host.Clear any pinned order that forces a missing profile:
coderclaw models auth order clear --provider anthropic
If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), CoderClaw will try it during model fallback. If you haven’t configured Google credentials, you’ll see No API key found for provider "google".
Fix: either provide Google auth, or remove/avoid Google models in agents.defaults.model.fallbacks / aliases so fallback doesn’t route there.
LLM request rejected message thinking signature required google antigravity
Cause: the session history contains thinking blocks without signatures (often from an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.
Fix: CoderClaw now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a new session or set /thinking off for that agent.
Related: /concepts/oauth (OAuth flows, token storage, multi-account patterns)
An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:
~/.coderclaw/agents/<agentId>/agent/auth-profiles.json
CoderClaw uses provider-prefixed IDs like:
anthropic:default (common when no email identity exists)anthropic:<email> for OAuth identitiesanthropic:work)Yes. Config supports optional metadata for profiles and an ordering per provider (auth.order.<provider>). This does not store secrets; it maps IDs to provider/mode and sets rotation order.
CoderClaw may temporarily skip a profile if it’s in a short cooldown (rate limits/timeouts/auth failures) or a longer disabled state (billing/insufficient credits). To inspect this, run coderclaw models status --json and check auth.unusableProfiles. Tuning: auth.cooldowns.billingBackoffHours*.
You can also set a per-agent order override (stored in that agent’s auth-profiles.json) via the CLI:
# Defaults to the configured default agent (omit --agent)
coderclaw models auth order get --provider anthropic
# Lock rotation to a single profile (only try this one)
coderclaw models auth order set --provider anthropic anthropic:default
# Or set an explicit order (fallback within provider)
coderclaw models auth order set --provider anthropic anthropic:work anthropic:default
# Clear override (fall back to config auth.order / round-robin)
coderclaw models auth order clear --provider anthropic
To target a specific agent:
coderclaw models auth order set --provider anthropic --agent main anthropic:default
CoderClaw supports both:
The wizard explicitly supports Anthropic setup-token and OpenAI Codex OAuth and can store API keys for you.
gateway.port controls the single multiplexed port for WebSocket + HTTP (Control UI, hooks, etc.).
Precedence:
--port > CODERCLAW_GATEWAY_PORT > gateway.port > default 18789
Because “running” is the supervisor’s view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling status.
Use coderclaw gateway status and trust these lines:
Probe target: (the URL the probe actually used)Listening: (what’s actually bound on the port)Last gateway error: (common root cause when the process is alive but the port isn’t listening)You’re editing one config file while the service is running another (often a --profile / CODERCLAW_STATE_DIR mismatch).
Fix:
coderclaw gateway install --force
Run that from the same --profile / environment you want the service to use.
CoderClaw enforces a runtime lock by binding the WebSocket listener immediately on startup (default ws://127.0.0.1:18789). If the bind fails with EADDRINUSE, it throws GatewayLockError indicating another instance is already listening.
Fix: stop the other instance, free the port, or run with coderclaw gateway --port <port>.
Set gateway.mode: "remote" and point to a remote WebSocket URL, optionally with a token/password:
{
gateway: {
mode: "remote",
remote: {
url: "ws://gateway.tailnet:18789",
token: "your-token",
password: "your-password",
},
},
}
Notes:
coderclaw gateway only starts when gateway.mode is local (or you pass the override flag).Your gateway is running with auth enabled (gateway.auth.*), but the UI is not sending the matching token/password.
Facts (from code):
coderclaw.control.settings.v1.Fix:
coderclaw dashboard (prints + copies the dashboard URL, tries to open; shows SSH hint if headless).coderclaw doctor --generate-gateway-token.ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/.gateway.auth.token (or CODERCLAW_GATEWAY_TOKEN) on the gateway host.coderclaw status --all and follow Troubleshooting. See Dashboard for auth details.tailnet bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn’t on Tailscale (or the interface is down), there’s nothing to bind to.
Fix:
gateway.bind: "loopback" / "lan".Note: tailnet is explicit. auto prefers loopback; use gateway.bind: "tailnet" when you want a tailnet-only bind.
Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation.
Yes, but you must isolate:
CODERCLAW_CONFIG_PATH (per-instance config)CODERCLAW_STATE_DIR (per-instance state)agents.defaults.workspace (workspace isolation)gateway.port (unique ports)Quick setup (recommended):
coderclaw --profile <name> … per instance (auto-creates ~/.coderclaw-<name>).gateway.port in each profile config (or pass --port for manual runs).coderclaw --profile <name> gateway install.Profiles also suffix service names (bot.molt.<profile>; legacy com.coderclaw.*, coderclaw-gateway-<profile>.service, CoderClaw Gateway (<profile>)).
Full guide: Multiple gateways.
The Gateway is a WebSocket server, and it expects the very first message to
be a connect frame. If it receives anything else, it closes the connection
with code 1008 (policy violation).
Common causes:
http://...) instead of a WS client.Quick fixes:
ws://<host>:18789 (or wss://... if HTTPS).connect frame.If you’re using the CLI or TUI, the URL should look like:
coderclaw tui --url ws://<host>:18789 --token <token>
Protocol details: Gateway protocol.
File logs (structured):
/tmp/coderclaw/coderclaw-YYYY-MM-DD.log
You can set a stable path via logging.file. File log level is controlled by logging.level. Console verbosity is controlled by --verbose and logging.consoleLevel.
Fastest log tail:
coderclaw logs --follow
Service/supervisor logs (when the gateway runs via launchd/systemd):
$CODERCLAW_STATE_DIR/logs/gateway.log and gateway.err.log (default: ~/.coderclaw/logs/...; profiles use ~/.coderclaw-<profile>/logs/...)journalctl --user -u coderclaw-gateway[-<profile>].service -n 200 --no-pagerschtasks /Query /TN "CoderClaw Gateway (<profile>)" /V /FO LISTSee Troubleshooting for more.
Use the gateway helpers:
coderclaw gateway status
coderclaw gateway restart
If you run the gateway manually, coderclaw gateway --force can reclaim the port. See Gateway.
There are two Windows install modes:
1) WSL2 (recommended): the Gateway runs inside Linux.
Open PowerShell, enter WSL, then restart:
wsl
coderclaw gateway status
coderclaw gateway restart
If you never installed the service, start it in the foreground:
coderclaw gateway run
2) Native Windows (not recommended): the Gateway runs directly in Windows.
Open PowerShell and run:
coderclaw gateway status
coderclaw gateway restart
If you run it manually (no service), use:
coderclaw gateway run
Docs: Windows (WSL2), Gateway service runbook.
Start with a quick health sweep:
coderclaw status
coderclaw models status
coderclaw channels status
coderclaw logs --follow
Common causes:
models status).If you are remote, confirm the tunnel/Tailscale connection is up and that the Gateway WebSocket is reachable.
Docs: Channels, Troubleshooting, Remote access.
This usually means the UI lost the WebSocket connection. Check:
coderclaw gateway statuscoderclaw statuscoderclaw dashboardThen tail logs:
coderclaw logs --follow
Docs: Dashboard, Remote access, Troubleshooting.
Start with logs and channel status:
coderclaw channels status
coderclaw channels logs --channel telegram
If you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works. If the Gateway is remote, make sure you are looking at logs on the Gateway host.
Docs: Telegram, Channel troubleshooting.
First confirm the Gateway is reachable and the agent can run:
coderclaw status
coderclaw models status
coderclaw logs --follow
In the TUI, use /status to see the current state. If you expect replies in a chat
channel, make sure delivery is enabled (/deliver on).
Docs: TUI, Slash commands.
If you installed the service:
coderclaw gateway stop
coderclaw gateway start
This stops/starts the supervised service (launchd on macOS, systemd on Linux). Use this when the Gateway runs in the background as a daemon.
If you’re running in the foreground, stop with Ctrl-C, then:
coderclaw gateway run
Docs: Gateway service runbook.
coderclaw gateway restart: restarts the background service (launchd/systemd).coderclaw gateway: runs the gateway in the foreground for this terminal session.If you installed the service, use the gateway commands. Use coderclaw gateway when
you want a one-off, foreground run.
Start the Gateway with --verbose to get more console detail. Then inspect the log file for channel auth, model routing, and RPC errors.
Outbound attachments from the agent must include a MEDIA:<path-or-url> line (on its own line). See CoderClaw assistant setup and Agent send.
CLI sending:
coderclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
Also check:
See Images.
Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:
coderclaw pairing approve <channel> <code>coderclaw pairing list <channel> if a code didn’t arrive.dmPolicy: "open" and allowlist "*").Run coderclaw doctor to surface risky DM policies.
No. Prompt injection is about untrusted content, not just who can DM the bot. If your assistant reads external content (web search/fetch, browser pages, emails, docs, attachments, pasted logs), that content can include instructions that try to hijack the model. This can happen even if you are the only sender.
The biggest risk is when tools are enabled: the model can be tricked into exfiltrating context or calling tools on your behalf. Reduce the blast radius by:
web_search / web_fetch / browser off for tool-enabled agentsDetails: Security.
Yes, for most setups. Isolating the bot with separate accounts and phone numbers reduces the blast radius if something goes wrong. This also makes it easier to rotate credentials or revoke access without impacting your personal accounts.
Start small. Give access only to the tools and accounts you actually need, and expand later if required.
We do not recommend full autonomy over your personal messages. The safest pattern is:
If you want to experiment, do it on a dedicated account and keep it isolated. See Security.
Yes, if the agent is chat-only and the input is trusted. Smaller tiers are more susceptible to instruction hijacking, so avoid them for tool-enabled agents or when reading untrusted content. If you must use a smaller model, lock down tools and run inside a sandbox. See Security.
Pairing codes are sent only when an unknown sender messages the bot and
dmPolicy: "pairing" is enabled. /start by itself doesn’t generate a code.
Check pending requests:
coderclaw pairing list telegram
If you want immediate access, allowlist your sender id or set dmPolicy: "open"
for that account.
No. Default WhatsApp DM policy is pairing. Unknown senders only get a pairing code and their message is not processed. CoderClaw only replies to chats it receives or to explicit sends you trigger.
Approve pairing with:
coderclaw pairing approve whatsapp <code>
List pending requests:
coderclaw pairing list whatsapp
Wizard phone number prompt: it’s used to set your allowlist/owner so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable channels.whatsapp.selfChatMode.
Most internal or tool messages only appear when verbose or reasoning is enabled for that session.
Fix in the chat where you see it:
/verbose off
/reasoning off
If it is still noisy, check the session settings in the Control UI and set verbose
to inherit. Also confirm you are not using a bot profile with verboseDefault set
to on in config.
Docs: Thinking and verbose, Security.
Send any of these as a standalone message (no slash):
stop
abort
esc
wait
exit
interrupt
These are abort triggers (not slash commands).
For background processes (from the exec tool), you can ask the agent to run:
process action:kill sessionId:XXX
Slash commands overview: see Slash commands.
Most commands must be sent as a standalone message that starts with /, but a few shortcuts (like /status) also work inline for allowlisted senders.
CoderClaw blocks cross-provider messaging by default. If a tool call is bound to Telegram, it won’t send to Discord unless you explicitly allow it.
Enable cross-provider messaging for the agent:
{
agents: {
defaults: {
tools: {
message: {
crossContext: {
allowAcrossProviders: true,
marker: { enabled: true, prefix: "[from {channel}] " },
},
},
},
},
},
}
Restart the gateway after editing config. If you only want this for a single
agent, set it under agents.list[].tools.message instead.
Queue mode controls how new messages interact with an in-flight run. Use /queue to change modes:
steer - new messages redirect the current taskfollowup - run messages one at a timecollect - batch messages and reply once (default)steer-backlog - steer now, then process backloginterrupt - abort current run and start freshYou can add options like debounce:2s cap:25 drop:summarize for followup modes.
Q: “What’s the default model for Anthropic with an API key?”
A: In CoderClaw, 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-5 or anthropic/claude-opus-4-6). If you see No credentials found for profile "anthropic:default", it means the Gateway couldn’t find Anthropic credentials in the expected auth-profiles.json for the agent that’s running.
Still stuck? Ask in Discord or open a GitHub discussion.