openclaw-credentials

name	openclaw-credentials
description	Guides the user through setting up API keys, model authentication, and messaging channel credentials for OpenClaw. Covers OAuth, API key rotation, model failover, and per-channel auth. Activate when the user says: "OpenClaw API key", "OpenClaw authentication", "connect OpenClaw to WhatsApp", "OpenClaw Telegram setup", "OpenClaw Slack token", "OpenClaw Discord bot", "openclaw model auth", "openclaw credentials", "openclaw OAuth", "openclaw channel token", "set up OpenClaw channels".
version	1.0.0

OpenClaw Credentials & Authentication

OpenClaw requires two types of credentials:

1. AI model credentials — API keys or OAuth tokens for the AI provider (e.g., Anthropic, OpenAI)
2. Channel credentials — Tokens and app registrations for each messaging channel

Configure both via the onboarding wizard or by editing config files directly.

AI Model Credentials

Run the onboarding wizard to configure the model interactively:

openclaw onboard

OpenClaw recommends using the latest-generation model available for best performance and security.

Reuse Claude Code API Key

If the user already has Claude Code installed, their Anthropic API key is stored in ~/.claude.json under the primaryApiKey field. Offer to read and reuse it automatically:

1. Read ~/.claude.json via Bash and extract primaryApiKey:

   node -e "const f=require('fs');const d=JSON.parse(f.readFileSync(require('os').homedir()+'/.claude.json','utf8'));console.log(d.primaryApiKey||'')"
   

2. If a key is found, ask (Yes/No): "Found your Claude Code API key (sk-ant-...xxxx). Use this for OpenClaw?"
   • Yes → set it for OpenClaw automatically:

     openclaw onboard --anthropic-key <key>
     

     Or export it for the current session and run onboard:

     export ANTHROPIC_API_KEY=<key> && openclaw onboard
     

   • No → fall back to manual API key entry below.
3. If no key is found in ~/.claude.json, skip this option and proceed to manual entry.

API Key Auth

Set the provider API key in config or environment:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

Or configure via the onboarding wizard which stores keys in ~/.openclaw/.

OAuth Auth

OAuth is supported for providers that offer it. Configure via the onboarding wizard — it handles the OAuth flow automatically.

Model Failover

Configure multiple model profiles with fallback:

• Primary model attempts first
• Falls back to secondary on rate limits or errors
• Supports mixing OAuth and API key profiles

See: https://docs.openclaw.ai/concepts/model-failover

Channel Credentials

Each channel requires its own credentials. Use openclaw onboard to walk through setup for each channel, or configure manually.

WhatsApp (Baileys)

WhatsApp uses QR code pairing — no bot account needed:

1. Run openclaw onboard and select WhatsApp
2. Scan the QR code with your WhatsApp mobile app
3. Session is saved to ~/.openclaw/

No API key required. Works with personal WhatsApp accounts.

Telegram (grammY)

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts to get a bot token
3. Add the token during openclaw onboard or in config:

{
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

Slack (Bolt)

1. Create a Slack app at https://api.slack.com/apps
2. Enable Socket Mode and generate an App-Level Token (xapp-...)
3. Add Bot Token Scopes: chat:write, im:history, im:read, app_mentions:read
4. Install to workspace to get Bot Token (xoxb-...)
5. Add both tokens during openclaw onboard:

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-..."
    }
  }
}

Discord (discord.js)

1. Create a bot at https://discord.com/developers/applications
2. Under "Bot", enable Message Content Intent and Server Members Intent
3. Generate a bot token
4. Invite the bot to your server with the OAuth2 URL Generator (scopes: bot, permissions: Send Messages, Read Message History)
5. Add the token during openclaw onboard:

{
  "channels": {
    "discord": {
      "token": "YOUR_BOT_TOKEN"
    }
  }
}

Signal (signal-cli)

1. Install signal-cli: https://github.com/AsamK/signal-cli
2. Register a phone number with Signal
3. Link to OpenClaw during onboarding

iMessage (BlueBubbles)

Requires macOS with iMessage enabled:

1. Install BlueBubbles server on macOS: https://bluebubbles.app
2. Obtain the BlueBubbles server URL and password
3. Configure during openclaw onboard

Microsoft Teams

Requires a Microsoft 365 developer account or org admin access to register a bot application in Azure.

Other Channels

OpenClaw supports: Google Chat, IRC, Matrix, Feishu, LINE, Mattermost, Nextcloud Talk, Nostr, Synology Chat, Tlon, Twitch, Zalo, WebChat.

Each channel's setup instructions are covered in the onboarding wizard. Run:

openclaw onboard

Pairing & DM Security

After channel setup, unknown senders get a pairing code by default:

openclaw pairing approve <channel> <pairing-code>

Check for risky auth configurations:

openclaw doctor

Rotating Credentials

To rotate an API key or channel token:

1. Update the key in your provider's dashboard (or re-read from ~/.claude.json primaryApiKey if using Claude Code)
2. Edit the value in ~/.openclaw/ config or re-run openclaw onboard
3. Restart the gateway: openclaw gateway --restart
4. Verify: openclaw doctor

References

• Onboarding: https://docs.openclaw.ai/start/onboarding
• Model failover: https://docs.openclaw.ai/concepts/model-failover
• Security: https://docs.openclaw.ai/gateway/security
• Channel docs: https://docs.openclaw.ai