Openclaw (TrucBot) Installation Tips

Generate at console.anthropic.com → Settings → API Keys. Name it descriptively (e.g., TrucBot1-Production) so usage reports stay readable when you have multiple keys. The full key is shown once — save it to your password manager immediately.

Generate a new key per bot. Separate keys mean separate usage tracking, independent revocation, and clearer attribution when you hit a rate limit.

Open Telegram, search for @BotFather, send /newbot. You'll be asked for a display name and a unique username ending in bot. BotFather returns a token formatted <botID>:<secret> — save it immediately, it's shown once.

Each bot needs its own Telegram bot token. Sharing one token between OpenClaw instances will cause both to fight over getUpdates polling and lose messages at random.

While you're in BotFather, consider /setjoingroups → Disable if the bot is for personal DM only. Removes a whole category of group-chat abuse surface.

You'll need this to lock the bot down to your account via allowlist policy (don't skip this step — see Phase 4). Easiest source: message @userinfobot on Telegram, which replies with your numeric user ID. More private alternative: send your bot a test message after install, then check the gateway logs for your inbound message ID.

Discord, WhatsApp, Slack, custom API keys for your own services — collect whatever integrations the bot needs before running the wizard. Treat them all as per-bot, not shared.

Don't sudo npm install -g. The clean pattern is to point npm at a per-user prefix, then add that to your PATH:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest

This avoids the EACCES errors you'll otherwise hit on Homebrew Node installs, and keeps the global packages owned by the user who installed them.

The default OpenClaw state directory is ~/.openclaw/. The moment you run any command without --profile, state can land there and bleed across what you thought were isolated instances. Get in the habit from the first setup call:

openclaw --profile trucbot1 setup

Consider adding a shell alias on the server to make this automatic:

alias oc='openclaw --profile trucbot1'

The profile dir holds state; the working directory holds your stuff — skills, custom configs, scratch files. Don't run OpenClaw from ~/. Create something like ~/openclaw-work-trucbot1/ and live there. Keeps the agent's files separate from your personal home directory clutter.

The wizard will ask how to store the gateway token. On a personal Mac where the home directory is locked to your user, plaintext storage in openclaw.json is fine — same threat model as your API keys, which live there anyway.

Use SecretRef (Keychain-backed) on shared machines, Docker images, or anywhere multiple users have shell access.

The wizard will offer to set up Telegram, Discord, etc. If you don't have a token ready for one, skip it — don't paste a placeholder. You can add channels later with openclaw --profile <name> channels. Wizards that get half-configured channels are harder to debug than channels added cleanly after the fact.

Default policy is pairing, which means any Telegram user who discovers your bot can send pairing requests. Switch to allowlist immediately:

openclaw --profile trucbot1 config set channels.telegram.dmPolicy "allowlist"
openclaw --profile trucbot1 config set channels.telegram.allowFrom '["YOUR_USER_ID"]'

After this, only your Telegram account can DM the bot. Test by sending yourself a message — should work as before. If your config has stale pairing approvals from before the switch, they become inert under allowlist, but cleaning them up with openclaw --profile trucbot1 pairing is good hygiene.

From the same machine OpenClaw is running on:

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:18789/

Any HTTP response (200, 401, 404) confirms the gateway is alive. HTTP 000 or "connection refused" means the gateway isn't running — check openclaw --profile trucbot1 status.

Once the bot is talking on Telegram and the dashboard loads, back up ~/.openclaw-trucbot1/ to another machine via rsync or whatever your backup pattern is. Do it now — before you invest hours in skills, AGENTS.md, and session history that would be painful to recreate.

Note the profile name, gateway port, working directory path, and which credentials are in which password manager entry. Six months from now, when you stand up TrucBot2, you'll want to mirror the pattern — not reverse-engineer it from a running system.

A previous install had user truc with home /Users/ccornum. Tools that resolved identity via $USER and tools that resolved via $HOME disagreed silently. Over months, that drift caused the install to become unrecoverable. Fix: pick matching names from Day 1.

A global install at /usr/local/lib/node_modules owned by one user blocks all others from updating or installing without sudo. Per-user ~/.npm-global prefixes keep installs isolated and avoid permission battles.

A half-installed OpenClaw can leave a launchd agent that respawns processes after a rm -rf. If reinstalls fail mysteriously, check launchctl list | grep -i claw and unload anything that's still alive before retrying.

Reusing the same Telegram bot token across instances causes both to fight over getUpdates polling. Messages disappear, replies hit the wrong bot, debugging is nightmarish. Always generate a new bot per instance.