Configuration

Set up OpenClaw configuration file with API keys, Telegram bot, and ArmorIQ plugin settings.

Configuration File

OpenClaw uses a JSON configuration file located at:

~/.openclaw/openclaw.json

This file contains all settings for:

LLM providers (OpenAI, Gemini)
Channels (Telegram, Slack)
Plugins (ArmorIQ)
Tools (web search)

Configuration Steps

Create Configuration Directory

mkdir -p ~/.openclaw

Check if config already exists:

ls ~/.openclaw/openclaw.json

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"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "open",
      "botToken": "YOUR_BOT_TOKEN",
      "allowFrom": ["*"],
      "groupPolicy": "allowlist",
      "streamMode": "partial"
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "token": "armoriq-local-dev"
    }
  },
  "plugins": {
    "enabled": true,
    "entries": {
      "armoriq": {
        "enabled": true,
        "policyUpdateEnabled": true,
        "policyUpdateAllowList": [
          "YOUR_TELEGRAM_USER_ID",
          "@YOUR_TELEGRAM_USERNAME"
        ],
        "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"
        }
      },
      "telegram": {
        "enabled": true
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "provider": "perplexity",
        "maxResults": 5,
        "perplexity": {
          "baseUrl": "https://openrouter.ai/api/v1"
        }
      }
    }
  }
}

Replace placeholders:

YOUR_USERNAME - your system username
YOUR_BOT_TOKEN - Telegram bot token
YOUR_TELEGRAM_USER_ID - your Telegram user ID
YOUR_TELEGRAM_USERNAME - your Telegram username
YOUR_ARMORIQ_API_KEY - ArmorIQ API key

Configure API Keys

Get your API keys and set environment variables:

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

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): If neither Brave Search nor Perplexity are available, you can use OpenRouter:

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

Get key from OpenRouter.

Setup Telegram Bot

Create Bot

Open Telegram and message @BotFather
Send /newbot
Set bot name (e.g., "My OpenClaw Bot")
Set username (e.g., "my_openclaw_bot")
Copy the bot token: 1234567890:ABCdef...

Add Token to Config

Update ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "open",
      "botToken": "1234567890:ABCdef...",
      "allowFrom": ["*"]
    }
  }
}

Get Your Telegram User ID

Message @userinfobot
Send /start
Bot replies with your user ID (e.g., 6193457473)

Start gateway (covered later)
Send any message to your bot

Check logs:

grep senderId /tmp/openclaw/openclaw-*.log
# Look for: senderId=6193457473

Configure ArmorIQ

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",
          "your_username",
          "telegram:YOUR_USER_ID"
        ],
        "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`	Telegram user IDs/usernames who can manage policies
`apiKey`	Your ArmorIQ API key
`userId`	Unique user identifier for this context
`agentId`	Unique agent identifier
`endpoints`	Production ArmorIQ service URLs (do not change)

Policy Allowlist Format: Include multiple formats for reliability:

Numeric ID: "6193457473"
Username with @: "@your_username"
Username without @: "your_username"
Prefixed: "telegram:6193457473"

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

# 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_..."

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

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

Telegram bot not responding

Verify bot token is correct
Check "enabled": true for telegram channel
Ensure bot token has no extra spaces
Start a fresh chat with the bot

Configuration Checklist

Before proceeding, verify:

~/.openclaw/openclaw.json created
JSON syntax valid (jq passes)
API keys set in environment or config
Telegram bot created and token added
Your Telegram user ID in policyUpdateAllowList
ArmorIQ API key configured
ArmorIQ endpoints point to production
Workspace path exists

Next Steps

✅ Configuration complete!

Proceed to Plugin Setup to enable ArmorIQ and test the integration.

Configuration

On this page