bot/setup.md

Setup

Requirements

• Node.js 20+ or newer
• npm
• A Telegram bot token from @BotFather

Project Setup

1. Install dependencies:

npm install

2. Create .env from .env.example and fill in your bot token:

BOT_TOKEN=your_telegram_bot_token_here
BOT_API_ROOT=
BOT_CONNECTOR=local-codex
LOCAL_CODEX_COMMAND=codex
LOCAL_CODEX_WORKDIR=
LOCAL_CODEX_SKILL_DIR=
LOCAL_CODEX_SANDBOX=workspace-write
LOCAL_CODEX_MODEL=
LOCAL_CODEX_PROFILE=
LOCAL_CODEX_SKIP_GIT_REPO_CHECK=
LOCAL_CODEX_ADD_DIRS=

3. Start the bot:

npm start

What The Bot Does

• Saves text messages to assets/request.txt by appending new lines
• Saves photos, videos, voice messages, and documents to assets/
• Immediately replies with Сообщение доставлено ИИ агенту, оно обрабатывается
• Sends the saved request to the configured connector strategy
• Returns the connector result back to Telegram as a follow-up reply

Connector Strategy

The bot uses a connector strategy selected by BOT_CONNECTOR.

local-codex

Runs the local codex CLI with codex exec for every supported Telegram message. The connector expects structured JSON output with:

• message: text reply for Telegram
• attachments: files to upload back to the user
• attachment fields: path, kind, caption

Supported attachment kind values:

• photo
• video
• animation
• document

If Codex generates an image, video, or any other file for the user, it should include that file path in attachments. Relative paths are resolved from LOCAL_CODEX_WORKDIR.

Relevant variables:

• BOT_CONNECTOR=local-codex
• LOCAL_CODEX_COMMAND=codex
• LOCAL_CODEX_WORKDIR=: working directory for Codex. Empty means this project root.
• LOCAL_CODEX_SKILL_DIR=: optional path to a local skill directory. ~ is supported.
• LOCAL_CODEX_SANDBOX=workspace-write: sandbox mode passed to codex exec
• LOCAL_CODEX_MODEL=: optional model override
• LOCAL_CODEX_PROFILE=: optional Codex profile
• LOCAL_CODEX_SKIP_GIT_REPO_CHECK=: set to true if the Codex workdir is not a git repo
• LOCAL_CODEX_ADD_DIRS=: comma-separated extra directories for Codex access

If LOCAL_CODEX_SKILL_DIR is set, the directory is passed to Codex as an accessible path and the agent is explicitly instructed to inspect and use that skill for media-generation tasks.

The connector queue is sequential, so messages are processed one by one in arrival order.

Optional: Local Bot API Server For Files Larger Than 20 MB

Telegram's hosted Bot API cannot download files larger than 20 MB. To support larger files, run a local telegram-bot-api server and point the bot to it with BOT_API_ROOT.

Official references:

• https://github.com/tdlib/telegram-bot-api
• https://core.telegram.org/bots/api#using-a-local-bot-api-server
• https://grammy.dev/guide/api.html

1. Get api_id and api_hash

Create them here:

• https://core.telegram.org/api/obtaining_api_id

2. Build The Local Bot API Server In ~/dev/lamda/bot_api

The commands below match the local layout already prepared on this machine.

mkdir -p ~/dev/lamda/bot_api

~/miniconda3/bin/conda create -y \
  -p ~/dev/lamda/bot_api/.buildenv \
  --override-channels \
  -c conda-forge \
  gperf openssl zlib cmake

git clone --recursive https://github.com/tdlib/telegram-bot-api.git ~/dev/lamda/bot_api/telegram-bot-api

git -C ~/dev/lamda/bot_api/telegram-bot-api submodule update --init --depth 1 td

mkdir -p ~/dev/lamda/bot_api/telegram-bot-api/build
mkdir -p ~/dev/lamda/bot_api/install

export PATH=~/dev/lamda/bot_api/.buildenv/bin:$PATH
export CMAKE_PREFIX_PATH=~/dev/lamda/bot_api/.buildenv

cmake -S ~/dev/lamda/bot_api/telegram-bot-api \
  -B ~/dev/lamda/bot_api/telegram-bot-api/build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=~/dev/lamda/bot_api/install \
  -DOPENSSL_ROOT_DIR=~/dev/lamda/bot_api/.buildenv \
  -DZLIB_ROOT=~/dev/lamda/bot_api/.buildenv

cmake --build ~/dev/lamda/bot_api/telegram-bot-api/build -j"$(nproc)"
cmake --install ~/dev/lamda/bot_api/telegram-bot-api/build

3. Start The Local Bot API Server

mkdir -p ~/dev/lamda/bot_api/data
mkdir -p ~/dev/lamda/bot_api/tmp

~/dev/lamda/bot_api/install/bin/telegram-bot-api \
  --api-id <API_ID> \
  --api-hash <API_HASH> \
  --local \
  --http-port 8081 \
  --dir ~/dev/lamda/bot_api/data \
  --temp-dir ~/dev/lamda/bot_api/tmp

4. Switch The Bot To The Local Server

Before switching away from Telegram's hosted Bot API, log the bot out there once:

https://api.telegram.org/bot<BOT_TOKEN>/logOut

Then set this in .env:

BOT_TOKEN=your_telegram_bot_token_here
BOT_API_ROOT=http://127.0.0.1:8081
BOT_CONNECTOR=local-codex

Restart the bot after that:

npm start

Notes

• BOT_API_ROOT is optional. Leave it empty to use the default Telegram hosted Bot API.
• The local Bot API server listens over HTTP by default.
• If both the bot and the local Bot API server run on the same machine, 127.0.0.1:8081 is enough.
• BOT_CONNECTOR defaults to local-codex in the current setup.