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

Create Configuration Directory

mkdir -p ~/.openclaw

Create Base Configuration

Create ~/.openclaw/openclaw.json with this template:

~/.openclaw/openclaw.json

{
  "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": [],
        "apiKey": "YOUR_ARMORIQ_API_KEY",
        "userId": "test-user-001",
        "agentId": "openclaw-agent-001",
        "contextId": "default",
        "endpoints": {
          "iap": "https://customer-iap.armoriq.ai",
          "backend": "https://customer-api.armoriq.ai"
        }
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "provider": "perplexity",
        "maxResults": 5,
        "perplexity": {
          "baseUrl": "https://openrouter.ai/api/v1"
        }
      }
    }
  }
}

Replace YOUR_USERNAME and YOUR_ARMORIQ_API_KEY with your actual values.

API Keys Configuration

OpenAI API Key

Get key from OpenAI Platform
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:

Get key from Google AI Studio
Set environment:
```
export GEMINI_API_KEY="AIzaSy..."
```

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

Get API Key

Sign up at ArmorIQ Dashboard
Navigate to API Keys
Copy your key: ak_live_...

Update Plugin Config

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

{
  "plugins": {
    "entries": {
      "armoriq": {
        "enabled": true,
        "policyUpdateEnabled": true,
        "policyUpdateAllowList": [
          "YOUR_USER_ID",
          "@your_username"
        ],
        "apiKey": "ak_live_...",
        "userId": "test-user-001",
        "agentId": "openclaw-agent-001",
        "contextId": "default",
        "endpoints": {
          "iap": "https://customer-iap.armoriq.ai",
          "backend": "https://customer-api.armoriq.ai"
        }
      }
    }
  }
}

Key fields:

Field	Description
`policyUpdateEnabled`	Allow policy management commands
`policyUpdateAllowList`	User IDs/usernames who can manage policies
`apiKey`	Your ArmorIQ API key
`userId`	Unique user identifier
`agentId`	Unique agent identifier
`endpoints`	Production ArmorIQ service URLs

Environment Variables

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

~/.openclaw/.env

# 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
ARMORIQ_API_KEY=ak_live_...
ARMORIQ_USER_ID=test-user-001
ARMORIQ_AGENT_ID=openclaw-agent-001

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:

Easy setup with BotFather. Supports streaming responses.

Slack

Socket Mode - no webhooks needed. Perfect for teams.

Discord

Bot API with intents. Great for community servers.

QR code login. No business account required.

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://customer-api.armoriq.ai/health \
  -H "Authorization: Bearer $ARMORIQ_API_KEY"

Configuration Locations

File	Purpose
`~/.openclaw/openclaw.json`	Main configuration
`~/.openclaw/.env`	Environment variables
`~/.openclaw/workspace/`	Agent workspace
`~/.openclaw/credentials/`	Channel credentials
`/tmp/openclaw/openclaw-*.log`	Gateway logs
`./armoriq.policy.json`	Policy store (in project root)

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:

ArmorIQ Plugin Setup - Enable security features
Running & Testing - Start the gateway

Overview