文档
帮助
FAQ

FAQ

针对真实环境设置的快速解答和深入故障排除（本地开发、VPS、多代理、OAuth/API 密钥、模型故障转移）。 有关运行时诊断，请参阅 Troubleshooting. 有关完整配置参考，请参阅 Configuration.

目录

出现问题时的前60秒

  1. Quick status (first check)

    clawdbot status

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

  2. Pasteable report (safe to share)

    clawdbot status --all

    Read-only diagnosis with log tail (tokens redacted).

  3. Daemon + port state

    clawdbot gateway status

    Shows supervisor runtime vs RPC reachability, the probe target URL, and which config the service likely used.

  4. Deep probes

    clawdbot status --deep

    Runs gateway health checks + provider probes (requires a reachable gateway). See Health.

  5. Tail the latest log

    clawdbot logs --follow

    If RPC is down, fall back to:

    tail -f "$(ls -t /tmp/clawdbot/clawdbot-*.log | head -1)"

    File logs are separate from service logs; see Logging and Troubleshooting.

  6. Run the doctor (repairs)

    clawdbot doctor

    Repairs/migrates config/state + runs health checks. See Doctor.

  7. Gateway snapshot

    clawdbot health --json
clawdbot 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://clawd.bot/install.sh | bash -s -- --install-method git

This installs Clawdbot 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/clawdbot/clawdbot/issues https://github.com/clawdbot/clawdbot/pulls

Start with these commands (share outputs when asking for help):

clawdbot status
clawdbot models status
clawdbot doctor

What they do:

  • clawdbot status: quick snapshot of gateway/agent health + basic config.
  • clawdbot models status: checks provider auth + model availability.
  • clawdbot doctor: validates and repairs common config/state issues.

Other useful CLI checks: clawdbot status --all, clawdbot logs --follow, clawdbot gateway status, clawdbot health --verbose.

Quick debug loop: First 60 seconds if something’s broken. Install docs: Install, Installer flags, Updating.

推荐如何安装和设置 Clawdbot？

The repo recommends running from source and using the onboarding wizard:

curl -fsSL https://clawd.bot/install.sh | bash
clawdbot 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/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm build
pnpm ui:build # auto-installs UI deps on first run
clawdbot onboard

If you don’t have a global install yet, run it via pnpm clawdbot onboard.

初始化设置后如何打开仪表板？

The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine. Tokens stay local to your host-nothing is fetched from the browser.

如何在本地主机和远程服务器上验证仪表板（令牌）？

Localhost (same machine):

  • Open http://127.0.0.1:18789/.
  • If it asks for auth, run clawdbot dashboard and use the tokenized link (?token=...).
  • The token is the same value as gateway.auth.token (or CLAWDBOT_GATEWAY_TOKEN) and is stored by the UI after first load.

Not on localhost:

  • Tailscale Serve (recommended): keep bind loopback, run clawdbot gateway --tailscale serve, open https://<magicdns>/. If gateway.auth.allowTailscale is true, identity headers satisfy auth (no token).
  • Tailnet bind: run clawdbot gateway --bind tailnet --token "<token>", open http://<tailscale-ip>:18789/, paste token in dashboard settings.
  • SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/?token=... from clawdbot dashboard.

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.

  • Use a 64-bit OS and keep Node >= 22.
  • Prefer the hackable (git) install so you can see logs and update fast.
  • Start without channels/skills, then add them one by one.
  • If you hit weird binary issues, it is usually an ARM compatibility problem.

Docs: Linux, Install.

卡在"醒醒朋友"/初始化设置无法完成。怎么办？

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.

  1. Restart the Gateway:
clawdbot gateway restart
  1. Check status + auth:
clawdbot status
clawdbot models status
clawdbot logs --follow
  1. If it still hangs, run:
clawdbot 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.

无需重新进行初始化设置，我可以将设置迁移到新机器（Mac mini）吗？

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:

  1. Install Clawdbot on the new machine.
  2. Copy $CLAWDBOT_STATE_DIR (default: ~/.clawdbot) from the old machine.
  3. Copy your workspace (default: ~/clawd).
  4. Run clawdbot 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 ~/.clawdbot/ (for example ~/.clawdbot/agents/<agentId>/sessions/).

Related: Where things live on disk, Agent workspace, Doctor, Remote mode.

哪里可以看到最新版本的更新内容？

Check the GitHub changelog:
https://github.com/clawdbot/clawdbot/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).

无法访问 docs.clawd.bot（SSL 错误）。怎么办？

Some Comcast/Xfinity connections incorrectly block docs.clawd.bot via Xfinity Advanced Security. Disable it or allowlist docs.clawd.bot, 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/clawdbot/clawdbot/tree/main/docs

stable 和 beta 版本有什么区别？

Stable and beta are npm dist‑tags, not separate code lines:

  • latest = stable
  • beta = early build for testing

We 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/clawdbot/clawdbot/blob/main/CHANGELOG.md

如何安装 beta 版本，beta 和 dev 版本有什么区别？

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://clawd.bot/install.sh | bash -s -- --beta
curl -fsSL --proto '=https' --tlsv1.2 https://clawd.bot/install.sh | bash -s -- --install-method git

Windows installer (PowerShell): https://clawd.bot/install.ps1

More detail: Development channels and Installer flags.

安装和初始化设置通常需要多长时间？

Rough guide:

  • Install: 2-5 minutes
  • Onboarding: 5-15 minutes depending on how many channels/models you configure

If it hangs, use Installer stuck and the fast debug loop in Im stuck.

如何试用最新版本？

Two options:

  1. Dev channel (git checkout):
clawdbot update --channel dev

This switches to the main branch and updates from source.

  1. Hackable install (from the installer site):
curl -fsSL https://clawd.bot/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/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm build

Docs: Update, Development channels, Install.

安装程序卡住了？如何获取更多信息？

Re-run the installer with verbose output:

curl -fsSL https://clawd.bot/install.sh | bash -s -- --verbose

Beta install with verbose:

curl -fsSL https://clawd.bot/install.sh | bash -s -- --beta --verbose

For a hackable (git) install:

curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --verbose

More options: Installer flags.

Windows 安装提示找不到 git 或无法识别 clawdbot

Two common Windows issues:

1) npm error spawn git / git not found

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

2) clawdbot is not recognized after install

  • Your npm global bin folder is not on PATH.
  • Check the path:
    npm config get prefix
  • Ensure <prefix>\\bin is on PATH (on most systems it is %AppData%\\npm).
  • Close and reopen PowerShell after updating PATH.

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://clawd.bot/install.sh | bash -s -- --install-method git

More detail: Install and Installer flags.

如何在 Linux 上安装 Clawdbot？

Short answer: follow the Linux guide, then run the onboarding wizard.

如何在 VPS 上安装 Clawdbot？

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.

云服务器/VPS 安装指南在哪里？

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.

我可以让 Clawd 自我更新吗？

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:

clawdbot update
clawdbot update status
clawdbot update --channel stable|beta|dev
clawdbot update --tag <dist-tag|version>
clawdbot update --no-restart

If you must automate from an agent:

clawdbot update --yes --no-restart
clawdbot gateway restart

Docs: Update, Updating.

初始化向导实际上是做什么的？

clawdbot onboard is the recommended setup path. In local mode it walks you through:

  • Model/auth setup (Anthropic setup-token recommended for Claude subscriptions, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)
  • Workspace location + bootstrap files
  • Gateway settings (bind/port/auth/tailscale)
  • Providers (WhatsApp, Telegram, Discord, Mattermost (plugin), Signal, iMessage)
  • Daemon install (LaunchAgent on macOS; systemd user unit on Linux/WSL2)
  • Health checks and skills selection

It also warns if your configured model is unknown or missing auth.

运行这个需要 Claude 或 OpenAI 订阅吗？

No. You can run Clawdbot 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.

我可以在没有 API 密钥的情况下使用 Claude Max 订阅吗

Yes. You can authenticate with Claude Code CLI OAuth or 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.

Anthropic “setup-token” 认证是如何工作的？

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. If Claude Code CLI credentials are present on the gateway host, Clawdbot can reuse them; otherwise choose Anthropic token (paste setup-token) and paste the string. The token is stored as an auth profile for the anthropic provider and used like an API key or OAuth profile. More detail: OAuth.

Clawdbot keeps auth.profiles["anthropic:claude-cli"].mode set to "oauth" so the profile accepts both OAuth and setup-token credentials; older "token" mode entries auto-migrate.

在哪里可以找到 Anthropic setup-token？

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 clawdbot models auth setup-token --provider anthropic. If you ran claude setup-token elsewhere, paste it on the gateway host with clawdbot models auth paste-token --provider anthropic. See Anthropic.

你们支持 Claude 订阅认证（Claude Code OAuth）吗？

Yes. Clawdbot can reuse Claude Code CLI credentials (OAuth) and also supports setup-token. If you have a Claude subscription, we recommend setup-token for long‑running setups (requires Claude Pro/Max + the claude CLI). You can generate it anywhere and paste it on the gateway host. OAuth reuse is supported, but avoid logging in separately via Clawdbot and Claude Code to prevent token conflicts. 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.

为什么我从 Anthropic 收到 HTTP 429: rate_limit_error？

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 Clawdbot can keep replying while a provider is rate‑limited. See Models and OAuth.

支持 AWS Bedrock 吗？

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.

Codex 认证是如何工作的？

Clawdbot supports OpenAI Code (Codex) via OAuth or by reusing your Codex CLI login (~/.codex/auth.json). The wizard can import the CLI login or run the OAuth flow and will set the default model to openai-codex/gpt-5.2 when appropriate. See Model providers and Wizard.

你们支持 OpenAI 订阅认证（Codex OAuth）吗？

Yes. Clawdbot fully supports OpenAI Code (Codex) subscription OAuth and can also reuse an existing Codex CLI login (~/.codex/auth.json) on the gateway host. The onboarding wizard can import the CLI login or run the OAuth flow for you.

See OAuth, Model providers, and Wizard.

如何设置 Gemini CLI OAuth

Gemini CLI uses a plugin auth flow, not a client id or secret in clawdbot.json.

Steps:

  1. Enable the plugin: clawdbot plugins enable google-gemini-cli-auth
  2. Login: clawdbot models auth login --provider google-gemini-cli --set-default

This stores OAuth tokens in auth profiles on the gateway host. Details: Model providers.

本地模型适合日常聊天吗？

Usually no. Clawdbot 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.

必须购买 Mac Mini 才能安装这个吗？

No. Clawdbot 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, you can keep the Gateway on Linux and run imsg on any Mac over SSH by pointing channels.imessage.cliPath at an SSH wrapper. If you want other macOS‑only tools, run the Gateway on a Mac or pair a macOS node.

Docs: iMessage, Nodes, Mac remote mode.

iMessage 支持需要 Mac mini 吗？

You need some macOS device signed into Messages. It does not have to be a Mac mini - any Mac works. Clawdbot’s iMessage integrations run on macOS (BlueBubbles or imsg), while the Gateway can run elsewhere.

Common setups:

  • Run the Gateway on Linux/VPS, and point channels.imessage.cliPath at an SSH wrapper that runs imsg on the Mac.
  • Run everything on the Mac if you want the simplest single‑machine setup.

Docs: iMessage, BlueBubbles, Mac remote mode.

如果我购买 Mac mini 来运行 Clawdbot，可以将其连接到我的 MacBook Pro 吗？

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:

  • Gateway on the Mac mini (always‑on).
  • MacBook Pro runs the macOS app or a node host and pairs to the Gateway.
  • Use clawdbot nodes status / clawdbot nodes list to see it.

Docs: Nodes, Nodes CLI.

我可以使用 Bun 吗？

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.

Telegram：allowFrom 中应该填什么？

channels.telegram.allowFrom is the human sender’s Telegram user ID (numeric, recommended) or @username. It is not the bot username.

Safer (no third-party bot):

  • DM your bot, then run clawdbot logs --follow and read from.id.

Official Bot API:

  • DM your bot, then call https://api.telegram.org/bot<bot_token>/getUpdates and read message.from.id.

Third-party (less private):

  • DM @userinfobot or @getidsbot.

See /channels/telegram.

多个人可以使用一个 WhatsApp 号码配合不同的 Clawdbot 吗？

Yes, via multi‑agent routing. Bind each sender’s WhatsApp DM (peer kind: "dm", 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.

我可以同时运行"快速聊天"代理和"Opus 编程"代理吗？

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.

Homebrew 可以在 Linux 上运行吗？

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 Clawdbot 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.

可破解（git）安装和 npm 安装有什么区别？

  • Hackable (git) install: full source checkout, editable, best for contributors. You run builds 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.

以后可以在 npm 和 git 安装之间切换吗？

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 Clawdbot code install. Your state (~/.clawdbot) and workspace (~/clawd) stay untouched.

From npm → git:

git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot
pnpm install
pnpm build
clawdbot doctor
clawdbot gateway restart

From git → npm:

npm install -g clawdbot@latest
clawdbot doctor
clawdbot 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.

我应该在我的笔记本电脑还是 VPS 上运行网关？

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)

  • Pros: no server cost, direct access to local files, live browser window.
  • Cons: sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.

VPS / cloud

  • Pros: always‑on, stable network, no laptop sleep issues, easier to keep running.
  • Cons: often run headless (use screenshots), remote file access only, you must SSH for updates.

Clawdbot-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.

在专用机器上运行 Clawdbot 有多重要？

Not required, but recommended for reliability and isolation.

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

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.

最低 VPS 要求和推荐的操作系统是什么？

Clawdbot is lightweight. For a basic Gateway + one chat channel:

  • Absolute minimum: 1 vCPU, 1GB RAM, ~500MB disk.
  • Recommended: 1-2 vCPU, 2GB RAM or more for headroom (logs, media, multiple channels). Node tools and browser automation can be resource hungry.

OS: use Ubuntu LTS (or any modern Debian/Ubuntu). The Linux install path is best tested there.

Docs: Linux, VPS hosting.

我可以在 VM 中运行 Clawdbot 吗，有什么要求

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:

  • Absolute minimum: 1 vCPU, 1GB RAM.
  • Recommended: 2GB RAM or more if you run multiple channels, browser automation, or media tools.
  • OS: Ubuntu LTS or another modern Debian/Ubuntu.

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.

什么是 Clawdbot？

用一段话解释什么是 Clawdbot？

Clawdbot 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.

价值主张是什么？

Clawdbot 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:

  • Your devices, your data: run the Gateway wherever you want (Mac, Linux, VPS) and keep the workspace + session history local.
  • Real channels, not a web sandbox: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc, plus mobile voice and Canvas on supported platforms.
  • Model-agnostic: use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per‑agent routing and failover.
  • Local-only option: run local models so all data can stay on your device if you want.
  • Multi-agent routing: separate agents per channel, account, or task, each with its own workspace and defaults.
  • Open source and hackable: inspect, extend, and self-host without vendor lock‑in.

Docs: Gateway, Channels, Multi‑agent, Memory.

我刚刚设置好了，首先应该做什么

Good first projects:

  • Build a website (WordPress, Shopify, or a simple static site).
  • Prototype a mobile app (outline, screens, API plan).
  • Organize files and folders (cleanup, naming, tagging).
  • Connect Gmail and automate summaries or follow ups.

It can handle large tasks, but it works best when you split them into phases and use sub agents for parallel work.

Clawdbot 的五大日常使用场景是什么

Everyday wins usually look like:

  • Personal briefings: summaries of inbox, calendar, and news you care about.
  • Research and drafting: quick research, summaries, and first drafts for emails or docs.
  • Reminders and follow ups: cron or heartbeat driven nudges and checklists.
  • Browser automation: filling forms, collecting data, and repeating web tasks.
  • Cross device coordination: send a task from your phone, let the Gateway run it on a server, and get the result back in chat.

Clawdbot 可以帮助 SaaS 进行潜在客户开发、外联、广告和博客吗

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 Clawdbot draft and you approve.

Docs: Security.

与 Claude Code 相比在 Web 开发方面有什么优势？

Clawdbot 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 Clawdbot when you want durable memory, cross-device access, and tool orchestration.

Advantages:

  • Persistent memory + workspace across sessions
  • Multi-platform access (WhatsApp, Telegram, TUI, WebChat)
  • Tool orchestration (browser, files, scheduling, hooks)
  • Always-on Gateway (run on a VPS, interact from anywhere)
  • Nodes for local browser/screen/camera/exec

Showcase: https://clawd.bot/showcase

技能和自动化

如何自定义技能而不让仓库变脏？

Use managed overrides instead of editing the repo copy. Put your changes in ~/.clawdbot/skills/<name>/SKILL.md (or add a folder via skills.load.extraDirs in ~/.clawdbot/clawdbot.json). Precedence is <workspace>/skills > ~/.clawdbot/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 ~/.clawdbot/clawdbot.json (lowest precedence). Default precedence remains: <workspace>/skills → ~/.clawdbot/skills → bundled → skills.load.extraDirs. clawdhub installs into ./skills by default, which Clawdbot treats as <workspace>/skills.

如何为不同任务使用不同的模型？

Today the supported patterns are:

  • Cron jobs: isolated jobs can set a model override per job.
  • Sub-agents: route tasks to separate agents with different default models.
  • On-demand switch: use /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 或提醒未触发。应该检查什么？

Cron runs inside the Gateway process. If the Gateway is not running continuously, scheduled jobs will not run.

Checklist:

  • Confirm cron is enabled (cron.enabled) and CLAWDBOT_SKIP_CRON is not set.
  • Check the Gateway is running 24/7 (no sleep/restarts).
  • Verify timezone settings for the job (--tz vs host timezone).

Debug:

clawdbot cron run <jobId> --force
clawdbot cron runs --id <jobId> --limit 50

Docs: Cron jobs, Cron vs Heartbeat.

如何在 Linux 上安装技能？

Use ClawdHub (CLI) or drop skills into your workspace. The macOS Skills UI isn’t available on Linux. Browse skills at https://clawdhub.com.

Install the ClawdHub CLI (pick one package manager):

npm i -g clawdhub
pnpm add -g clawdhub

Clawdbot 可以按计划或在后台持续运行任务吗？

Yes. Use the Gateway scheduler:

  • Cron jobs for scheduled or recurring tasks (persist across restarts).
  • Heartbeat for “main session” periodic checks.
  • Isolated jobs for autonomous agents that post summaries or deliver to chats.

Docs: Cron jobs, Cron vs Heartbeat, Heartbeat.

Can I run Apple macOS only skills from Linux

Not directly. macOS skills are gated by metadata.clawdbot.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 imsg, apple-notes, apple-reminders) 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. Clawdbot 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.

  1. Create an SSH wrapper for the binary (example: imsg):
    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@"
  2. Put the wrapper on PATH on the Linux host (for example ~/bin/imsg).
  3. Override the skill metadata (workspace or ~/.clawdbot/skills) to allow Linux:
    ---
name: imsg
description: iMessage/SMS CLI for listing chats, history, watch, and sending.
metadata: {"clawdbot":{"os":["darwin","linux"],"requires":{"bins":["imsg"]}}}
---
  4. Start a new session so the skills snapshot refreshes.

For iMessage specifically, you can also point channels.imessage.cliPath at an SSH wrapper (Clawdbot only needs stdio). See iMessage.

你们有 Notion 或 HeyGen 集成吗？

Not built‑in today.

Options:

  • Custom skill / plugin: best for reliable API access (Notion/HeyGen both have APIs).
  • Browser automation: works without code but is slower and more fragile.

If you want to keep context per client (agency workflows), a simple pattern is:

  • One Notion page per client (context + preferences + active work).
  • Ask the agent to fetch that page at the start of a session.

If you want a native integration, open a feature request or build a skill targeting those APIs.

Install skills:

clawdhub install <skill-slug>
clawdhub update --all

ClawdHub installs into ./skills under your current directory (or falls back to your configured Clawdbot workspace); Clawdbot treats that as <workspace>/skills on the next session. For shared skills across agents, place them in ~/.clawdbot/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 ClawdHub.

如何安装 Chrome 扩展程序以接管浏览器？

Use the built-in installer, then load the unpacked extension in Chrome:

clawdbot browser extension install
clawdbot browser extension path

Then Chrome → chrome://extensions → enable “Developer mode” → “Load unpacked” → pick that folder.

Full guide (including remote Gateway via Tailscale + security notes): Chrome extension

If the Gateway runs on the same machine as Chrome (default setup), you usually do not need clawdbot browser serve. 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.

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.

内存是如何工作的？

Clawdbot memory is just Markdown files in the agent workspace:

  • Daily notes in memory/YYYY-MM-DD.md
  • Curated long-term notes in MEMORY.md (main/private sessions only)

Clawdbot 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.

语义内存搜索需要 OpenAI API 密钥吗？

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, Clawdbot 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, Clawdbot 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.

Docs: Memory, Context.

文件在磁盘上的位置

Clawdbot 使用的所有数据都保存在本地吗？

No - Clawdbot’s state is local, but external services still see what you send them.

  • Local by default: sessions, memory files, config, and workspace live on the Gateway host (~/.clawdbot + your workspace directory).
  • Remote by necessity: messages you send to model providers (Anthropic/OpenAI/etc.) go to their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their servers.
  • You control the footprint: using local models keeps prompts on your machine, but channel traffic still goes through the channel’s servers.

Related: Agent workspace, Memory.

Clawdbot 将其数据存储在哪里？

Everything lives under $CLAWDBOT_STATE_DIR (default: ~/.clawdbot):

PathPurpose
$CLAWDBOT_STATE_DIR/clawdbot.jsonMain config (JSON5)
$CLAWDBOT_STATE_DIR/credentials/oauth.jsonLegacy OAuth import (copied into auth profiles on first use)
$CLAWDBOT_STATE_DIR/agents/<agentId>/agent/auth-profiles.jsonAuth profiles (OAuth + API keys)
$CLAWDBOT_STATE_DIR/agents/<agentId>/agent/auth.jsonRuntime auth cache (managed automatically)
$CLAWDBOT_STATE_DIR/credentials/Provider state (e.g. whatsapp/<accountId>/creds.json)
$CLAWDBOT_STATE_DIR/agents/Per‑agent state (agentDir + sessions)
$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/Conversation history & state (per agent)
$CLAWDBOT_STATE_DIR/agents/<agentId>/sessions/sessions.jsonSession metadata (per agent)

Legacy single‑agent path: ~/.clawdbot/agent/* (migrated by clawdbot doctor).

Your workspace (AGENTS.md, memory files, skills, etc.) is separate and configured via agents.defaults.workspace (default: ~/clawd).

AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放在哪里？

These files live in the agent workspace, not ~/.clawdbot.

  • Workspace (per agent): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md (or memory.md), memory/YYYY-MM-DD.md, optional HEARTBEAT.md.
  • State dir (~/.clawdbot): config, credentials, auth profiles, sessions, logs, and shared skills (~/.clawdbot/skills).

Default workspace is ~/clawd, configurable via:

{
  agents: { defaults: { workspace: "~/clawd" } }
}

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 ~/.clawdbot (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.

如何完全卸载 Clawdbot？

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 Clawdbot 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.

配置基础

配置是什么格式？在哪里？

Clawdbot reads an optional JSON5 config from $CLAWDBOT_CONFIG_PATH (default: ~/.clawdbot/clawdbot.json):

$CLAWDBOT_CONFIG_PATH

If the file is missing, it uses safe‑ish defaults (including a default workspace of ~/clawd).

我设置了 gateway.bind: "lan"（或 "tailnet"），现在什么都没有监听/UI 显示未授权

Non-loopback binds require auth. Configure gateway.auth.mode + gateway.auth.token (or use CLAWDBOT_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.
  • The Control UI authenticates via 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: clawdbot 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 ones
  • hot, restart, off are also supported

如何启用网络搜索（和网络获取）？

web_fetch works without an API key. web_search requires a Brave Search API key. Recommended: run clawdbot 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:

  • If you use allowlists, add web_search/web_fetch or group:web.
  • web_fetch is enabled by default (unless explicitly disabled).
  • Daemons read env vars from ~/.clawdbot/.env (or the service environment).

Docs: Web tools.

如何运行中央网关并在不同设备上使用专用工作程序？

The common pattern is one Gateway (e.g. Raspberry Pi) plus nodes and agents:

  • Gateway (central): owns channels (Signal/WhatsApp), routing, and sessions.
  • Nodes (devices): Macs/iOS/Android connect as peripherals and expose local tools (system.run, canvas, camera).
  • Agents (workers): separate brains/workspaces for special roles (e.g. “Hetzner ops”, “Personal data”).
  • Sub‑agents: spawn background work from a main agent when you want parallelism.
  • TUI: connect to the Gateway and switch agents/sessions.

Docs: Nodes, Remote access, Multi-Agent Routing, Sub-agents, TUI.

Clawdbot 浏览器可以无头运行吗？

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:

  • No visible browser window (use screenshots if you need visuals).
  • Some sites are stricter about automation in headless mode (CAPTCHAs, anti‑bot). For example, X/Twitter often blocks headless sessions.

如何使用 Brave 进行浏览器控制？

Set browser.executablePath to your Brave binary (or any Chromium-based browser) and restart the Gateway. See the full config examples in Browser.

远程网关 + 节点

命令如何在 Telegram、网关和节点之间传播？

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:

  1. Run the Gateway on the always‑on host (VPS/home server).
  2. Put the Gateway host + your computer on the same tailnet.
  3. Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).
  4. Open the macOS app locally and connect in Remote over SSH mode (or direct tailnet) so it can register as a node.
  5. Approve the node on the Gateway:
    clawdbot nodes pending
clawdbot 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.

Tailscale 已连接但没有收到回复。怎么办？

Check the basics:

  • Gateway is running: clawdbot gateway status
  • Gateway health: clawdbot status
  • Channel health: clawdbot channels status

Then verify auth and routing:

  • If you use Tailscale Serve, make sure gateway.auth.allowTailscale is set correctly.
  • If you connect via SSH tunnel, confirm the local tunnel is up and points at the right port.
  • Confirm your allowlists (DM or group) include your account.

Docs: Tailscale, Remote access, Channels.

两个 Clawdbot 可以相互通信吗（本地 + VPS）？

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 clawdbot 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):

clawdbot 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.

多个代理需要单独的 VPS 吗

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.

在我的个人笔记本电脑上使用节点而不是从 VPS SSH 有什么好处？

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.

  • No inbound SSH required. Nodes connect out to the Gateway WebSocket and use device pairing.
  • Safer execution controls. system.run is gated by node allowlists/approvals on that laptop.
  • More device tools. Nodes expose canvas, camera, and screen in addition to system.run.
  • Local browser automation. Keep the Gateway on a VPS, but run Chrome locally and relay control with the Chrome extension + clawdbot browser serve.

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.

有 API/RPC 方式来应用配置吗？

Yes. config.apply validates + writes the full config and restarts the Gateway as part of the operation.

config.apply 清除了我的配置。如何恢复并避免这种情况？

config.apply replaces the entire config. If you send a partial object, everything else is removed.

Recover:

  • Restore from backup (git or a copied ~/.clawdbot/clawdbot.json).
  • If you have no backup, re-run clawdbot doctor and reconfigure channels/models.
  • If this was unexpected, file a bug and include your last known config or any backup.
  • A local coding agent can often reconstruct a working config from logs or history.

Avoid it:

  • Use clawdbot config set for small changes.
  • Use clawdbot configure for interactive edits.

Docs: Config, Configure, Doctor.

首次安装的最小"合理"配置是什么？ 

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

This sets your workspace and restricts who can trigger the bot.

如何在 VPS 上设置 Tailscale 并从 Mac 连接？

Minimal steps:

  1. Install + login on the VPS
    curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
  2. Install + login on your Mac
    • Use the Tailscale app and sign in to the same tailnet.
  3. Enable MagicDNS (recommended)
    • In the Tailscale admin console, enable MagicDNS so the VPS has a stable name.
  4. Use the tailnet hostname

If you want the Control UI without SSH, use Tailscale Serve on the VPS:

clawdbot gateway --tailscale serve

This keeps the gateway bound to loopback and exposes HTTPS via Tailscale. See Tailscale.

如何将 Mac 节点连接到远程网关（Tailscale Serve）？

Serve exposes the Gateway Control UI + WS. Nodes connect over the same Gateway WS endpoint.

Recommended setup:

  1. Make sure the VPS + Mac are on the same tailnet.
  2. Use the macOS app in Remote mode (SSH target can be the tailnet hostname). The app will tunnel the Gateway port and connect as a node.
  3. Approve the node on the gateway:
    clawdbot nodes pending
clawdbot nodes approve <requestId>

Docs: Gateway protocol, Discovery, macOS remote mode.

环境变量和 .env 加载

Clawdbot 如何加载环境变量？

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

  • .env from the current working directory
  • a global fallback .env from ~/.clawdbot/.env (aka $CLAWDBOT_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:

  1. Put the missing keys in ~/.clawdbot/.env so they’re picked up even when the service doesn’t inherit your shell env.
  2. Enable shell import (opt‑in convenience):
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents: CLAWDBOT_LOAD_SHELL_ENV=1, CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000.

I set COPILOTGITHUBTOKEN but models status shows Shell env off Why

clawdbot models status reports whether shell env import is enabled. “Shell env: off” does not mean your env vars are missing - it just means Clawdbot 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:

  1. Put the token in ~/.clawdbot/.env:
    COPILOT_GITHUB_TOKEN=...
  2. Or enable shell import (env.shellEnv.enabled: true).
  3. Or add it to your config env block (applies only if missing).

Then restart the gateway and recheck:

clawdbot 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.

如果我不发送 /new，会话会自动重置吗？

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
  }
}

有没有办法组建一个 Clawdbot 团队（一个 CEO 和多个代理）

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:

  • Ask the bot to summarize the current state and write it to a file.
  • Use /compact before long tasks, and /new when switching topics.
  • Keep important context in the workspace and ask the bot to read it back.
  • Use sub-agents for long or parallel work so the main chat stays smaller.
  • Pick a model with a larger context window if this happens often.

如何完全重置 Clawdbot 但保留安装？

Use the reset command:

clawdbot reset

Non-interactive full reset:

clawdbot reset --scope full --yes --non-interactive

Then re-run onboarding:

clawdbot onboard --install-daemon

Notes:

  • The onboarding wizard also offers Reset if it sees an existing config. See Wizard.
  • If you used profiles (--profile / CLAWDBOT_PROFILE), reset each state dir (defaults are ~/.clawdbot-<profile>).
  • Dev reset: clawdbot 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:

  • Enable or tune session pruning (agents.defaults.contextPruning) to trim old tool output.
  • Use a model with a larger context window.

Docs: Compaction, Session pruning, Session management.

为什么我看到"LLM request rejected: messages.N.content.X.tool_use.input: Field required”？

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).

为什么我每30分钟收到一次心跳消息？

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), Clawdbot 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.

需要将"机器人帐户"添加到 WhatsApp 群组吗？

No. Clawdbot runs on your own account, so if you’re in the group, Clawdbot 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"]
    }
  }
}

如何获取 WhatsApp 群组的 JID？

Option 1 (fastest): tail logs and send a test message in the group:

clawdbot 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:

clawdbot directory groups list --channel whatsapp

Docs: WhatsApp, Directory, Logs.

为什么 Clawdbot 在群组中不回复？

Two common causes:

  • Mention gating is on (default). You must @mention the bot (or match mentionPatterns).
  • You configured 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:

  • Disk growth: sessions + transcripts live under ~/.clawdbot/agents/<agentId>/sessions/.
  • Token cost: more agents means more concurrent model usage.
  • Ops overhead: per-agent auth profiles, workspaces, and channel routing.

Tips:

  • Keep one active workspace per agent (agents.defaults.workspace).
  • Prune old sessions (delete JSONL or store entries) if disk grows.
  • Use clawdbot doctor to spot stray workspaces and profile mismatches.

我可以同时运行多个机器人或聊天（Slack）吗，应该如何设置？

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:

  • Always‑on Gateway host (VPS/Mac mini).
  • One agent per role (bindings).
  • Slack channel(s) bound to those agents.
  • Local browser via extension relay (or a node) when needed.

Docs: Multi‑Agent Routing, Slack, Browser, Chrome extension, Nodes.

模型：默认值、选择、别名、切换

“默认模型"是什么？

Clawdbot’s default model is whatever you set as:

agents.defaults.model.primary

Models are referenced as provider/model (example: anthropic/claude-opus-4-5). If you omit the provider, Clawdbot currently assumes anthropic as a temporary deprecation fallback - but you should still explicitly set provider/model.

你推荐什么模型？

Recommended default: anthropic/claude-opus-4-5.
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.

我可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？

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)
  • clawdbot models set ... (updates just model config)
  • clawdbot configure --section models (interactive)
  • edit agents.defaults.model in ~/.clawdbot/clawdbot.json

Avoid 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 clawdbot doctor to repair.

Docs: Models, Configure, Config, Doctor.

Clawd、Flawd 和 Krill 使用什么模型？

  • Clawd + Flawd: Anthropic Opus (anthropic/claude-opus-4-5) - see Anthropic.
  • Krill: MiniMax M2.1 (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:claude-cli
/model opus@anthropic:default

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-5

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.

Can I use GPT 5.2 for daily tasks and Codex 5.2 for coding

Yes. Set one as default and switch as needed:

  • Quick switch (per session): /model gpt-5.2 for daily tasks, /model gpt-5.2-codex for coding.
  • Default + switch: set agents.defaults.model.primary to openai-codex/gpt-5.2, then switch to openai-codex/gpt-5.2-codex when coding (or the other way around).
  • Sub-agents: route coding tasks to sub-agents with a different default model.

See Models and Slash commands.

为什么我看到"Model … is not allowed"然后没有回复？

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.

为什么我看到"Unknown model: minimax/MiniMax-M2.1”？

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:

  1. Upgrade to 2026.1.12 (or run from source main), then restart the gateway.
  2. Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key exists in env/auth profiles so the provider can be injected.
  3. Use the exact model id (case‑sensitive): minimax/MiniMax-M2.1 or minimax/MiniMax-M2.1-lightning.
  4. Run:
    clawdbot models list
    and pick from the list (or /model list in chat).

See MiniMax and Models.

我可以将 MiniMax 作为默认值，OpenAI 用于复杂任务吗？

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 A default: MiniMax
  • Agent B default: OpenAI
  • Route by agent or use /agent to switch

Docs: Models, Multi-Agent Routing, MiniMax, OpenAI.

opus / sonnet / gpt 是内置快捷方式吗？

Yes. Clawdbot ships a few default shorthands (only applied when the model exists in agents.defaults.models):

  • opus → anthropic/claude-opus-4-5
  • sonnet → anthropic/claude-sonnet-4-5
  • gpt → openai/gpt-5.2
  • gpt-mini → openai/gpt-5-mini
  • gemini → google/gemini-3-pro-preview
  • gemini-flash → google/gemini-3-flash-preview

If 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-5" },
      models: {
        "anthropic/claude-opus-4-5": { 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 或 Z.AI）的模型？

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:

~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

Fix options:

  • Run clawdbot agents add <id> and configure auth during the wizard.
  • Or copy 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.

Model failover and “All models failed”

故障转移是如何工作的？

Failover happens in two stages:

  1. Auth profile rotation within the same provider.
  2. Model fallback to the next model in agents.defaults.model.fallbacks.

Cooldowns apply to failing profiles (exponential backoff), so Clawdbot 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.

No credentials found for profile "anthropic:default"的修复清单

  • Confirm where auth profiles live (new vs legacy paths)
    • Current: ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json
    • Legacy: ~/.clawdbot/agent/* (migrated by clawdbot doctor)
  • Confirm your env var is loaded by the Gateway
    • If you set ANTHROPIC_API_KEY in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in ~/.clawdbot/.env or enable env.shellEnv.
  • Make sure you’re editing the correct agent
    • Multi‑agent setups mean there can be multiple auth-profiles.json files.
  • Sanity‑check model/auth status
    • Use clawdbot models status to see configured models and whether providers are authenticated.

Fix checklist for No credentials found for profile anthropic claude cli

This means the run is pinned to the Claude Code CLI profile, but the Gateway can’t find that profile in its auth store.

  • Sync the Claude Code CLI token on the gateway host
    • Run clawdbot models status (it loads + syncs Claude Code CLI credentials).
    • If it still says missing: run claude setup-token (or clawdbot models auth setup-token --provider anthropic) and retry.
  • If the token was created on another machine
    • Paste it into the gateway host with clawdbot models auth paste-token --provider anthropic.
  • Check the profile mode
    • auth.profiles["anthropic:claude-cli"].mode must be "oauth" (token mode rejects OAuth credentials).
  • If you want to use an API key instead
    • Put ANTHROPIC_API_KEY in ~/.clawdbot/.env on the gateway host.
    • Clear any pinned order that forces anthropic:claude-cli:
      clawdbot models auth order clear --provider anthropic
  • Confirm you’re running commands on the gateway host
    • In remote mode, auth profiles live on the gateway machine, not your laptop.

为什么它也尝试了 Google Gemini 并且失败了？

If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), Clawdbot 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: Clawdbot 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, CLI sync)

什么是认证配置文件？

An auth profile is a named credential record (OAuth or API key) tied to a provider. Profiles live in:

~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

典型的配置文件 ID 是什么？

Clawdbot uses provider‑prefixed IDs like:

  • anthropic:default (common when no email identity exists)
  • anthropic:<email> for OAuth identities
  • custom IDs you choose (e.g. anthropic: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.

Clawdbot 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 clawdbot 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)
clawdbot models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
clawdbot models auth order set --provider anthropic anthropic:claude-cli

# Or set an explicit order (fallback within provider)
clawdbot models auth order set --provider anthropic anthropic:claude-cli anthropic:default

# Clear override (fall back to config auth.order / round-robin)
clawdbot models auth order clear --provider anthropic

To target a specific agent:

clawdbot models auth order set --provider anthropic --agent main anthropic:claude-cli

OAuth vs API 密钥：有什么区别？

Clawdbot supports both:

  • OAuth often leverages subscription access (where applicable).
  • API keys use pay‑per‑token billing.

The wizard explicitly supports Anthropic OAuth and OpenAI Codex OAuth and can store API keys for you.

Gateway: ports, “already running”, and remote mode

网关使用什么端口？

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

Precedence:

--port > CLAWDBOT_GATEWAY_PORT > gateway.port > default 18789

为什么 clawdbot gateway status 显示 Runtime: running 但 RPC probe: failed？

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 clawdbot 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)

为什么 clawdbot gateway status 显示 Config (cli) 和 Config (service) 不同？

You’re editing one config file while the service is running another (often a --profile / CLAWDBOT_STATE_DIR mismatch).

Fix:

clawdbot gateway install --force

Run that from the same --profile / environment you want the service to use.

“另一个网关实例已在监听"是什么意思？

Clawdbot 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 clawdbot gateway --port <port>.

如何在远程模式下运行 Clawdbot（客户端连接到其他地方的网关）？

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:

  • clawdbot gateway only starts when gateway.mode is local (or you pass the override flag).
  • The macOS app watches the config file and switches modes live when these values change.

控制 UI 显示"未授权”（或不断重新连接）。怎么办？

Your gateway is running with auth enabled (gateway.auth.*), but the UI is not sending the matching token/password.

Facts (from code):

  • The Control UI stores the token in browser localStorage key clawdbot.control.settings.v1.
  • The UI can import ?token=... (and/or ?password=...) once, then strips it from the URL.

Fix:

  • Fastest: clawdbot dashboard (prints + copies tokenized link, tries to open; shows SSH hint if headless).
  • If you don’t have a token yet: clawdbot doctor --generate-gateway-token.
  • If remote, tunnel first: ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/?token=....
  • Set gateway.auth.token (or CLAWDBOT_GATEWAY_TOKEN) on the gateway host.
  • In the Control UI settings, paste the same token (or refresh with a one-time ?token=... link).
  • Still stuck? Run clawdbot status --all and follow Troubleshooting. See Dashboard for auth details.

我设置了 gateway.bind: "tailnet" 但无法绑定/什么都没有监听

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:

  • Start Tailscale on that host (so it has a 100.x address), or
  • Switch to 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:

  • CLAWDBOT_CONFIG_PATH (per‑instance config)
  • CLAWDBOT_STATE_DIR (per‑instance state)
  • agents.defaults.workspace (workspace isolation)
  • gateway.port (unique ports)

Quick setup (recommended):

  • Use clawdbot --profile <name> … per instance (auto-creates ~/.clawdbot-<name>).
  • Set a unique gateway.port in each profile config (or pass --port for manual runs).
  • Install a per-profile service: clawdbot --profile <name> gateway install.

Profiles also suffix service names (com.clawdbot.<profile>, clawdbot-gateway-<profile>.service, Clawdbot Gateway (<profile>)). Full guide: Multiple gateways.

“invalid handshake” / 代码 1008 是什么意思？

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:

  • You opened the HTTP URL in a browser (http://...) instead of a WS client.
  • You used the wrong port or path.
  • A proxy or tunnel stripped auth headers or sent a non‑Gateway request.

Quick fixes:

  1. Use the WS URL: ws://<host>:18789 (or wss://... if HTTPS).
  2. Don’t open the WS port in a normal browser tab.
  3. If auth is on, include the token/password in the connect frame.

If you’re using the CLI or TUI, the URL should look like:

clawdbot tui --url ws://<host>:18789 --token <token>

Protocol details: Gateway protocol.

日志记录和调试

日志在哪里？

File logs (structured):

/tmp/clawdbot/clawdbot-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:

clawdbot logs --follow

Service/supervisor logs (when the gateway runs via launchd/systemd):

  • macOS: $CLAWDBOT_STATE_DIR/logs/gateway.log and gateway.err.log (default: ~/.clawdbot/logs/...; profiles use ~/.clawdbot-<profile>/logs/...)
  • Linux: journalctl --user -u clawdbot-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "Clawdbot Gateway (<profile>)" /V /FO LIST

See Troubleshooting for more.

如何启动/停止/重启网关服务？

Use the gateway helpers:

clawdbot gateway status
clawdbot gateway restart

If you run the gateway manually, clawdbot gateway --force can reclaim the port. See Gateway.

我在 Windows 上关闭了终端 - 如何重启 Clawdbot？

There are two Windows install modes:

1) WSL2 (recommended): the Gateway runs inside Linux.

Open PowerShell, enter WSL, then restart:

wsl
clawdbot gateway status
clawdbot gateway restart

If you never installed the service, start it in the foreground:

clawdbot gateway run

2) Native Windows (not recommended): the Gateway runs directly in Windows.

Open PowerShell and run:

clawdbot gateway status
clawdbot gateway restart

If you run it manually (no service), use:

clawdbot gateway run

Docs: Windows (WSL2), Gateway service runbook.

网关已启动但回复从未到达。应该检查什么？

Start with a quick health sweep:

clawdbot status
clawdbot models status
clawdbot channels status
clawdbot logs --follow

Common causes:

  • Model auth not loaded on the gateway host (check models status).
  • Channel pairing/allowlist blocking replies (check channel config + logs).
  • WebChat/Dashboard is open without the right token.

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:

  1. Is the Gateway running? clawdbot gateway status
  2. Is the Gateway healthy? clawdbot status
  3. Does the UI have the right token? clawdbot dashboard
  4. If remote, is the tunnel/Tailscale link up?

Then tail logs:

clawdbot logs --follow

Docs: Dashboard, Remote access, Troubleshooting.

Telegram setMyCommands 因网络错误失败。应该检查什么？

Start with logs and channel status:

clawdbot channels status
clawdbot 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.

TUI 没有输出。应该检查什么？

First confirm the Gateway is reachable and the agent can run:

clawdbot status
clawdbot models status
clawdbot 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:

clawdbot gateway stop
clawdbot 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:

clawdbot gateway run

Docs: Gateway service runbook.

ELI5（像5岁一样解释）：clawdbot gateway restart vs clawdbot gateway

  • clawdbot gateway restart: restarts the background service (launchd/systemd).
  • clawdbot gateway: runs the gateway in the foreground for this terminal session.

If you installed the service, use the gateway commands. Use clawdbot 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.

媒体和附件

我的技能生成了图像/PDF，但什么都没有发送

Outbound attachments from the agent must include a MEDIA:<path-or-url> line (on its own line). See Clawdbot assistant setup and Agent send.

CLI sending:

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

Also check:

  • The target channel supports outbound media and isn’t blocked by allowlists.
  • The file is within the provider’s size limits (images are resized to max 2048px).

See Images.

安全和访问控制

将 Clawdbot 暴露给入站私信安全吗？

Treat inbound DMs as untrusted input. Defaults are designed to reduce risk:

  • Default behavior on DM‑capable channels is pairing:
    • Unknown senders receive a pairing code; the bot does not process their message.
    • Approve with: clawdbot pairing approve <channel> <code>
    • Pending requests are capped at 3 per channel; check clawdbot pairing list <channel> if a code didn’t arrive.
  • Opening DMs publicly requires explicit opt‑in (dmPolicy: "open" and allowlist "*").

Run clawdbot 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:

  • using a read-only or tool-disabled “reader” agent to summarize untrusted content
  • keeping web_search / web_fetch / browser off for tool-enabled agents
  • sandboxing and strict tool allowlists

Details: Security.

Should my bot have its own email GitHub account or phone number

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.

Docs: Security, Pairing.

我可以让它自主处理我的短信吗，这安全吗

We do not recommend full autonomy over your personal messages. The safest pattern is:

  • Keep DMs in pairing mode or a tight allowlist.
  • Use a separate number or account if you want it to message on your behalf.
  • Let it draft, then approve before sending.

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.

我在 Telegram 中运行了 /start 但没有收到配对代码

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:

clawdbot pairing list telegram

If you want immediate access, allowlist your sender id or set dmPolicy: "open" for that account.

WhatsApp：它会给我的联系人发消息吗？配对如何工作？

No. Default WhatsApp DM policy is pairing. Unknown senders only get a pairing code and their message is not processed. Clawdbot only replies to chats it receives or to explicit sends you trigger.

Approve pairing with:

clawdbot pairing approve whatsapp <code>

List pending requests:

clawdbot 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.

Chat commands, aborting tasks, and “it won’t stop”

如何阻止内部系统消息在聊天中显示

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.

如何从 Telegram 发送 Discord 消息？（“Cross-context messaging denied”）

Clawdbot 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 task
  • followup - run messages one at a time
  • collect - batch messages and reply once (default)
  • steer-backlog - steer now, then process backlog
  • interrupt - abort current run and start fresh

You can add options like debounce:2s cap:25 drop:summarize for followup modes.

Answer the exact question from the screenshot/chat log

Q: “What’s the default model for Anthropic with an API key?”

A: In Clawdbot, 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-5). 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.

故障排除