177 lines
5 KiB
Markdown
177 lines
5 KiB
Markdown
# Setup
|
|
|
|
## Requirements
|
|
|
|
- Node.js 20+ or newer
|
|
- npm
|
|
- A Telegram bot token from `@BotFather`
|
|
|
|
## Project Setup
|
|
|
|
1. Install dependencies:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
2. Create `.env` from `.env.example` and fill in your bot token:
|
|
|
|
```env
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
https://api.telegram.org/bot<BOT_TOKEN>/logOut
|
|
```
|
|
|
|
Then set this in `.env`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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.
|