Skip to main content

​
Configuration

SimpleClaw stores configuration in ~/.simpleclaw/config.yaml (or ~/.openclaw/config.yaml for compatibility). The config file uses YAML format with environment variable substitution and file includes.

​
Config File Location

The default config path is: 
~/.simpleclaw/config.yaml
You can override this with the SIMPLECLAW_CONFIG environment variable.

​
Basic Structure

A minimal config file: 
gateway:
  mode: local
  bind: loopback
  port: 18789

models:
  - id: anthropic-claude
    provider: anthropic
    model: claude-3-5-sonnet-20241022
    apiKey: ${ANTHROPIC_API_KEY}

channels:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}
    dmPolicy: pairing
Environment variables are expanded using ${VAR_NAME} syntax.

​
Gateway Configuration

The gateway section controls the WebSocket server:
​
mode
string
default:"local"
Gateway mode: local or remote
​
bind
string
default:"loopback"
Bind address: loopback (127.0.0.1) or all (0.0.0.0)
​
port
number
default:"18789"
WebSocket server port
​
auth.mode
string
default:"none"
Authentication mode: none, password, or token
​
auth.password
string
Password for password auth mode
​
tailscale.mode
string
default:"off"
Tailscale exposure: off, serve (tailnet-only), or funnel (public)

​
Example: Remote Gateway with Password Auth

gateway:
  mode: remote
  bind: loopback  # Tailscale will expose it
  port: 18789
  auth:
    mode: password
    password: ${GATEWAY_PASSWORD}
  tailscale:
    mode: funnel
    resetOnExit: true
When using tailscale.mode: funnel (public HTTPS), you must set auth.mode: password. SimpleClaw enforces this for security.

​
Model Configuration

The models array defines LLM providers: 
models:
  - id: anthropic-main
    provider: anthropic
    model: claude-3-5-sonnet-20241022
    apiKey: ${ANTHROPIC_API_KEY}
    
  - id: openai-gpt4
    provider: openai
    model: gpt-4-turbo
    apiKey: ${OPENAI_API_KEY}
    
  - id: bedrock-claude
    provider: bedrock
    model: anthropic.claude-3-sonnet-20240229-v1:0
    region: us-east-1
​
id
string
required
Unique identifier for this model configuration
​
provider
string
required
Provider name: anthropic, openai, google, bedrock, etc.
​
model
string
required
Model identifier (provider-specific)
​
apiKey
string
API key for authentication (use ${VAR} for env vars)
​
region
string
AWS region (for Bedrock provider)
See Core Concepts: Models for details on model configuration, failover, and authentication modes.

​
Channel Configuration

The channels object configures messaging platforms: 
channels:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}
    dmPolicy: pairing
    allowFrom:
      - "123456789"  # Specific user ID
      
  discord:
    enabled: true
    token: ${DISCORD_BOT_TOKEN}
    dmPolicy: pairing
    guilds:
      - id: "987654321"
        allowFrom:
          - "*"  # All guild members
          
  whatsapp:
    enabled: true
    dmPolicy: pairing

​
Common Channel Options

​
enabled
boolean
default:"false"
Enable or disable this channel
​
token
string
Bot token (for Telegram, Discord, Slack)
​
dmPolicy
string
default:"pairing"
DM access policy: open or pairing
​
allowFrom
array
List of allowed user IDs or ["*"] for all
Default DM policy is pairing for security. Unknown senders get a pairing code. Approve with simpleclaw pairing approve <channel> <code>.
See the Channels Guide for channel-specific configuration.

​
Routing Configuration

Route messages to specific agents based on channel, account, or peer: 
routing:
  bindings:
    - agent: work-agent
      channels:
        - telegram:account1
      
    - agent: personal-agent
      channels:
        - discord
        - whatsapp
​
agent
string
required
Target agent ID
​
channels
array
List of channel matchers: <channel>, <channel>:<account>, or <channel>:<account>:<peer>
See Core Concepts: Routing for routing precedence and session keys.

​
Agent Configuration

Define multiple agents with isolated workspaces: 
agents:
  - id: main
    workspace: ~/.simpleclaw/agents/main
    model: anthropic-main
    
  - id: work-agent
    workspace: ~/.simpleclaw/agents/work
    model: openai-gpt4
​
id
string
required
Unique agent identifier
​
workspace
string
Workspace directory for this agent
​
model
string
Default model ID for this agent
See Core Concepts: Agents for agent management and configuration.

​
Using the CLI

Manage configuration via the CLI:

​
View current config

simpleclaw config get

​
Set a value

simpleclaw config set gateway.port 8080

​
Get a specific value

simpleclaw config get channels.telegram.enabled

​
Validate config

simpleclaw doctor
The doctor command checks for:
  • Invalid configuration
  • Missing API keys
  • Risky DM policies
  • Permission issues
  • Port conflicts

​
Environment Variables

Common environment variables:
VariableDescription
ANTHROPIC_API_KEYAnthropic API key
OPENAI_API_KEYOpenAI API key
TELEGRAM_BOT_TOKENTelegram bot token
DISCORD_BOT_TOKENDiscord bot token
SLACK_BOT_TOKENSlack bot token
GATEWAY_PASSWORDGateway password auth
SIMPLECLAW_CONFIGOverride config file path
Store sensitive values in environment variables and reference them in config: 
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
Create a .env file or add to ~/.profile for persistent environment variables.

​
File Includes

Split large configs into multiple files: 
gateway:
  mode: local
  
include:
  - channels.yaml
  - models.yaml
  - routing.yaml
Then in channels.yaml: 
channels:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}

​
Config Schema Validation

SimpleClaw validates configuration against a Zod schema. Invalid configs will fail with detailed error messages. Run validation: 
simpleclaw config validate

​
Next Steps

Add Channels

Connect WhatsApp, Telegram, Discord, and more

Configure Routing

Route messages to different agents

Model Setup

Configure LLM providers and failover

Security

Set up DM pairing and allowlists

Build docs developers (and LLMs) love

Get started for freeTalk to us