- DisplaySpecBuilder: add TunnelServiceInterface constructor injection, implement outputViewerLink/outputFallbackContent for long output (>15 lines or >800 chars) - DisplaySpecBuilder: fix buildThoughtSpec indicator to "Thinking..." - ActivityTracker: store and pass tunnelService to DisplaySpecBuilder, pass sessionContext to all buildToolSpec calls - setupVerbosityCallbacks: write outputMode instead of deprecated displayVerbosity key - /verbosity static command description updated to note deprecation - Docs: update displayVerbosity → outputMode across configuration, chat-commands, troubleshooting, and architecture docs; add /outputmode command reference
9.4 KiB
Configuration
Config File Location
All configuration lives in a single JSON file:
~/.openacp/config.json
The path can be overridden with the OPENACP_CONFIG_PATH environment variable. The file is created automatically on first run with safe defaults.
Interactive Editor
To edit config interactively while OpenACP is running:
openacp config
This opens a menu-driven editor with sections for Channels, Agent, Workspace, Security, Logging, Run Mode, API, and Tunnel. Changes are saved on exit. When the daemon is running, changes are applied immediately via the local API without requiring a restart (where supported).
Reconfigure Wizard
For a guided reconfiguration of core sections, use:
openacp onboard
This runs runReconfigure(), which loads your existing config, shows a summary, and lets you step through sections selectively. Sections available:
- Channels — Add, modify, disable, or delete channel configurations. For each configured channel you can choose to modify settings, disable the bot without losing credentials, or permanently delete the channel config.
- Agents — Select which installed agent to use as the default.
- Workspace — Change the base directory where agent working directories are created.
- Run Mode — Switch between foreground and daemon mode, and toggle autostart on boot.
- Integrations — Configure optional integrations (e.g., Claude CLI).
For the machine-readable schema with all field types and defaults, see the Configuration Schema. For a full list of environment variable overrides, see Environment Variables.
Plugin-Specific Settings
With the microkernel plugin architecture, plugin-specific settings (Telegram botToken, speech providers, tunnel config, etc.) are now stored in per-plugin settings files:
~/.openacp/plugins/<plugin-name>/settings.json
The core config.json only contains: defaultAgent, workspace, security, logging, runMode, autoStart, and sessionStore.
Fields like channels, tunnel, speech, and usage in config.json are legacy (auto-migrated) — they are automatically migrated to their respective plugin settings.json files on startup. Existing configurations continue to work without manual changes.
Full Configuration Reference
channels
Channel adapters. Each key is a channel identifier. The built-in channels are telegram and discord.
Telegram:
"telegram": {
"enabled": true,
"botToken": "1234567890:ABC...",
"chatId": -1001234567890,
"outputMode": "medium"
}
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | false |
Whether this channel is active |
botToken |
string | — | Telegram Bot API token |
chatId |
number | — | Forum group chat ID |
outputMode |
low | medium | high |
medium |
Detail level for agent output messages. The legacy key displayVerbosity is accepted for backward compatibility. |
Discord:
"discord": {
"enabled": true,
"botToken": "MTI...",
"guildId": "123456789012345678",
"forumChannelId": null,
"notificationChannelId": null
}
agents
Named map of ACP-compatible agent binaries. Each entry describes how to spawn the agent subprocess.
"agents": {
"claude": {
"command": "claude-agent-acp",
"args": [],
"env": {},
"workingDirectory": "~/projects"
}
}
| Field | Type | Default | Description |
|---|---|---|---|
command |
string | — | Executable name or path |
args |
string[] | [] |
Additional CLI arguments |
env |
object | {} |
Extra environment variables for the subprocess |
workingDirectory |
string | — | Override working directory (otherwise uses workspace) |
defaultAgent
"defaultAgent": "claude"
The agent key used when a new session is created. Must exist in agents.
workspace
"workspace": {
"baseDir": "~/openacp-workspace"
}
Base directory for agent working directories. Named workspaces are subdirectories under this path. The ~ prefix is expanded to the home directory.
security
"security": {
"allowedUserIds": [],
"maxConcurrentSessions": 20,
"sessionTimeoutMinutes": 60
}
| Field | Type | Default | Description |
|---|---|---|---|
allowedUserIds |
string[] | [] |
Allowlist of platform user IDs. Empty = all users allowed. |
maxConcurrentSessions |
number | 20 |
Hard cap on active + initializing sessions across all channels. |
sessionTimeoutMinutes |
number | 60 |
Idle session timeout in minutes. |
See Security for details.
logging
"logging": {
"level": "info",
"logDir": "~/.openacp/logs",
"maxFileSize": "10m",
"maxFiles": 7,
"sessionLogRetentionDays": 30
}
See Logging for details.
runMode
"runMode": "foreground"
"foreground" or "daemon". Controls whether openacp start runs in the terminal or spawns a detached background process.
autoStart
"autoStart": false
If true, OpenACP installs a platform autostart entry (macOS LaunchAgent or Linux systemd user service) so the daemon starts on login. Managed automatically by the run mode setup in the config editor and onboard wizard.
api
"api": {
"port": 21420,
"host": "127.0.0.1"
}
The local REST API used by the CLI and web UI. host defaults to 127.0.0.1 (loopback only). Do not bind to 0.0.0.0 unless you have network-level access controls in place.
tunnel
"tunnel": {
"enabled": true,
"port": 3100,
"provider": "cloudflare",
"options": {},
"maxUserTunnels": 5,
"storeTtlMinutes": 60,
"auth": { "enabled": false }
}
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | false |
Enable tunnel |
port |
number | 3100 |
Local port the tunnel exposes |
provider |
string | "cloudflare" |
cloudflare, ngrok, bore, or tailscale |
options |
object | {} |
Provider-specific options (domain, authtoken, etc.) |
auth.enabled |
boolean | false |
Require bearer token on tunnel requests |
usage
"usage": {
"enabled": true,
"monthlyBudget": 50,
"warningThreshold": 0.8,
"currency": "USD",
"retentionDays": 90
}
Usage tracking. When monthlyBudget is set and usage reaches warningThreshold (80% by default), a notification is sent. Set enabled: false to disable tracking entirely.
speech
"speech": {
"stt": {
"provider": null,
"providers": {
"groq": { "apiKey": "gsk_..." }
}
},
"tts": {
"provider": null,
"providers": {}
}
}
Speech-to-text and text-to-speech configuration. Set provider to the key of a configured entry in providers to enable. null disables speech for that direction.
sessionStore
"sessionStore": {
"ttlDays": 30
}
How long completed session records are retained before cleanup.
integrations
Managed automatically. Records which optional integrations are installed.
Environment Variable Overrides
The following environment variables override their corresponding config fields at startup. They do not modify the config file on disk.
| Variable | Config path |
|---|---|
OPENACP_CONFIG_PATH |
(config file path itself) |
OPENACP_TELEGRAM_BOT_TOKEN |
channels.telegram.botToken |
OPENACP_TELEGRAM_CHAT_ID |
channels.telegram.chatId |
OPENACP_DISCORD_BOT_TOKEN |
channels.discord.botToken |
OPENACP_DISCORD_GUILD_ID |
channels.discord.guildId |
OPENACP_SLACK_BOT_TOKEN |
channels.slack.botToken |
OPENACP_SLACK_APP_TOKEN |
channels.slack.appToken |
OPENACP_SLACK_SIGNING_SECRET |
channels.slack.signingSecret |
OPENACP_DEFAULT_AGENT |
defaultAgent |
OPENACP_RUN_MODE |
runMode |
OPENACP_API_PORT |
api.port |
OPENACP_LOG_LEVEL |
logging.level |
OPENACP_LOG_DIR |
logging.logDir |
OPENACP_DEBUG |
Sets logging.level to debug (when OPENACP_LOG_LEVEL is not set) |
OPENACP_TUNNEL_ENABLED |
tunnel.enabled |
OPENACP_TUNNEL_PORT |
tunnel.port |
OPENACP_TUNNEL_PROVIDER |
tunnel.provider |
OPENACP_SPEECH_STT_PROVIDER |
speech.stt.provider |
OPENACP_SPEECH_GROQ_API_KEY |
speech.stt.providers.groq.apiKey |
Environment variables are applied after the config file is read and before Zod validation. They take precedence over file values.
Hot-Reload
When openacp config communicates changes via the local API (daemon mode), supported fields are applied to the running process immediately. Fields that require a full restart (e.g., channel credentials, API port) emit a needsRestart signal in the response.
Backward Compatibility
Every new config field uses .default() or .optional() in the Zod schema. This means an older config.json will always pass validation after an upgrade — missing fields are filled with their defaults. Fields are never renamed or removed without a migration.
Automatic migrations run at startup before validation. Current migrations:
add-tunnel-section— Adds thetunnelblock if absent (pre-0.3 configs).fix-agent-commands— Renames legacy agent command names to their current equivalents.migrate-agents-to-store— Moves agent definitions fromconfig.jsoninto the separate~/.openacp/agents.jsonstore.
Migrations mutate the raw JSON in place and write it back to disk if any change was made. No action is required from you.