Configure xopc

Use the desktop or web console for routine settings. Use xopc config for terminal changes, automation, and diagnosis. Edit xopc.json directly only when a setting is not available in the UI.

Find the active configuration

xopc config path
xopc config show
xopc config validate

The default file is ~/.xopc/xopc.json. A profile, command-line option, or environment variable can select another file, so xopc config path is more reliable than assuming the default.

Change a setting safely

Use dot paths with the CLI:

xopc config get gateway.port
xopc config set gateway.port 18790
xopc config unset gateway.remote.url
xopc config validate

Values that look like JSON are parsed as JSON. Quote strings when your shell requires it.

After a change:

1. run xopc config validate;
2. restart the affected service if the UI does not show the new value;
3. perform one small verification action;
4. check logs before making more changes.

The Gateway reloads many settings automatically, but credentials, extensions, channels, and runtime changes may require a restart.

Common settings

Goal	Recommended place	Guide
Add a provider or choose a model	Settings → Capabilities → Models	Models
Create an Agent	Agents	Agents
Enable tools	Agent editor	Tools
Install or configure a Skill	Skills	Skills
Connect an MCP server	Settings → Agent MCP	MCP
Connect a messaging app	Channels	Channels
Enable remote access	Settings → Remote access	Remote access
Connect XOPC Cloud or an enterprise platform	xopc platform	XOPC Platform
Change voice or image providers	Settings → Capabilities	Voice, Images

Editing JSON directly

Back up the file first, keep the JSON syntax valid, and change one section at a time. Agent definitions, defaults, bindings, and client-specific Agent choices are not JSON settings; manage them in Agents, through conversation, or with xopc agents.

A minimal JSON shape is:

{
  "gateway": {
    "port": 18790
  }
}

Do not copy this over an existing configuration; it intentionally omits most settings. Use Configuration reference to find the relevant section.

Agent data is stored transactionally in ~/.xopc/xopc.db. On the first upgraded start, xopc imports old Agent JSON fields, writes backups, removes those fields from xopc.json, and then uses SQLite exclusively.

Secrets

Prefer the credential controls in the UI or commands such as xopc providers set-key. Credentials may live in auth profiles or environment variables instead of the main JSON file.

• Never commit xopc.json, .env, or auth files containing secrets.
• Do not share config show output without reviewing it, even though known secrets are masked.
• Rotate a token immediately if it appears in chat, logs, screenshots, or source control.

Profiles and overrides

xopc can use separate state profiles and alternate paths. When behavior differs between clients, compare:

xopc profile list
xopc config path

The most common cause is that two clients use different state directories, configuration files, or Gateway URLs.

For exact top-level fields, environment variables, and data locations, see Configuration reference and Data and file locations.