Configuration

All xopc configuration is centralized in ~/.xopc/xopc.json.

Use task guides first when you are trying to accomplish something:

Task	Guide
Configure a model	How to configure your first model
Connect Telegram	How to connect Telegram
Reach the gateway from another device	How to expose the gateway safely
Add another agent	How to create a second agent
Debug a broken setup	How to diagnose a broken setup

For the exhaustive field reference, see Configuration reference.

The rest of this page is reference material for the xopc.json shape.

Quick Start

Run the interactive setup wizard:

bash

xopc onboard

Or create manually:

json

{
  "agents": {
    "default": "main",
    "defaultPreset": "default",
    "capabilityPresets": {
      "default": {
        "id": "default",
        "name": "Global defaults",
        "models": {
          "defaultRole": "deep",
          "roles": {
            "deep": { "model": "anthropic/claude-sonnet-4-5" }
          }
        }
      }
    },
    "list": [
      {
        "id": "main",
        "identity": {
          "name": "Main",
          "role": "General assistant",
          "language": "en",
          "tone": "direct"
        },
        "responsibilities": {
          "primary": ["Help the user complete tasks"]
        },
        "workspace": { "root": "~/.xopc/workspace/main" },
        "tools": { "builtin": {} },
        "skills": { "mode": "all" },
        "memory": {
          "mode": "confirmWrite",
          "sources": ["session", "curated"],
          "writePolicy": { "curated": "confirm" },
          "understanding": { "enabled": true, "adaptiveCadence": true, "reviewIntervalTurns": 10 }
        },
        "workflows": {},
        "boundaries": { "requiresConfirmation": [], "forbidden": [], "escalation": [] }
      }
    ]
  },
  "providers": {
    "anthropic": "${ANTHROPIC_API_KEY}"
  }
}

Full Configuration Example

json

{
  "agents": {
    "default": "main",
    "list": [
      {
        "id": "main",
        "identity": { "name": "Main", "role": "General assistant" },
        "responsibilities": { "primary": ["Help the user complete tasks"] },
        "workspace": { "root": "~/.xopc/workspace/main" },
        "models": {
          "defaultRole": "deep",
          "roles": {
            "deep": { "model": "deepseek/deepseek-v4-flash" }
          }
        },
        "tools": { "builtin": {} },
        "skills": { "mode": "all" },
        "memory": { "mode": "confirmWrite", "sources": ["session"] },
        "workflows": {},
        "boundaries": { "requiresConfirmation": [], "forbidden": [], "escalation": [] }
      }
    ]
  },
  "providers": {
    "deepseek": "${DEEPSEEK_API_KEY}"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "defaults": {
        "dmPolicy": "pairing",
        "groupPolicy": "open",
        "streaming": { "mode": "partial" }
      },
      "accounts": {
        "personal": {
          "name": "Personal Bot",
          "botToken": "BOT_TOKEN",
          "dmPolicy": "allowlist",
          "groupPolicy": "open",
          "allowFrom": [123456789],
          "streaming": { "mode": "partial" }
        }
      }
    }
  },
  "gateway": {
    "host": "0.0.0.0",
    "port": 18790
  },
  "tools": {
    "web": {
      "search": {
        "maxResults": 5,
        "providers": [{ "type": "brave", "apiKey": "BSA_your_key_here" }]
      }
    },
    "media": {
      "audio": {
        "enabled": true,
        "provider": "alibaba",
        "alibaba": {
          "apiKey": "${DASHSCOPE_API_KEY}",
          "model": "paraformer-v2"
        }
      }
    }
  },
  "messages": {
    "tts": {
      "enabled": true,
      "provider": "openai",
      "trigger": "inbound",
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "model": "tts-1",
        "voice": "alloy"
      }
    }
  },
  "heartbeat": {
    "enabled": true,
    "intervalMs": 300000
  }
}

Configuration Sections

agents

Agent configuration is manifest-first. The required runtime entries live in agents.list; each entry is an Agent Capability Manifest. Routing and session keys use the first segment of the session key as the agent id. Reusable capabilityPresets and defaultPreset are optional policy patch mechanisms. There is no agents.defaults merge layer.

Top-level `agents` fields

Field	Type	Description
`default`	string	Optional. Default agent id when the session key or API does not specify one. If omitted: first enabled manifest in `list`, else `main`.
`defaultPreset`	string	Optional. Global preset id applied before each agent's own `extends`. Defaults to `default` when omitted. Use it only when you want shared baseline capabilities.
`capabilityPresets`	object	Optional. Named reusable policy patches keyed by preset id. Presets may define model roles, tools, skills, memory, workflows, boundaries, runtime limits, and locks.
`list`	array	Concrete Agent Capability Manifests. Each entry can be complete on its own, including its own `models`.

`agents.list` entries

Each entry must include id, identity, responsibilities, workspace, tools, skills, workflows, and boundaries. Add models directly to the agent when the agent owns its model roles. Profile Markdown still lives under agents/<id>/profile/ for long-form persona/context files, but the structured manifest is the source of truth for runtime policy. User understanding and memory are configured once in top-level userContext.

Field	Type	Description
`id`	string	Agent id (also the first segment of the session key).
`extends`	string[]	Optional list of preset ids from `agents.capabilityPresets`. Later presets and the manifest override earlier fields.
`enabled`	boolean	Default `true`. When `false`, the id is ignored for routing and runtime resolution.
`identity`	object	Structured display/model identity: `name`, `role`, optional `description`, `language`, `tone`, `avatar`.
`responsibilities`	object	`primary`, optional `secondary`, and optional `outOfScope` lists.
`workspace.root`	string	Per-agent Markdown workspace root (`~` expanded). Tool `cwd`, generated artifacts, and user files.
`models.defaultRole`	string	Role id used when a workflow/session does not request a named role.
`models.roles`	object	Named model roles. Each role uses `{ "model": "provider/model", "description": "..." }`.
`tools.builtin`	object	Built-in tool policy by tool name: `{ "mode": "allow"
`tools.mcp`	object	Optional MCP server/tool policies.
`skills`	object	Skill visibility policy: `all`, `allowlist`, `denylist`, or `off`.
`memory`	object	Memory mode, sources, write policy, retention, privacy, and optional background user-understanding review policy.
`workflows`	object	Optional default/allowed/suggested workflow policy.
`boundaries`	object	Confirmation, forbidden, and escalation rules.
`runtime`	object	Optional runtime limits (`maxTurns`, `timeoutMs`, `maxToolFailuresPerTurn`).
`prompt`	object	Optional structured prompt customizations.

Use xopc agents add / agents delete to manage entries and directories; there is no separate agent registry outside config.

models.roles

json

{
  "models": {
    "defaultRole": "deep",
    "roles": {
      "small": {
        "model": "openai/gpt-4o-mini",
        "description": "Fast low-cost model"
      },
      "large": {
        "model": "anthropic/claude-sonnet-4-5"
      }
    }
  }
}

Model ID format: provider/model-id (e.g., anthropic/claude-opus-4-5).

Preset model patches use the same models shape, without requiring a complete manifest.

providers

Configure LLM provider API keys. Use environment variable references:

json

{
  "providers": {
    "openai": "${OPENAI_API_KEY}",
    "anthropic": "${ANTHROPIC_API_KEY}",
    "groq": "${GROQ_API_KEY}"
  }
}

Built-in provider ids match @earendil-works/pi-ai KnownProvider. Env var names are defined in src/providers/env-keys.ts (PROVIDER_ENV_MAP); the table below mirrors that file. Other vendors (e.g. DashScope-only HTTP APIs) use models.json, not xopc.json → providers, unless you add a custom id there.

Provider id	Environment variables (first match wins where listed)
`amazon-bedrock`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` (and other AWS envs per pi-ai / SDK)
`anthropic`	`ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`
`azure-openai-responses`	`AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_BASE_URL`
`cloudflare-ai-gateway`	`CLOUDFLARE_API_KEY` (model URLs may also need account/gateway ids—see pi-ai model `baseUrl`)
`cloudflare-workers-ai`	`CLOUDFLARE_API_KEY`
`cerebras`	`CEREBRAS_API_KEY`
`dashscope`	`DASHSCOPE_API_KEY` (image/STT/TTS; not an LLM `KnownProvider` in pi-ai)
`deepseek`	`DEEPSEEK_API_KEY`
`fireworks`	`FIREWORKS_API_KEY`
`github-copilot`	`COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`, `GITHUB_COPILOT_TOKEN`
`google`	`GEMINI_API_KEY`, `GOOGLE_API_KEY`
`google-antigravity`	`ANTIGRAVITY_API_KEY`
`google-gemini-cli`	`GEMINI_CLI_TOKEN`, `GOOGLE_TOKEN`
`google-vertex`	`GOOGLE_CLOUD_API_KEY`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`
`groq`	`GROQ_API_KEY`
`huggingface`	`HF_TOKEN`, `HUGGINGFACE_TOKEN`
`kimi-coding`	`KIMI_API_KEY`, `MOONSHOT_API_KEY`
`minimax`	`MINIMAX_API_KEY`
`minimax-cn`	`MINIMAX_CN_API_KEY`, `MINIMAX_API_KEY`
`mistral`	`MISTRAL_API_KEY`
`moonshotai`	`MOONSHOT_API_KEY`
`moonshotai-cn`	`MOONSHOT_API_KEY`
`openai`	`OPENAI_API_KEY`
`openai-codex`	(no env map row—use OAuth / `xopc auth login openai-codex`)
`opencode`	`OPENCODE_API_KEY`
`opencode-go`	`OPENCODE_API_KEY`
`openrouter`	`OPENROUTER_API_KEY`
`together`	`TOGETHER_API_KEY`
`vercel-ai-gateway`	`AI_GATEWAY_API_KEY`, `VERCEL_AI_GATEWAY_API_KEY`
`xai`	`XAI_API_KEY`
`xiaomi`	`XIAOMI_API_KEY`
`xiaomi-token-plan-cn`	`XIAOMI_TOKEN_PLAN_CN_API_KEY`
`xiaomi-token-plan-ams`	`XIAOMI_TOKEN_PLAN_AMS_API_KEY`
`xiaomi-token-plan-sgp`	`XIAOMI_TOKEN_PLAN_SGP_API_KEY`
`zai`	`ZAI_API_KEY`

For why there are four Xiaomi ids, see Models — Built-in LLM providers.

Note: Environment variables take priority over config file values.

See Models Documentation for custom provider configuration.

bindings

Optional array of rules that assign an agentId to incoming traffic. Rules are sorted by priority (higher first). Each rule’s match requires an exact channel value (e.g. telegram); peerId may use * glob patterns. If nothing matches, routing uses the default agent id: agents.default if set, else the first enabled entry in agents.list, else main. See Session Routing System.

session

Field	Type	Default	Description
`dmScope`	string	`main`	How DM sessions are merged or split: `main`, `per-peer`, `per-channel-peer`, `per-account-channel-peer`
`identityLinks`	object	-	Map of canonical id → `["channel:peerId", ...]` aliases for cross-channel identity
`storage`	object	-	Optional session store tuning (`pruneAfterMs`, `maxEntries`)

Details and examples: Session Routing System.

channels

Communication channels configuration.

Keys under channels depend on which channel types you use. Built-in Telegram and Weixin accept the shapes documented in Channel configuration. Other keys may come from extensions—follow each extension’s README.

channels.telegram

Multi-account Telegram configuration:

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "defaults": {
        "dmPolicy": "pairing",
        "groupPolicy": "open",
        "streaming": { "mode": "partial" }
      },
      "accounts": {
        "personal": {
          "name": "Personal Bot",
          "botToken": "BOT_TOKEN",
          "dmPolicy": "allowlist",
          "groupPolicy": "open",
          "allowFrom": [123456789],
          "streaming": { "mode": "partial" }
        }
      }
    }
  }
}

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable Telegram
`accounts`	object	-	Multi-account config
`accounts.<id>.name`	string	-	Display name
`accounts.<id>.botToken`	string	-	Bot token
`defaults.dmPolicy`	string	`pairing`	Default DM policy for accounts
`defaults.groupPolicy`	string	`open`	Default group policy for accounts
`defaults.streaming.mode`	string	`partial`	Default stream mode for accounts
`accounts.<id>.dmPolicy`	string	inherits `defaults.dmPolicy`	DM policy
`accounts.<id>.groupPolicy`	string	inherits `defaults.groupPolicy`	Group policy
`accounts.<id>.allowFrom`	array	`[]`	Allowed user IDs
`accounts.<id>.streaming.mode`	string	inherits `defaults.streaming.mode`	Stream mode

DM policies (pairing | allowlist | open | disabled):

pairing (recommended): unknown users are not passed to the agent until their Telegram / Feishu / Weixin sender id is allowed. For Telegram, allow sources are channels.telegram.accounts.<id>.allowFrom plus entries in the Telegram credential file created after you run xopc channels pairing approve. First contact receives a pairing code in DM. See Channels — DM pairing and CLI — channels.
allowlist: same merge rules as pairing for the allow list, but no pairing code message; unknown senders are dropped.
open: any user can DM (avoid on public bots).
disabled: DMs are rejected.

Group Policies: open | allowlist | disabled

Stream Modes: off | partial | block

channels.feishu

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "APP_ID",
      "appSecret": "APP_SECRET",
      "verificationToken": "VERIFICATION_TOKEN"
    }
  }
}

gateway

HTTP API gateway configuration.

Field	Type	Default	Description
`bind`	string	`loopback`	`auto`, `loopback`, `lan`, `tailnet`, `custom`
`customBindHost`	string	-	IPv4 address when `bind` is `custom`
`port`	number	`18790`	Port number
`mode`	string	`local`	`local` or `remote` (CLI target)
`remote`	object	-	Persistent remote URL/token for CLI when `mode=remote`
`tailscale`	object	`{ mode: off }`	`serve` / `funnel` / `off` — see network.md
`tls`	object	-	Native HTTPS (optional)
`auth`	object	-	Authentication config
`corsOrigins`	string[]	`[]`	Browser origin allowlist

gateway.auth

Field	Type	Default	Description
`mode`	string	`token`	Auth mode: `none`, `token`, `password`
`token`	string	auto-generated	Bearer / `X-Api-Key` credential when `mode: "token"`
`password`	string	-	Password credential when `mode: "password"`
`rateLimit`	object	enabled	Brute-force protection for failed auth attempts

Notes:

gateway.auth.token and gateway.auth.password are mutually exclusive; setting both is rejected at startup.
In token mode, if no token is configured, xopc generates a random token at startup.
Weak / placeholder tokens (for example your-secret-token-here) and tokens shorter than 16 chars are rejected.
You can override auth from env: XOPC_GATEWAY_AUTH_MODE, XOPC_GATEWAY_TOKEN, XOPC_GATEWAY_PASSWORD.

gateway.auth.rateLimit

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable auth failure rate limiting
`maxAttempts`	number	`5`	Max failed attempts within the window
`windowMs`	number	`900000`	Rolling window in milliseconds
`blockDurationMs`	number	`300000`	Temporary block duration in milliseconds

gateway.corsOrigins

Field	Type	Default	Description
`gateway.corsOrigins`	string[]	`[]`	Browser origin allowlist (exact origins, e.g. `http://localhost:5173`)

Security behavior:

Browser requests with an Origin header are rejected when origin checks fail.
Non-browser requests without Origin are validated by the auth middleware instead.
Setting corsOrigins to "*" is allowed but flagged by startup security audit logs.

Channel connect defer

Fields live under gateway.* (channelConnectDeferMode, channelConnectDeferIds, channelConnectDeferSkipIds). When you run xopc gateway (the GatewayServer path), outbound-heavy channel plugins (Telegram, Weixin, Feishu) can defer ChannelPlugin.start() until after the HTTP listener has bound, so the control plane and static UI come up first. Plugin authors opt in via meta.deferConnectUntilAfterListen on the channel plugin.

Field	Type	Default	Description
`channelConnectDeferMode`	`"auto"` \| `"off"` \| `"explicit"`	(unset →) `auto`	`auto` — defer set = enabled channels whose plugin meta requests defer, minus `channelConnectDeferSkipIds`. `off` — never defer; all channels `start()` in phase 1. `explicit` — defer only ids listed in `channelConnectDeferIds` (empty list → defer none).
`channelConnectDeferIds`	string[]	-	Max 24 entries. Used when `channelConnectDeferMode` is `explicit`.
`channelConnectDeferSkipIds`	string[]	-	Max 24 entries. Removed from the defer set after `auto` or `explicit` resolution.

Startup logs (structured, phase: "gateway.channel_startup"):

stage: "phase1" — includes channelInitMs, deferPlanMs, channelPhase1StartMs, replayOutboundMs (or null when replay runs after listen), channelConnectDeferMode, channelConnectDeferSource (meta | explicit | off), and deferredChannelIds.
stage: "phase2" — after HTTP listen: channelPhase2DeferredMs, replayOutboundMs, onHttpListeningTotalMs, plus the same defer mode/source snapshot.

Useful filters: gateway.channel_startup or phase-1 complete / phase-2 complete in log text.

tools

Tool configurations.

tools.web

Field	Type	Default	Description
`search`	object	-	Web search config
`browse`	object	-	Web browsing config

tools.web.search

Field	Type	Default	Description
`maxResults`	number	`5`	Default result count when the tool omits `count`
`providers`	array	`[]`	Ordered list of search backends (`brave`, `tavily`, `bing`, `searxng`). Empty → HTML fallback only.

Each provider entry: type, optional apiKey, optional url (SearXNG base URL), optional disabled.

tools.media.audio (STT)

Speech-to-Text configuration for inbound voice messages. Lives under tools.media.audio (the gateway REST surface still exposes it as stt for backwards-friendly form payloads).

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable STT
`provider`	string	`alibaba`	Primary provider: `alibaba`, `openai`
`alibaba`	object	-	Alibaba DashScope config
`openai`	object	-	OpenAI Whisper config
`fallback`	object	-	Fallback configuration
`timeoutMs`	number	`60000`	Hard per-call HTTP timeout (ms)

tools.media.audio.alibaba

Field	Type	Default	Description
`apiKey`	string	-	DashScope API key (env: `DASHSCOPE_API_KEY`)
`model`	string	`paraformer-v2`	Model id

tools.media.audio.openai

Field	Type	Default	Description
`apiKey`	string	-	OpenAI API key (env: `OPENAI_API_KEY`)
`model`	string	`whisper-1`	Whisper model id

tools.media.audio.fallback

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable fallback
`order`	array	`["alibaba", "openai"]`	Fallback order

On failure, the runtime tries each provider in order and records structured attempts (provider, outcome, latency, reason) for diagnostics. All HTTP calls go through the shared media-shared/http chassis with SSRF guard (fetchWithTimeoutGuarded).

Example:

json

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "provider": "alibaba",
        "alibaba": {
          "apiKey": "${DASHSCOPE_API_KEY}",
          "model": "paraformer-v2"
        },
        "fallback": {
          "enabled": true,
          "order": ["alibaba", "openai"]
        }
      }
    }
  }
}

messages.tts (TTS)

Text-to-Speech configuration for assistant voice replies and the optional text_to_speech agent tool. Lives under messages.tts (the gateway REST surface still exposes it as tts).

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable TTS (and registration of `text_to_speech` when true)
`provider`	string	`openai`	Primary provider: `openai`, `alibaba`, `edge`, `minimax`, `tts-local-cli`, or any extension-registered SpeechProviderPlugin id
`trigger`	string	`always`	`off`, `always`, `inbound`, `tagged`
`maxTextLength`	number	`512`	Max characters sent to TTS providers. Conservative default chosen to fit every built-in provider (Alibaba qwen-tts caps at 512). Raise per-provider if your primary supports longer input.
`timeoutMs`	number	`60000`	Per-request HTTP timeout (ms). Range `1000`–`180000`. MiniMax internally bumps to ≥150s for its async polling flow.
`fallback`	object	-	Provider fallback order
`summarization`	object	-	LLM summarization before TTS when text exceeds threshold
`modelOverrides`	object	-	Allow `[[tts:...]]` directives from the model
`openai`	object	-	OpenAI TTS config
`alibaba`	object	-	Alibaba DashScope TTS config
`edge`	object	-	Microsoft Edge TTS (no API key)
`minimax`	object	-	MiniMax T2A async TTS config
`tts-local-cli`	object	-	Local CLI provider (bundled extension)

messages.tts.openai

Field	Type	Default	Description
`apiKey`	string	-	OpenAI API key (env: `OPENAI_API_KEY`)
`baseUrl`	string	`https://api.openai.com/v1`	Override base URL (env: `OPENAI_TTS_BASE_URL`) for OpenAI-compatible vendors
`model`	string	`tts-1`	Model: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`
`voice`	string	`alloy`	Voice: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`, `coral`, `verse`, …

messages.tts.alibaba

Field	Type	Default	Description
`apiKey`	string	-	DashScope API key (env: `DASHSCOPE_API_KEY`)
`model`	string	`qwen-tts`	TTS model id
`voice`	string	`longxiaochun`	Voice id (`Cherry`, `Ethan`, `longxiaochun`, `longxiaobai`, …)

messages.tts.edge

Field	Type	Default	Description
`enabled`	boolean	`true`	When `false`, Edge is excluded from the provider chain
`voice`	string	`en-US-MichelleNeural`	Edge voice id
`lang`	string	`en-US`	BCP-47 language
`outputFormat`	string	`audio-24khz-48kbitrate-mono-mp3`	Edge output format string
`proxy`	string	-	Optional HTTP(S) proxy for Edge

messages.tts.minimax

Field	Type	Default	Description
`apiKey`	string	-	MiniMax API key (env: `MINIMAX_API_KEY`)
`baseUrl`	string	`https://api.minimaxi.com/v1`	Override base URL
`model`	string	`speech-2.8-hd`	Model id (`speech-2.8-hd`, `speech-2.8-turbo`, …)
`voice`	string	`male-qn-qingse`	Voice id
`groupId`	string	-	Forward-compat slot for enterprise tier

messages.tts.tts-local-cli

Provided by the bundled tts-local-cli extension (see extensions/tts-local-cli/xopc.extension.json for the authoritative JSON Schema). Spawns any local TTS binary (mlx-audio, sherpa-onnx-tts, piper, …) via shell template and reads the output file.

Field	Type	Default	Description
`command`	string	required	Shell command template; supports , , , placeholders (case-insensitive)
`args`	string[]	`[]`	Extra args appended after the parsed command
`cwd`	string	-	Working directory for the spawned process
`outputFormat`	enum	`wav`	File extension produced by the CLI: `mp3` \| `opus` \| `wav`
`timeoutMs`	number	`120000`	Hard kill timeout (ms)
`env`	object	-	Extra env vars merged into the spawned process env (`Record<string,string>`)

The Voice settings UI exposes the common fields (command, cwd, outputFormat, timeoutMs); args and env are advanced fields — edit ~/.xopc/xopc.json directly to set them.

messages.tts.fallback

Field	Type	Default	Description
`enabled`	boolean	`true`	Try other providers on failure
`order`	array	`["openai","alibaba","edge","minimax"]`	Order after deduplicating primary

The fallback list accepts any registered SpeechProviderPlugin id, including extension providers like tts-local-cli.

messages.tts.summarization

Field	Type	Default	Description
`enabled`	boolean	`true`	Summarize long text via LLM before TTS
`threshold`	number	same as `maxTextLength`	Min length to trigger summarization
`targetLength`	number	same as `maxTextLength`	Target length after summarization
`model`	string	-	Model ref for summarization; env `XOPC_TTS_SUMMARIZE_MODEL` if unset

Trigger modes:

off: No automatic TTS on outbound
always: TTS when outbound rules pass
inbound: TTS only when the user message carried voice (transcribedVoice)
tagged: TTS only when assistant text contains [[tts]]

See Voice (STT/TTS) for Telegram group voice + mention behavior, /tts status, and channel formats.

mcp

Outbound MCP server registry (agent consumes external MCP tools).

Field	Type	Default	Description
`sessionIdleTtlMs`	number	`600000`	Per-session MCP runtime idle TTL (10 min); `0` disables eviction
`servers`	object	`{}`	Server id → connection definition (stdio or HTTP)

See MCP for configuration, Web UI, and security notes.

heartbeat

Periodic health check configuration.

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable heartbeat
`intervalMs`	number	`300000`	Interval in ms (5 min)

automations

Automations are managed in SQLite and through the Gateway console/API, not through xopc.json. Open #/automations or use /api/automations and /api/automation-runs.

See Automations for triggers, actions, reliability, and run history.

extensions

Extension enable/disable configuration.

json

{
  "extensions": {
    "enabled": ["telegram-channel", "weather-tool"],
    "disabled": ["deprecated-extension"],
    "telegram-channel": {
      "token": "bot-token-here"
    },
    "weather-tool": true
  }
}

Field	Type	Description
`enabled`	string[]	List of extension IDs to enable
`disabled`	string[]	(Optional) List of extension IDs to disable
`[extension-id]`	object/boolean	Extension-specific configuration

See Extensions Documentation for details.

Environment Variables

xopc supports environment variables for sensitive data:

Variable	Description
`OPENAI_API_KEY`	OpenAI API key
`ANTHROPIC_API_KEY`	Anthropic API key
`ANTHROPIC_OAUTH_TOKEN`	Anthropic OAuth token (when used)
`GOOGLE_API_KEY` / `GEMINI_API_KEY`	Google AI (Gemini) API keys
`GROQ_API_KEY`	Groq API key
`CEREBRAS_API_KEY`	Cerebras API key
`DEEPSEEK_API_KEY`	DeepSeek API key
`MINIMAX_API_KEY`	MiniMax API key
`MOONSHOT_API_KEY`	Moonshot / Kimi-family keys (see `PROVIDER_ENV_MAP` for `moonshotai*` vs `kimi-coding`)
`FIREWORKS_API_KEY`	Fireworks AI
`TOGETHER_API_KEY`	Together AI
`CLOUDFLARE_API_KEY`	Cloudflare Workers AI / AI Gateway
`XIAOMI_API_KEY`	Xiaomi MiMo (API billing); token-plan variants use `XIAOMI_TOKEN_PLAN_*_API_KEY`
`AI_GATEWAY_API_KEY`	Vercel AI Gateway (alias `VERCEL_AI_GATEWAY_API_KEY`)
`DASHSCOPE_API_KEY`	Alibaba DashScope (STT/TTS, image gen)
`XOPC_TTS_SUMMARIZE_MODEL`	Model ref for TTS long-text summarization when `tts.summarization.model` is unset
`TELEGRAM_BOT_TOKEN`	Telegram bot token
`XOPC_CONFIG`	Custom config file path
`XOPC_WORKSPACE`	Custom workspace directory
`XOPC_SESSION_SEARCH_MODEL`	Default model for `session_search` summaries when the selected manifest does not provide a summary model role
`XOPC_LOG_LEVEL`	Log level (trace/debug/info/warn/error/fatal)
`XOPC_LOG_DIR`	Log directory path
`XOPC_LOG_CONSOLE`	Enable console output (true/false)
`XOPC_LOG_FILE`	Enable file output (true/false)
`XOPC_LOG_RETENTION_DAYS`	Days to retain log files
`XOPC_PRETTY_LOGS`	Pretty print logs for development
`XOPC_LOG_LLM_PAYLOAD`	Include the complete system prompt, messages, and tools in debug logs (sensitive; default false)

Environment variables take priority over config file values.

Configuration Management

Validate Configuration

bash

xopc config validate
# legacy alias:
xopc config --validate

View Configuration

bash

xopc config show
# legacy alias:
xopc config --show

Edit values with xopc config set / xopc config unset, or open xopc config path in your editor.

Update

Controls version checks, optional auto-install, and post-update gateway restart behavior. See Updates.

json

{
  "update": {
    "channel": "stable",
    "checkOnStart": true,
    "auto": {
      "enabled": false,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  },
  "commands": {
    "restart": true
  }
}

Key	Default	Description
`update.channel`	`stable`	`stable` \| `beta` \| `dev` — maps to npm dist-tags `latest` / `beta` / `dev`
`update.checkOnStart`	`true`	Gateway queries registry on startup
`update.auto.enabled`	`false`	Auto-install from gateway (stable/beta npm global only)
`update.auto.stableDelayHours`	`6`	Stable rollout delay after first detection
`update.auto.stableJitterHours`	`12`	Extra random delay for stable auto-update
`update.auto.betaCheckIntervalHours`	`1`	Min hours between auto attempts for same beta version
`commands.restart`	`true`	When `false`, disables post-update restart and SIGUSR1 restart paths

FAQ

Q: How to use multiple providers?

Use the providers configuration to define multiple API keys. The agent automatically selects the appropriate provider based on the model ID:

json

{
  "providers": {
    "openai": "${OPENAI_API_KEY}",
    "anthropic": "${ANTHROPIC_API_KEY}"
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}

Q: How to use Ollama (local models)?

Configure custom provider in ~/.xopc/models.json:

json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" }
      ]
    }
  }
}

See Models Documentation for details.

Q: How to configure OAuth?

xopc supports OAuth authentication for certain providers:

Kimi (Device Code Flow):

json

{
  "providers": {
    "kimi": {
      "auth": {
        "type": "oauth",
        "clientId": "your-client-id"
      }
    }
  }
}

Kimi uses Device Code Flow - the CLI will prompt you to visit auth.kimi.com and enter a code.

Q: How to use environment variables?

Use ${VAR_NAME} syntax in config:

json

{
  "providers": {
    "openai": "${OPENAI_API_KEY}",
    "anthropic": "${ANTHROPIC_API_KEY}"
  }
}

Or set environment variables directly without adding to config.

Configuration ​

Quick Start ​

Full Configuration Example ​

Configuration Sections ​

agents ​

Top-level agents fields ​

agents.list entries ​

models.roles ​

providers ​

bindings ​

session ​

channels ​

channels.telegram ​

channels.feishu ​

gateway ​

gateway.auth ​

gateway.auth.rateLimit ​

gateway.corsOrigins ​

Channel connect defer ​

tools ​

tools.web ​

tools.web.search ​

tools.media.audio (STT) ​

tools.media.audio.alibaba ​

tools.media.audio.openai ​

tools.media.audio.fallback ​

messages.tts (TTS) ​

messages.tts.openai ​

messages.tts.alibaba ​

messages.tts.edge ​

messages.tts.minimax ​

messages.tts.tts-local-cli ​

messages.tts.fallback ​

messages.tts.summarization ​

mcp ​

heartbeat ​

automations ​

extensions ​

Environment Variables ​

Configuration Management ​

Validate Configuration ​

View Configuration ​

Update ​

FAQ ​

Q: How to use multiple providers? ​

Q: How to use Ollama (local models)? ​

Q: How to configure OAuth? ​

Q: How to use environment variables? ​

Configuration

Quick Start

Full Configuration Example

Configuration Sections

agents

Top-level `agents` fields

`agents.list` entries

models.roles

providers

bindings

session

channels

channels.telegram

channels.feishu

gateway

gateway.auth

gateway.auth.rateLimit

gateway.corsOrigins

Channel connect defer

tools

tools.web

tools.web.search

tools.media.audio (STT)

tools.media.audio.alibaba

tools.media.audio.openai

tools.media.audio.fallback

messages.tts (TTS)

messages.tts.openai

messages.tts.alibaba

messages.tts.edge

messages.tts.minimax

messages.tts.tts-local-cli

messages.tts.fallback

messages.tts.summarization

mcp

heartbeat

automations

extensions

Environment Variables

Configuration Management

Validate Configuration

View Configuration

Update

FAQ

Q: How to use multiple providers?

Q: How to use Ollama (local models)?

Q: How to configure OAuth?

Q: How to use environment variables?