Configuration

Set up OpenClaw with API keys, messaging channels, and ArmorIQ security plugin.

Configuration File

OpenClaw uses a JSON configuration file located at:

~/.openclaw/openclaw.json

This file contains all settings for:

• LLM providers (OpenAI, Gemini)
• Messaging channels (Telegram, Slack, Discord, WhatsApp)
• Plugins (ArmorIQ security)
• Tools (web search, file operations)

Quick Start

mkdir -p ~/.openclaw

{
  "auth": {
    "profiles": {
      "openai:default": {
        "provider": "openai",
        "mode": "api_key"
      }
    },
    "order": {
      "openai": ["openai:default"]
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-4-turbo"
      },
      "workspace": "/home/YOUR_USERNAME/.openclaw/workspace",
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "token": "armoriq-local-dev"
    }
  },
  "plugins": {
    "enabled": true,
    "entries": {
      "armoriq": {
        "enabled": true,
        "policyUpdateEnabled": true,
        "policyUpdateAllowList": [],
        "userId": "you@example.com",
        "agentId": "openclaw-agent-001",
        "contextId": "default"
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "provider": "perplexity",
        "maxResults": 5,
        "perplexity": {
          "baseUrl": "https://openrouter.ai/api/v1"
        }
      }
    }
  }
}

API Keys Configuration

OpenAI API Key

1. Get key from OpenAI Platform
2. Set environment variable:

# Add to ~/.bashrc
export OPENAI_API_KEY="sk-proj-..."
source ~/.bashrc

# Add to ~/.config/fish/config.fish
set -gx OPENAI_API_KEY "sk-proj-..."
source ~/.config/fish/config.fish

# Create ~/.openclaw/.env
echo 'OPENAI_API_KEY=sk-proj-...' >> ~/.openclaw/.env

Alternative: Gemini API Key

To use Google Gemini instead:

1. Get key from Google AI Studio
2. Set environment:

   export GEMINI_API_KEY="AIzaSy..."

3. Update config model:

   {
     "agents": {
       "defaults": {
         "model": {
           "primary": "google/gemini-2.0-flash-exp"
         }
       }
     }
   }

Web Search API Key

OpenClaw officially supports Brave Search and Perplexity for web search:

Brave Search (Recommended):

export BRAVE_SEARCH_API_KEY="your-brave-api-key"

Get key from Brave Search API.

Perplexity:

export PERPLEXITY_API_KEY="your-perplexity-key"

Get key from Perplexity.

OpenRouter (Fallback):

export OPENROUTER_API_KEY="sk-or-v1-..."

Get key from OpenRouter.

ArmorIQ Configuration

Connect to ArmorIQ

The installer signs you in with a browser approval and stores the key for you, so there is normally nothing to copy or paste:

1. It opens platform.armoriq.ai/auth/device and shows a code
2. You confirm the code matches and approve
3. The backend mints the key and it is saved to ~/.armoriq/credentials.json with 0600 permissions

To connect later, or to switch accounts, use the CLI:

armoriq login      # browser approval, same as the installer
armoriq whoami     # show the signed-in account and key
armoriq logout     # clear local credentials

The plugin resolves the key in this order: the apiKey config value, then ARMORIQ_API_KEY, then ~/.armoriq/credentials.json. Setting apiKey in config is an override, not the normal path.

If you would rather create a key by hand, the API Keys page is at tools.armoriq.ai.

Update Plugin Config

Edit the armoriq section in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "armoriq": {
        "enabled": true,
        "policyUpdateEnabled": true,
        "policyUpdateAllowList": [
          "YOUR_USER_ID",
          "@your_username"
        ],
        "userId": "you@example.com",
        "agentId": "openclaw-agent-001",
        "contextId": "default"
      }
    }
  }
}

Key fields:

Endpoints are deliberately absent. The plugin derives them from ARMORIQ_ENV (production unless set), so there is nothing to configure and nothing to go stale when a service moves. Set iapEndpoint / backendEndpoint / proxyEndpoint only when pointing at a staging or local stack.

Observability

ArmorClaw reports each turn to the dashboard: the intent plan, every tool decision, and whether the turn completed. It is on by default and fails open, so a reporting problem can never block a tool call.

Turn it off with either:

{ "observabilityEnabled": false }

export ARMORIQ_OBSERVABILITY_DISABLED=true

Reporting is skipped automatically when there is no API key, since nothing could be attributed to an account.

Environment Variables

Create ~/.openclaw/.env for sensitive data:

# OpenAI
OPENAI_API_KEY=sk-proj-...

# Gemini (if using)
GEMINI_API_KEY=AIzaSy...

# OpenRouter (for web search)
OPENROUTER_API_KEY=sk-or-v1-...

# Slack (if using)
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# Discord (if using)
DISCORD_BOT_TOKEN=MTQ3...

# ArmorIQ
# Nothing required here. The key comes from ~/.armoriq/credentials.json and
# endpoints are derived from ARMORIQ_ENV. Set ARMORIQ_API_KEY only to override
# the signed-in key.

Load Environment

# Add to ~/.config/fish/config.fish
set -gx OPENAI_API_KEY "sk-proj-..."
set -gx ARMORIQ_API_KEY "ak_live_..."
set -gx SLACK_BOT_TOKEN "xoxb-..."
set -gx SLACK_APP_TOKEN "xapp-..."
set -gx DISCORD_BOT_TOKEN "MTQ3..."

# Add to ~/.bashrc
export OPENAI_API_KEY="sk-proj-..."
export ARMORIQ_API_KEY="ak_live_..."
export SLACK_BOT_TOKEN="xoxb-..."
export SLACK_APP_TOKEN="xapp-..."
export DISCORD_BOT_TOKEN="MTQ7..."

Messaging Channels

Choose one or more messaging platforms to interact with OpenClaw:

Each channel has its own detailed setup guide. Click to configure your preferred platform(s).

Validate Configuration

Check JSON Syntax

cat ~/.openclaw/openclaw.json | jq .

Should output formatted JSON without errors.

Test API Keys

# Test OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | jq .

# Test ArmorIQ
curl https://api.armoriq.ai/health \
  -H "Authorization: Bearer $ARMORIQ_API_KEY"

Configuration Locations

Common Issues

Invalid JSON syntax

Validate with jq:

cat ~/.openclaw/openclaw.json | jq .

Fix any syntax errors (missing commas, quotes, etc.).

API key not working

• Verify key is not expired
• Check for extra spaces or line breaks
• Ensure correct prefix (sk-proj-, ak_live_, etc.)

Channel not starting

• Verify channel is enabled in config
• Check required tokens are set in environment
• Review channel-specific setup guide
• Check logs for errors: tail -f /tmp/openclaw/openclaw-*.log

Configuration Checklist

Before proceeding, verify:

• ~/.openclaw/openclaw.json created
• JSON syntax valid (jq passes)
• OpenAI or Gemini API key configured
• ArmorIQ API key configured
• ArmorIQ endpoints point to production
• Workspace path exists
• At least one messaging channel configured
• Environment variables loaded

Next Steps

Basic configuration complete!

Configure a messaging channel:

• Telegram Setup - Quickest to set up
• Slack Setup - Best for teams
• Discord Setup - Great for communities
• WhatsApp Setup - No API keys needed

Then proceed to:

• Quick Start Guide - Install, enable security features, run the gateway, and test your bot
• Core Concepts - Understand the intent-verification flow