OpenACP/docs/gitbook/api-reference/environment-variables.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

51 lines
4.1 KiB
Markdown

# Environment Variables
Environment variables override values in `~/.openacp/config.json` at startup. They do not modify the config file.
All overrides are applied before Zod schema validation, so the final config is always validated.
| Variable | Config Equivalent | Type | Description |
|---|---|---|---|
| `OPENACP_TELEGRAM_BOT_TOKEN` | `channels.telegram.botToken` | string | Telegram Bot API token |
| `OPENACP_TELEGRAM_CHAT_ID` | `channels.telegram.chatId` | number | Telegram chat/supergroup ID (parsed as integer) |
| `OPENACP_DISCORD_BOT_TOKEN` | `channels.discord.botToken` | string | Discord bot token |
| `OPENACP_DISCORD_GUILD_ID` | `channels.discord.guildId` | string | Discord server (guild) ID |
| `OPENACP_SLACK_BOT_TOKEN` | `channels.slack.botToken` | string | Slack bot OAuth token (`xoxb-...`) |
| `OPENACP_SLACK_APP_TOKEN` | `channels.slack.appToken` | string | Slack app-level token for Socket Mode (`xapp-...`) |
| `OPENACP_SLACK_SIGNING_SECRET` | `channels.slack.signingSecret` | string | Slack signing secret |
| `OPENACP_DEFAULT_AGENT` | `defaultAgent` | string | Agent name to use when none is specified |
| `OPENACP_RUN_MODE` | `runMode` | `"foreground"` \| `"daemon"` | How `openacp` starts the server |
| `OPENACP_API_PORT` | `api.port` | number | REST API listen port (parsed as integer) |
| `OPENACP_LOG_LEVEL` | `logging.level` | string | Log level (`silent`, `debug`, `info`, `warn`, `error`, `fatal`) |
| `OPENACP_LOG_DIR` | `logging.logDir` | string | Directory for log files |
| `OPENACP_DEBUG` | `logging.level` → `"debug"` | any | Set to any non-empty value to enable debug logging. Ignored if `OPENACP_LOG_LEVEL` is also set. |
| `OPENACP_TUNNEL_ENABLED` | `tunnel.enabled` | boolean | Set to `"true"` or `"false"` to enable/disable the tunnel service |
| `OPENACP_TUNNEL_PORT` | `tunnel.port` | number | Tunnel service listen port (parsed as integer) |
| `OPENACP_TUNNEL_PROVIDER` | `tunnel.provider` | string | Tunnel provider (`cloudflare`, `ngrok`, `bore`, `tailscale`) |
| `OPENACP_SPEECH_STT_PROVIDER` | `speech.stt.provider` | string | Active speech-to-text provider name |
| `OPENACP_SPEECH_GROQ_API_KEY` | `speech.stt.providers.groq.apiKey` | string | API key for the Groq STT provider |
| `OPENACP_CONFIG_PATH` | — | string | Override the config file path (default: `~/.openacp/config.json`) |
| `OPENACP_INSTANCE_ROOT` | — | string | Set the instance root directory. Overrides auto-detection and CLI flags. See [Multi-Instance](../features/multi-instance.md). |
## Plugin-Level Environment Variables
With the plugin architecture, channel-specific and feature-specific environment variables are now handled by individual plugins in their `setup()` method. The following variables are **plugin-level** (processed by the respective plugin, not core):
- **Telegram plugin:** `OPENACP_TELEGRAM_BOT_TOKEN`, `OPENACP_TELEGRAM_CHAT_ID`
- **Discord plugin:** `OPENACP_DISCORD_BOT_TOKEN`, `OPENACP_DISCORD_GUILD_ID`
- **Slack plugin:** `OPENACP_SLACK_BOT_TOKEN`, `OPENACP_SLACK_APP_TOKEN`, `OPENACP_SLACK_SIGNING_SECRET`
- **Speech plugin:** `OPENACP_SPEECH_STT_PROVIDER`, `OPENACP_SPEECH_GROQ_API_KEY`
- **Tunnel plugin:** `OPENACP_TUNNEL_ENABLED`, `OPENACP_TUNNEL_PORT`, `OPENACP_TUNNEL_PROVIDER`
These remain functional for backward compatibility but are read by each plugin rather than by core config loading.
**Core-level** variables (processed by OpenACPCore directly): `OPENACP_CONFIG_PATH`, `OPENACP_DEFAULT_AGENT`, `OPENACP_RUN_MODE`, `OPENACP_API_PORT`, `OPENACP_LOG_LEVEL`, `OPENACP_LOG_DIR`, `OPENACP_DEBUG`.
## Notes
- **`OPENACP_DEBUG`** is a convenience shorthand. Setting `OPENACP_LOG_LEVEL=debug` is equivalent and takes precedence.
- **`OPENACP_CONFIG_PATH`** does not correspond to a config field; it controls where the config file is read from and is evaluated before any config is loaded.
- Numeric fields (`OPENACP_TELEGRAM_CHAT_ID`, `OPENACP_API_PORT`, `OPENACP_TUNNEL_PORT`) are converted to integers automatically.
- Boolean fields (`OPENACP_TUNNEL_ENABLED`) are compared to the string `"true"` — any other value is treated as `false`.
- Env vars take precedence over `config.json` but are not persisted; `openacp config set` modifies the file.