Configuration

This page documents runtime configuration via environment variables.

For ready-to-use command examples per backend, see Agent Setup.

TELEGRAM_BOT_TOKEN

Telegram bot token (from BotFather). Required unless passed as --telegram-token.

TELEGRAM_ALLOWED_USER_IDS

Comma-separated allowlist of Telegram numeric user IDs. Example: 123456,987654.

TELEGRAM_ALLOWED_USERNAMES

Comma-separated allowlist of Telegram usernames. Usernames are normalized to lowercase and can include or omit @. Example: alice,@bob.

ACP_AGENT_COMMAND

Command line used to launch the ACP agent process. Examples: npx @zed-industries/codex-acp, uv run examples/echo_agent.py. Required unless passed as --agent-command.

ACP_RESTART_COMMAND

Optional command used by /restart to relaunch the bot process. Recommended when you run with uv run ... and need to preserve its flags. Example: uv run telegram-acp-bot --telegram-token ... --agent-command ....

ACP_PERMISSION_MODE

Default permission policy for ACP tool calls. Allowed values: ask, approve, deny. Maps to --permission-mode.

ACP_PERMISSION_EVENT_OUTPUT

Permission/tool event log output mode. Allowed values: stdout, off. Maps to --permission-event-output.

ACP_STDIO_LIMIT

Asyncio stdio reader limit in bytes for ACP transport. Increase this if the agent emits very large JSON lines. Maps to --acp-stdio-limit.

ACP_CONNECT_TIMEOUT

Timeout in seconds for ACP initialize/new_session handshake. Prevents /new from hanging forever if the agent does not speak ACP over stdio. Maps to --acp-connect-timeout.

ACP_LOG_LEVEL

Application log level. Common values: DEBUG, INFO, WARNING, ERROR.

ACP_LOG_FORMAT

Application log format. Allowed values: text, json. text includes contextual key/value fields in each line. json emits structured logs with chat_id, session_id, and prompt_cycle_id.

ACP_ACTIVITY_MODE

Controls how intermediate agent activity events are shown in Telegram. Allowed values: normal, compact, verbose. normal (default) emits each visible activity event as its own message. compact collapses all events into a single in-place status message that is replaced by the final answer when the agent responds. While work is in progress, that same compact message keeps the normal activity emoji in the message text (for example ⚙️, 🌐, 📖) and rotates the trailing dots to show progress. verbose streams append-only updates in place for active reply text and tool activity, and then finalizes those messages when the prompt completes. Maps to --activity-mode.

ACP_SCHEDULED_TASKS_DB

Path to the SQLite database used for deferred follow-up tasks. Maps to --scheduled-tasks-db.

ACP_TELEGRAM_CHANNEL_ALLOW_PATH

Enables path inputs for the internal MCP telegram_send_attachment tool. Disabled by default. Set to 1 (or true/yes/on) only when file-path inputs are trusted.

ACP_TELEGRAM_CHANNEL_STATE_FILE

Path to the MCP channel shared state file (session_id -> chat_id, plus last active session). Usually injected by the bot runtime for the internal MCP server.

ACP_TELEGRAM_BOT_TOKEN

Telegram bot token used by the internal MCP server when sending attachments. Usually injected by the bot runtime for the internal MCP server.

Example .env

TELEGRAM_BOT_TOKEN=123456:abc
TELEGRAM_ALLOWED_USER_IDS=123456789
# TELEGRAM_ALLOWED_USERNAMES=alice,@bob
ACP_AGENT_COMMAND="npx @zed-industries/codex-acp"
ACP_RESTART_COMMAND="uv run telegram-acp-bot --telegram-token 123456:abc --agent-command \"npx @zed-industries/codex-acp\""
ACP_PERMISSION_MODE=ask
ACP_PERMISSION_EVENT_OUTPUT=stdout
ACP_STDIO_LIMIT=8388608
ACP_CONNECT_TIMEOUT=30
ACP_LOG_LEVEL=INFO
ACP_LOG_FORMAT=text
ACP_ACTIVITY_MODE=normal
ACP_SCHEDULED_TASKS_DB=/home/alice/.local/state/telegram-acp-bot/scheduled-tasks.sqlite3

MCP behavior

The bot always advertises an internal MCP stdio server named telegram-channel to the ACP agent. No extra configuration is required.

MCP channel environment variables

• ACP_TELEGRAM_CHANNEL_ALLOW_PATH controls whether MCP attachment delivery accepts path input. Default behavior is disabled, so agents must use data_base64.

• ACP_TELEGRAM_CHANNEL_STATE_FILE points to runtime state used to resolve session routing for MCP calls.

• ACP_TELEGRAM_BOT_TOKEN is the token consumed by the MCP server when calling Telegram Bot API.

Security notes:

• Keep ACP_TELEGRAM_CHANNEL_ALLOW_PATH disabled unless your agent is trusted to read local files.

• ACP_TELEGRAM_CHANNEL_STATE_FILE and ACP_TELEGRAM_BOT_TOKEN are typically managed by the bot process and should not be shared across unrelated runtimes.