~/.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.
Full example config.json
Full example config.json
config.json
agents
Global agent settings.
Default parameters applied to every agent unless overridden at the agent level.
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.model_name enable automatic round-robin load balancing across them.
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.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.API key for authenticating with the provider. Required for all HTTP-based providers unless
api_base points to a local unauthenticated server.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.
Authentication method. Set to
"oauth" for providers that use OAuth-based login (e.g., antigravity, github-copilot). Omit for API-key–based providers.HTTP/HTTPS/SOCKS5 proxy URL to use for requests to this provider. Example:
"http://proxy.corp.example.com:8080".Connection mode for CLI-based providers (
claude-cli, codex-cli, github-copilot). Valid values: "stdio", "grpc". Defaults to "grpc" for GitHub Copilot.Workspace directory for CLI-based providers (
claude-cli, codex-cli). Defaults to "." if not set.Requests-per-minute cap for this entry. When reached, Operator waits before sending the next request.
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".Per-request HTTP timeout in seconds. Values
<= 0 fall back to the compiled default of 120 s.Load balancing
Duplicate amodel_name across multiple entries to distribute load via round-robin:
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:
| Field | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Enable this channel. |
allow_from | string[] | [] | Allowlist of user/account IDs. Empty means all authenticated users are allowed. Accepts both string and numeric IDs. |
reasoning_channel_id | string | "" | If set, internal reasoning/thinking output is forwarded to this channel or thread ID instead of the main conversation. |
channels.telegram
Enable the Telegram bot.
Telegram Bot API token. Obtain from @BotFather.
Custom Telegram Bot API base URL. Useful when running a local Bot API server.
HTTP/SOCKS5 proxy for Telegram API requests.
Allowlist of Telegram user IDs (numeric or string).
Controls when the bot responds in group chats.
Forward reasoning output to this chat ID.
channels.discord
Enable the Discord bot.
Discord bot token from the Discord Developer Portal.
HTTP/SOCKS5 proxy for Discord API requests.
Allowlist of Discord user IDs.
Channel ID for reasoning output.
channels.slack
Enable the Slack bot.
Slack bot OAuth token (
xoxb-…).Slack app-level token for Socket Mode (
xapp-…).Allowlist of Slack user IDs.
Channel ID for reasoning output.
channels.whatsapp
Enable the WhatsApp integration.
WebSocket URL of the WhatsApp bridge server.
Use native WhatsApp mode instead of a bridge.
Path to store WhatsApp session data.
Allowlist of WhatsApp phone numbers or JIDs.
JID or chat ID for reasoning output.
channels.feishu
Enable the Feishu/Lark bot.
Feishu app ID.
Feishu app secret.
Feishu event encryption key.
Feishu webhook verification token.
Allowlist of Feishu user open IDs.
Chat ID for reasoning output.
channels.dingtalk
Enable the DingTalk bot.
DingTalk app client ID.
DingTalk app client secret.
Allowlist of DingTalk user IDs.
Chat ID for reasoning output.
channels.qq
Enable the QQ bot.
QQ app ID.
QQ app secret.
Allowlist of QQ user IDs.
Chat ID for reasoning output.
channels.line
Enable the LINE bot.
LINE channel secret.
LINE channel access token.
Webhook path for LINE events.
Allowlist of LINE user IDs.
Chat ID for reasoning output.
channels.onebot
Enable the OneBot v11 adapter (QQ via go-cqhttp or similar).
WebSocket URL of the OneBot v11 server.
Access token for the OneBot server.
Reconnection interval in seconds when the WebSocket connection drops.
Allowlist of QQ user IDs.
Group or user ID for reasoning output.
channels.maixcam
Enable the MaixCam hardware channel.
Bind address for the MaixCam listener.
Port for the MaixCam listener.
Allowlist of device IDs.
Channel ID for reasoning output.
channels.wecom
WeCom Bot — easier setup, supports group chats via webhook.
Enable the WeCom bot channel.
WeCom verification token.
43-character AES encoding key for message encryption.
WeCom group robot webhook URL.
Incoming webhook path.
Allowlist of WeCom user IDs.
Reply timeout in seconds.
Chat ID for reasoning output.
channels.wecom_app
WeCom self-built application — more features, proactive messaging, private chats only.
Enable the WeCom App channel.
WeCom corporation ID.
WeCom application secret.
WeCom application agent ID.
WeCom verification token.
43-character AES encoding key.
Incoming webhook path.
Allowlist of WeCom user IDs.
Reply timeout in seconds.
Chat ID for reasoning output.
channels.wecom_aibot
WeCom AI Bot (智能机器人) — official WeCom AI Bot integration with proactive messaging.
Enable the WeCom AI Bot channel.
WeCom verification token.
43-character AES encoding key.
Incoming webhook path.
Maximum streaming steps per response.
Message sent automatically when a user opens a chat. Set to
"" to disable.Allowlist of WeCom user IDs.
Chat ID for reasoning output.
channels.standard
HTTP/WebSocket standard channel for custom integrations.
Enable the standard WebSocket channel.
Bearer token for authenticating incoming connections.
CORS allowed origins.
WebSocket ping interval in seconds.
Read timeout in seconds.
Write timeout in seconds.
Maximum simultaneous WebSocket connections.
Allowlist of client IDs.
tools
Additional filesystem paths the agent is permitted to read from, even when
restrict_to_workspace is true.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.
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.Maximum number of bytes to fetch from a single URL. Default is 10 MB.
Brave Search integration.
DuckDuckGo search (no API key required).
Perplexity AI search integration.
Tavily search integration.
tools.exec
Controls shell command execution safety.
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.Additional regular expressions to block. Commands matching any pattern are rejected. Patterns follow Go
regexp syntax.Regular expressions for commands that are explicitly allowed, overriding any matching deny patterns.
tools.cron
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.
Global toggle for all MCP server connections. Must be
true for any server to connect.Map of server names to server configuration objects. Server names are used only for identification in logs.Stdio example:Remote SSE/HTTP example:
tools.skills
Skill discovery and installation via registries.
ClawHub skill registry configuration.
Maximum number of simultaneous registry search requests.
In-memory search result cache settings.
tools.media_cleanup
Automatic cleanup of temporary media files.
Enable automatic media file cleanup.
Files older than this are eligible for removal.
How often the cleanup job runs.
heartbeat
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 in minutes. Minimum effective value is 5.
devices
Enable device monitoring capabilities (currently USB device detection).
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.
Bind address for the gateway listener. Change to
"0.0.0.0" to accept connections from the network.TCP port for the gateway listener.