Configuration reference
This page maps the main configuration areas. For a specific installed version, xopc config show, xopc config get <path>, and the settings UI are the authoritative view of effective values.
Locations and commands
Default file: ~/.xopc/xopc.json.
xopc config path
xopc config show
xopc config get <dot.path>
xopc config set <dot.path> <value>
xopc config unset <dot.path>
xopc config validateXOPC_CONFIG or XOPC_CONFIG_PATH can select another configuration file. State profiles can also change the default root.
Top-level areas
| Section | Controls |
|---|---|
userContext | Shared user-owned context, privacy, and recall behavior |
providers | Model provider configuration and credential references |
channels | Telegram, Weixin, Feishu, and extension channel settings |
gateway | Port, binding, authentication, remote connection, and Tailscale behavior |
tools | Search, browser, media, runtime, and other tool settings |
messages | Outbound message and text-to-speech behavior |
mcp | External MCP server connections and lifecycle settings |
extensions | Extension enable/disable and extension-specific configuration |
runtimeTools | Managed Node.js and Python runtimes |
heartbeat | Periodic Agent checks when enabled |
platform | Standalone or connected mode, the platform base URL, optional workspace, and validated discovery snapshot |
Workflows and Automations are normally managed in their own Gateway pages rather than written directly into xopc.json.
Agent definitions, inherited defaults, routing bindings, and surface defaults live in ~/.xopc/xopc.db. Manage them from Agents, xopc agents, or an Agent conversation; they are intentionally absent from xopc.json.
Common path overrides
| Variable | Purpose |
|---|---|
XOPC_STATE_DIR | State root |
XOPC_CONFIG / XOPC_CONFIG_PATH | Configuration file |
XOPC_WORKSPACE | Primary workspace override |
XOPC_CREDENTIALS_DIR | Credential directory |
XOPC_LOG_DIR | Log directory |
XOPC_LOG_LEVEL | Log verbosity |
XOPC_AUTOMATION_WEBHOOK_SECRETS | JSON object mapping Automation webhook secret ids to secrets |
Provider-specific variables such as OPENAI_API_KEY are shown by provider setup and xopc providers schema <provider>.
Validation and secrets
Run xopc config validate after direct edits. Use JSON syntax: no trailing commas or duplicate keys. Prefer UI or CLI credential commands for secrets, and review any output before sharing it.
Task-oriented instructions are in Configure xopc.