Skip to main content
The Operator configuration file lives at ~/.operator/config.json (or $OPERATOR_HOME/config.json if the environment variable is set). It is loaded once at startup; most fields can also be overridden at runtime via environment variables.
config.json
{
  "agents": {
    "defaults": {
      "workspace": "~/.operator/workspace",
      "restrict_to_workspace": true,
      "model_name": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-your-key"
    },
    {
      "model_name": "gemini",
      "model": "antigravity/gemini-2.0-flash",
      "auth_method": "oauth"
    },
    {
      "model_name": "loadbalanced-gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-key1",
      "api_base": "https://api1.example.com/v1"
    },
    {
      "model_name": "loadbalanced-gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-key2",
      "api_base": "https://api2.example.com/v1"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": false,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"],
      "reasoning_channel_id": ""
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "allow_from": [],
      "group_trigger": { "mention_only": false },
      "reasoning_channel_id": ""
    }
  },
  "tools": {
    "web": {
      "brave": { "enabled": false, "api_key": "YOUR_BRAVE_API_KEY", "max_results": 5 },
      "duckduckgo": { "enabled": true, "max_results": 5 },
      "perplexity": { "enabled": false, "api_key": "pplx-xxx", "max_results": 5 },
      "proxy": ""
    },
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": []
    },
    "cron": { "exec_timeout_minutes": 5 },
    "mcp": {
      "enabled": false,
      "servers": {
        "filesystem": {
          "enabled": false,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      }
    },
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai"
        }
      }
    }
  },
  "heartbeat": { "enabled": true, "interval": 30 },
  "devices": { "enabled": false, "monitor_usb": true },
  "gateway": { "host": "127.0.0.1", "port": 18790 }
}

agents

Global agent settings.
agents.defaults
object
Default parameters applied to every agent unless overridden at the agent level.
agents.list
object[]
Optional list of named agents with per-agent overrides. Each entry can override the model, workspace, and skills for a specific agent.

model_list

model_list is the recommended way to configure AI providers. The older providers top-level key is deprecated and will be removed in v2.0. If only providers is present, it is automatically migrated at startup.
An ordered array of model entries. Each entry defines an alias, a provider/model identifier, and credentials. Multiple entries with the same model_name enable automatic round-robin load balancing across them.
{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-your-key",
      "api_base": "https://api.openai.com/v1"
    }
  ]
}
model_list[].model_name
string
required
User-facing alias for this model entry. This is the value you set in agents.defaults.model_name. Must be non-empty. Duplicate values across entries are allowed and enable load balancing.
model_list[].model
string
required
Protocol-prefixed model identifier in the form protocol/model-id. The protocol determines which provider backend is used. If no prefix is given, openai is assumed.See the AI provider reference for the full list of supported protocols and example model IDs.
model_list[].api_key
string
API key for authenticating with the provider. Required for all HTTP-based providers unless api_base points to a local unauthenticated server.
model_list[].api_base
string
Override the provider’s default API endpoint URL. Use this to point at a self-hosted deployment, proxy, or alternative region. Each provider has a compiled-in default that applies when this field is omitted.
model_list[].auth_method
string
Authentication method. Set to "oauth" for providers that use OAuth-based login (e.g., antigravity, github-copilot). Omit for API-key–based providers.
model_list[].proxy
string
HTTP/HTTPS/SOCKS5 proxy URL to use for requests to this provider. Example: "http://proxy.corp.example.com:8080".
model_list[].connect_mode
string
Connection mode for CLI-based providers (claude-cli, codex-cli, github-copilot). Valid values: "stdio", "grpc". Defaults to "grpc" for GitHub Copilot.
model_list[].workspace
string
Workspace directory for CLI-based providers (claude-cli, codex-cli). Defaults to "." if not set.
model_list[].rpm
number
Requests-per-minute cap for this entry. When reached, Operator waits before sending the next request.
model_list[].max_tokens_field
string
Override the JSON field name used to pass max_tokens in the API request body. Some providers (e.g., newer OpenAI endpoints) require "max_completion_tokens" instead of "max_tokens".
model_list[].request_timeout
number
Per-request HTTP timeout in seconds. Values <= 0 fall back to the compiled default of 120 s.

Load balancing

Duplicate a model_name across multiple entries to distribute load via round-robin:
{
  "model_list": [
    { "model_name": "gpt4", "model": "openai/gpt-5.2", "api_key": "sk-key1", "api_base": "https://api1.example.com/v1" },
    { "model_name": "gpt4", "model": "openai/gpt-5.2", "api_key": "sk-key2", "api_base": "https://api2.example.com/v1" },
    { "model_name": "gpt4", "model": "openai/gpt-5.2", "api_key": "sk-key3", "api_base": "https://api3.example.com/v1" }
  ]
}
Every call to model gpt4 cycles through the three endpoints in sequence.

channels

Messaging platform integrations. All channels are disabled by default. Enable only the channels you need. Every channel config includes the following common fields:
FieldTypeDefaultDescription
enabledboolfalseEnable this channel.
allow_fromstring[][]Allowlist of user/account IDs. Empty means all authenticated users are allowed. Accepts both string and numeric IDs.
reasoning_channel_idstring""If set, internal reasoning/thinking output is forwarded to this channel or thread ID instead of the main conversation.

channels.telegram

channels.telegram.enabled
boolean
default:"false"
Enable the Telegram bot.
channels.telegram.token
string
Telegram Bot API token. Obtain from @BotFather.
channels.telegram.base_url
string
Custom Telegram Bot API base URL. Useful when running a local Bot API server.
channels.telegram.proxy
string
HTTP/SOCKS5 proxy for Telegram API requests.
channels.telegram.allow_from
string[]
default:"[]"
Allowlist of Telegram user IDs (numeric or string).
channels.telegram.group_trigger
object
Controls when the bot responds in group chats.
channels.telegram.typing
object
channels.telegram.placeholder
object
channels.telegram.reasoning_channel_id
string
Forward reasoning output to this chat ID.

channels.discord

channels.discord.enabled
boolean
default:"false"
Enable the Discord bot.
channels.discord.token
string
Discord bot token from the Discord Developer Portal.
channels.discord.proxy
string
HTTP/SOCKS5 proxy for Discord API requests.
channels.discord.allow_from
string[]
default:"[]"
Allowlist of Discord user IDs.
channels.discord.group_trigger
object
channels.discord.reasoning_channel_id
string
Channel ID for reasoning output.

channels.slack

channels.slack.enabled
boolean
default:"false"
Enable the Slack bot.
channels.slack.bot_token
string
Slack bot OAuth token (xoxb-…).
channels.slack.app_token
string
Slack app-level token for Socket Mode (xapp-…).
channels.slack.allow_from
string[]
default:"[]"
Allowlist of Slack user IDs.
channels.slack.group_trigger
object
channels.slack.reasoning_channel_id
string
Channel ID for reasoning output.

channels.whatsapp

channels.whatsapp.enabled
boolean
default:"false"
Enable the WhatsApp integration.
channels.whatsapp.bridge_url
string
default:"ws://localhost:3001"
WebSocket URL of the WhatsApp bridge server.
channels.whatsapp.use_native
boolean
default:"false"
Use native WhatsApp mode instead of a bridge.
channels.whatsapp.session_store_path
string
Path to store WhatsApp session data.
channels.whatsapp.allow_from
string[]
default:"[]"
Allowlist of WhatsApp phone numbers or JIDs.
channels.whatsapp.reasoning_channel_id
string
JID or chat ID for reasoning output.

channels.feishu

channels.feishu.enabled
boolean
default:"false"
Enable the Feishu/Lark bot.
channels.feishu.app_id
string
Feishu app ID.
channels.feishu.app_secret
string
Feishu app secret.
channels.feishu.encrypt_key
string
Feishu event encryption key.
channels.feishu.verification_token
string
Feishu webhook verification token.
channels.feishu.allow_from
string[]
default:"[]"
Allowlist of Feishu user open IDs.
channels.feishu.reasoning_channel_id
string
Chat ID for reasoning output.

channels.dingtalk

channels.dingtalk.enabled
boolean
default:"false"
Enable the DingTalk bot.
channels.dingtalk.client_id
string
DingTalk app client ID.
channels.dingtalk.client_secret
string
DingTalk app client secret.
channels.dingtalk.allow_from
string[]
default:"[]"
Allowlist of DingTalk user IDs.
channels.dingtalk.reasoning_channel_id
string
Chat ID for reasoning output.

channels.qq

channels.qq.enabled
boolean
default:"false"
Enable the QQ bot.
channels.qq.app_id
string
QQ app ID.
channels.qq.app_secret
string
QQ app secret.
channels.qq.allow_from
string[]
default:"[]"
Allowlist of QQ user IDs.
channels.qq.reasoning_channel_id
string
Chat ID for reasoning output.

channels.line

channels.line.enabled
boolean
default:"false"
Enable the LINE bot.
channels.line.channel_secret
string
LINE channel secret.
channels.line.channel_access_token
string
LINE channel access token.
channels.line.webhook_path
string
default:"/webhook/line"
Webhook path for LINE events.
channels.line.allow_from
string[]
default:"[]"
Allowlist of LINE user IDs.
channels.line.reasoning_channel_id
string
Chat ID for reasoning output.

channels.onebot

channels.onebot.enabled
boolean
default:"false"
Enable the OneBot v11 adapter (QQ via go-cqhttp or similar).
channels.onebot.ws_url
string
default:"ws://127.0.0.1:3001"
WebSocket URL of the OneBot v11 server.
channels.onebot.access_token
string
Access token for the OneBot server.
channels.onebot.reconnect_interval
number
default:"5"
Reconnection interval in seconds when the WebSocket connection drops.
channels.onebot.group_trigger
object
channels.onebot.allow_from
string[]
default:"[]"
Allowlist of QQ user IDs.
channels.onebot.reasoning_channel_id
string
Group or user ID for reasoning output.

channels.maixcam

channels.maixcam.enabled
boolean
default:"false"
Enable the MaixCam hardware channel.
channels.maixcam.host
string
default:"0.0.0.0"
Bind address for the MaixCam listener.
channels.maixcam.port
number
default:"18790"
Port for the MaixCam listener.
channels.maixcam.allow_from
string[]
default:"[]"
Allowlist of device IDs.
channels.maixcam.reasoning_channel_id
string
Channel ID for reasoning output.

channels.wecom

WeCom Bot — easier setup, supports group chats via webhook.
channels.wecom.enabled
boolean
default:"false"
Enable the WeCom bot channel.
channels.wecom.token
string
WeCom verification token.
channels.wecom.encoding_aes_key
string
43-character AES encoding key for message encryption.
channels.wecom.webhook_url
string
WeCom group robot webhook URL.
channels.wecom.webhook_path
string
default:"/webhook/wecom"
Incoming webhook path.
channels.wecom.allow_from
string[]
default:"[]"
Allowlist of WeCom user IDs.
channels.wecom.reply_timeout
number
default:"5"
Reply timeout in seconds.
channels.wecom.reasoning_channel_id
string
Chat ID for reasoning output.

channels.wecom_app

WeCom self-built application — more features, proactive messaging, private chats only.
channels.wecom_app.enabled
boolean
default:"false"
Enable the WeCom App channel.
channels.wecom_app.corp_id
string
WeCom corporation ID.
channels.wecom_app.corp_secret
string
WeCom application secret.
channels.wecom_app.agent_id
number
WeCom application agent ID.
channels.wecom_app.token
string
WeCom verification token.
channels.wecom_app.encoding_aes_key
string
43-character AES encoding key.
channels.wecom_app.webhook_path
string
default:"/webhook/wecom-app"
Incoming webhook path.
channels.wecom_app.allow_from
string[]
default:"[]"
Allowlist of WeCom user IDs.
channels.wecom_app.reply_timeout
number
default:"5"
Reply timeout in seconds.
channels.wecom_app.reasoning_channel_id
string
Chat ID for reasoning output.

channels.wecom_aibot

WeCom AI Bot (智能机器人) — official WeCom AI Bot integration with proactive messaging.
channels.wecom_aibot.enabled
boolean
default:"false"
Enable the WeCom AI Bot channel.
channels.wecom_aibot.token
string
WeCom verification token.
channels.wecom_aibot.encoding_aes_key
string
43-character AES encoding key.
channels.wecom_aibot.webhook_path
string
default:"/webhook/wecom-aibot"
Incoming webhook path.
channels.wecom_aibot.max_steps
number
default:"10"
Maximum streaming steps per response.
channels.wecom_aibot.welcome_message
string
Message sent automatically when a user opens a chat. Set to "" to disable.
channels.wecom_aibot.allow_from
string[]
default:"[]"
Allowlist of WeCom user IDs.
channels.wecom_aibot.reasoning_channel_id
string
Chat ID for reasoning output.

channels.standard

HTTP/WebSocket standard channel for custom integrations.
channels.standard.enabled
boolean
default:"false"
Enable the standard WebSocket channel.
channels.standard.token
string
Bearer token for authenticating incoming connections.
channels.standard.allow_origins
string[]
CORS allowed origins.
channels.standard.ping_interval
number
default:"30"
WebSocket ping interval in seconds.
channels.standard.read_timeout
number
default:"60"
Read timeout in seconds.
channels.standard.write_timeout
number
default:"10"
Write timeout in seconds.
channels.standard.max_connections
number
default:"100"
Maximum simultaneous WebSocket connections.
channels.standard.allow_from
string[]
default:"[]"
Allowlist of client IDs.

tools

tools.allow_read_paths
string[]
Additional filesystem paths the agent is permitted to read from, even when restrict_to_workspace is true.
tools.allow_write_paths
string[]
Additional filesystem paths the agent is permitted to write to, even when restrict_to_workspace is true.

tools.web

Controls web search and fetch capabilities.
tools.web.proxy
string
HTTP/HTTPS/SOCKS5 proxy URL for all web tool requests. For proxies that require credentials, use the HTTP_PROXY/HTTPS_PROXY environment variables instead of embedding credentials here.
tools.web.fetch_limit_bytes
number
default:"10485760"
Maximum number of bytes to fetch from a single URL. Default is 10 MB.
tools.web.brave
object
Brave Search integration.
tools.web.duckduckgo
object
DuckDuckGo search (no API key required).
tools.web.perplexity
object
Perplexity AI search integration.
tools.web.tavily
object
Tavily search integration.

tools.exec

Controls shell command execution safety.
tools.exec.enable_deny_patterns
boolean
default:"true"
When true, a built-in set of dangerous command patterns is blocked before execution. Set to false to disable all built-in blocking (not recommended in production).Blocked by default: rm -rf, format, mkfs, dd if=, shutdown, reboot, pkill, killall, sudo, chmod, chown, curl | sh, wget | sh, docker run, docker exec, git push --force, eval, and others.
tools.exec.custom_deny_patterns
string[]
default:"[]"
Additional regular expressions to block. Commands matching any pattern are rejected. Patterns follow Go regexp syntax.
{
  "custom_deny_patterns": ["\\brm\\s+-r\\b", "\\bkillall\\s+python"]
}
tools.exec.custom_allow_patterns
string[]
default:"[]"
Regular expressions for commands that are explicitly allowed, overriding any matching deny patterns.

tools.cron

tools.cron.exec_timeout_minutes
number
default:"5"
Maximum execution time in minutes for cron-triggered commands. Set to 0 for no timeout.

tools.mcp

Model Context Protocol server integration. MCP extends the agent with tools from external servers.
tools.mcp.enabled
boolean
default:"false"
Global toggle for all MCP server connections. Must be true for any server to connect.
tools.mcp.servers
object
Map of server names to server configuration objects. Server names are used only for identification in logs.Stdio example:
{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      }
    }
  }
}
Remote SSE/HTTP example:
{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "context7": {
          "enabled": true,
          "type": "http",
          "url": "https://mcp.context7.com/mcp",
          "headers": { "CONTEXT7_API_KEY": "ctx7sk-xx" }
        }
      }
    }
  }
}
MCP server configuration (tools.mcp.servers.*) cannot be set via environment variables. Use config.json for all server definitions.

tools.skills

Skill discovery and installation via registries.
tools.skills.registries.clawhub
object
ClawHub skill registry configuration.
tools.skills.max_concurrent_searches
number
default:"2"
Maximum number of simultaneous registry search requests.
tools.skills.search_cache
object
In-memory search result cache settings.

tools.media_cleanup

Automatic cleanup of temporary media files.
tools.media_cleanup.enabled
boolean
default:"true"
Enable automatic media file cleanup.
tools.media_cleanup.max_age_minutes
number
default:"30"
Files older than this are eligible for removal.
tools.media_cleanup.interval_minutes
number
default:"5"
How often the cleanup job runs.

heartbeat

heartbeat.enabled
boolean
default:"true"
Send periodic heartbeat pings to the Operator cloud service for uptime monitoring and remote management. Disable if running in an air-gapped environment.
heartbeat.interval
number
default:"30"
Heartbeat interval in minutes. Minimum effective value is 5.

devices

devices.enabled
boolean
default:"false"
Enable device monitoring capabilities (currently USB device detection).
devices.monitor_usb
boolean
default:"true"
Monitor USB device plug/unplug events when devices.enabled is true.

gateway

The local HTTP/WebSocket gateway that exposes the Operator API on the local machine.
gateway.host
string
default:"127.0.0.1"
Bind address for the gateway listener. Change to "0.0.0.0" to accept connections from the network.
gateway.port
number
default:"18790"
TCP port for the gateway listener.

Deprecated: providers

The top-level providers key is deprecated as of v1.x and will be removed in v2.0. Migrate to model_list instead. See the migration guide for details.If model_list is empty and providers is present, Operator performs an automatic in-memory migration at startup.
The legacy format configured providers globally rather than per-model:
{
  "providers": {
    "openai": { "api_key": "sk-...", "api_base": "https://api.openai.com/v1" },
    "anthropic": { "api_key": "sk-ant-..." }
  },
  "agents": {
    "defaults": { "provider": "openai", "model": "gpt-5.2" }
  }
}

Build docs developers (and LLMs) love