OpenACP/docs/gitbook/api-reference/configuration-schema.md
0xmrpeter e8af143c87 docs: update gitbook for recent specs (03-29 to 04-01)
Add new pages: output modes, workspaces (multi-instance), app connectivity.
Update 16 existing pages to reflect: tunnel auto-start/keepalive, JWT auth
system, SSE streaming, session config options, one-liner install, startup UX,
lazy session resume, new CLI commands (attach, remote), and new chat commands
(/mode, /model, /thought, /dangerous).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 21:24:26 +07:00

231 lines
9.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Configuration Schema
Config is stored at `~/.openacp/config.json`. The file is created with defaults on first run. All fields support backward-compatible migrations; old configs load without errors.
Edit interactively with `openacp config`, or set individual values with `openacp config set <path> <value>`.
---
## channels
Channel adapters. Each adapter key under `channels` is an object. The built-in Telegram and Discord adapters ship with OpenACP; Slack and others are plugin-based.
### channels.telegram.*
| Field | Type | Default | Description |
|---|---|---|---|
| `channels.telegram.enabled` | boolean | `false` | Enable the Telegram adapter |
| `channels.telegram.botToken` | string | `"YOUR_BOT_TOKEN_HERE"` | Telegram Bot API token (from @BotFather) |
| `channels.telegram.chatId` | number | `0` | Telegram group/supergroup chat ID |
| `channels.telegram.notificationTopicId` | number \| null | `null` | Forum topic ID for system notifications |
| `channels.telegram.assistantTopicId` | number \| null | `null` | Forum topic ID for the Assistant |
| `channels.telegram.outputMode` | `"low"` \| `"medium"` \| `"high"` | `"medium"` | Controls how much detail is shown in messages. The legacy key `displayVerbosity` is accepted for backward compatibility. |
### channels.discord.*
| Field | Type | Default | Description |
|---|---|---|---|
| `channels.discord.enabled` | boolean | `false` | Enable the Discord adapter |
| `channels.discord.botToken` | string | `"YOUR_DISCORD_BOT_TOKEN_HERE"` | Discord bot token |
| `channels.discord.guildId` | string | `""` | Discord server (guild) ID |
| `channels.discord.forumChannelId` | string \| null | `null` | Forum channel ID for session threads |
| `channels.discord.notificationChannelId` | string \| null | `null` | Channel ID for system notifications |
| `channels.discord.assistantThreadId` | string \| null | `null` | Thread ID for the Assistant |
| `channels.discord.outputMode` | `"low"` \| `"medium"` \| `"high"` | `"medium"` | Adapter-level output detail. Overridden per session via `/outputmode session`. 3-level cascade: session → adapter → global → `"medium"`. The legacy key `displayVerbosity` is auto-migrated on startup. |
### channels.slack.*
Slack support is provided via a plugin adapter. Fields follow the schema below when the Slack plugin is installed.
| Field | Type | Default | Description |
|---|---|---|---|
| `channels.slack.enabled` | boolean | `false` | Enable the Slack adapter |
| `channels.slack.botToken` | string | — | Slack bot OAuth token (`xoxb-...`) |
| `channels.slack.appToken` | string | — | Slack app-level token for Socket Mode (`xapp-...`) |
| `channels.slack.signingSecret` | string | — | Slack signing secret for request verification |
| `channels.slack.notificationChannelId` | string | — | Channel ID for system notifications |
| `channels.slack.allowedUserIds` | string[] | `[]` | Slack user IDs permitted to interact |
| `channels.slack.channelPrefix` | string | `"openacp"` | Prefix for auto-created Slack channels |
| `channels.slack.autoCreateSession` | boolean | `true` | Auto-create a session on first message |
| `channels.slack.startupChannelId` | string | — | Channel to post startup notification to |
### Base channel fields (all adapters)
| Field | Type | Default | Description |
|---|---|---|---|
| `enabled` | boolean | `false` | Whether this channel is active |
| `adapter` | string | — | Package name for plugin-based adapters |
| `outputMode` | `"low"` \| `"medium"` \| `"high"` | `"medium"` | Message detail level. The legacy key `displayVerbosity` is accepted for backward compatibility. |
---
## agents
Map of named agent configurations. Each key is an agent name used in `defaultAgent` and session creation.
| Field | Type | Default | Description |
|---|---|---|---|
| `agents.<name>.command` | string | — | Executable to spawn (e.g. `claude-agent-acp`) |
| `agents.<name>.args` | string[] | `[]` | Arguments passed to the command |
| `agents.<name>.workingDirectory` | string | — | Default working directory for this agent |
| `agents.<name>.env` | object | `{}` | Additional environment variables for the subprocess |
**Example**
```json
"agents": {
"claude": { "command": "claude-agent-acp", "args": [], "env": {} },
"codex": { "command": "codex", "args": ["--acp"], "env": {} }
}
```
---
## outputMode
| Field | Type | Default | Description |
|---|---|---|---|
| `outputMode` | `"low"` \| `"medium"` \| `"high"` | `"medium"` | Global default output mode. Overridden per adapter via `channels.<name>.outputMode` and per session via `/outputmode session`. See [Output Modes](../features/output-modes.md). |
---
## defaultAgent
| Field | Type | Default | Description |
|---|---|---|---|
| `defaultAgent` | string | `"claude"` | Agent name used when no agent is specified in a session |
---
## workspace
| Field | Type | Default | Description |
|---|---|---|---|
| `workspace.baseDir` | string | `"~/openacp-workspace"` | Base directory for agent working directories. `~` is expanded. Named workspaces are created as subdirectories. |
---
## security
| Field | Type | Default | Description |
|---|---|---|---|
| `security.allowedUserIds` | string[] | `[]` | Whitelist of channel user IDs permitted to start sessions. Empty list allows all users. |
| `security.maxConcurrentSessions` | number | `20` | Maximum number of simultaneously active sessions |
| `security.sessionTimeoutMinutes` | number | `60` | Minutes of inactivity before a session is automatically closed |
---
## logging
| Field | Type | Default | Description |
|---|---|---|---|
| `logging.level` | `"silent"` \| `"debug"` \| `"info"` \| `"warn"` \| `"error"` \| `"fatal"` | `"info"` | Log verbosity level |
| `logging.logDir` | string | `"~/.openacp/logs"` | Directory for log files |
| `logging.maxFileSize` | string \| number | `"10m"` | Maximum size per log file before rotation |
| `logging.maxFiles` | number | `7` | Number of rotated log files to retain |
| `logging.sessionLogRetentionDays` | number | `30` | Days to retain per-session log files |
---
## api
| Field | Type | Default | Description |
|---|---|---|---|
| `api.port` | number | `21420` | Port for the local REST API server |
| `api.host` | string | `"127.0.0.1"` | Host/interface to bind. Change to `0.0.0.0` to expose externally (not recommended without firewall rules). |
---
## runMode
| Field | Type | Default | Description |
|---|---|---|---|
| `runMode` | `"foreground"` \| `"daemon"` | `"foreground"` | How `openacp` (no args) starts the server. `daemon` forks to a background process. |
---
## autoStart
| Field | Type | Default | Description |
|---|---|---|---|
| `autoStart` | boolean | `false` | Whether to register OpenACP as a system service that starts on login |
---
## sessionStore
| Field | Type | Default | Description |
|---|---|---|---|
| `sessionStore.ttlDays` | number | `30` | Days before session records are purged from the store |
---
## tunnel
| Field | Type | Default | Description |
|---|---|---|---|
| `tunnel.enabled` | boolean | `false` | Enable the built-in tunnel service. When `true`, the tunnel auto-starts on server boot with keepalive monitoring. |
| `tunnel.provider` | `"cloudflare"` \| `"ngrok"` \| `"bore"` \| `"tailscale"` | `"cloudflare"` | Tunnel provider |
| `tunnel.options` | object | `{}` | Provider-specific options (passed through to the tunnel process) |
| `tunnel.maxUserTunnels` | number | `5` | Maximum number of simultaneous user-created tunnels |
| `tunnel.storeTtlMinutes` | number | `60` | Minutes before expired tunnel entries are cleaned up |
---
## usage
| Field | Type | Default | Description |
|---|---|---|---|
| `usage.enabled` | boolean | `true` | Track token/cost usage per session |
| `usage.monthlyBudget` | number | — | Monthly spending limit in `usage.currency` |
| `usage.warningThreshold` | number | `0.8` | Fraction of budget at which to send a warning (0–1) |
| `usage.currency` | string | `"USD"` | Currency for budget tracking |
| `usage.retentionDays` | number | `90` | Days to retain usage records |
---
## speech
### speech.stt.*
| Field | Type | Default | Description |
|---|---|---|---|
| `speech.stt.provider` | string \| null | `null` | Active STT provider name (e.g. `"groq"`) |
| `speech.stt.providers.<name>.apiKey` | string | — | API key for the named provider |
| `speech.stt.providers.<name>.model` | string | — | Model identifier for the named provider |
### speech.tts.*
| Field | Type | Default | Description |
|---|---|---|---|
| `speech.tts.provider` | string \| null | `null` | Active TTS provider name |
| `speech.tts.providers.<name>.apiKey` | string | — | API key for the named provider |
| `speech.tts.providers.<name>.model` | string | — | Model identifier for the named provider |
---
## agentSwitch
Controls the behavior of the `/switch` command.
| Field | Type | Default | Description |
|---|---|---|---|
| `agentSwitch.labelHistory` | boolean | `true` | When `true`, agent names are prepended to messages in the conversation history injected into the new agent during a switch. Helps the incoming agent distinguish which AI produced which response. |
**Example**
```json
"agentSwitch": {
"labelHistory": true
}
```
---
## integrations
Tracks installed agent integrations (managed automatically by `openacp agents install` / `openacp integrate`).
| Field | Type | Description |
|---|---|---|
| `integrations.<name>.installed` | boolean | Whether the integration is installed |
| `integrations.<name>.installedAt` | string | ISO 8601 timestamp of installation |