Перейти к содержимому
Интеграция с ИИ-агентами

Интеграция с ИИ-агентами

tguser изначально создавался как инструмент для ИИ-агентов (Hermes-Agent, OpenClaw, Claude Code, Codex CLI и др.): агент вызывает обычную shell-команду и отправляет сообщение в Telegram от имени пользователя.

Обязательный шаг: глобальная установка

Агент запускает команды из произвольной рабочей директории — того каталога, где идёт его текущая задача. Вариант uv run tguser … для этого плохо подходит: uv run привязан к проекту, поэтому из другой директории он определит (и синхронизирует) окружение чужого проекта, в котором никакого tguser нет. Вызов завершится ошибкой «command not found» — если только tguser уже не лежит в PATH, а это как раз и даёт глобальная установка.

Поэтому перед интеграцией установите инструмент глобально:

uv tool install git+https://github.com/yerza06/tguser-cli.git

Команда собирает пакет, создаёт для него изолированное окружение в ~/.local/share/uv/tools/tguser/ и кладёт исполняемый файл в ~/.local/bin/tguser. После этого агент может вызывать tguser из любой директории — как git или ls. Подробный разбор команды — в 01. Установка.

Проверить, что всё готово для агента:

cd /tmp && tguser whoami     # должен показать текущий аккаунт из любой директории

Что важно знать агенту

  • Команда одна и та же везде — tguser, без префиксов и без cd в репозиторий.
  • Состояние глобальное. Учётные данные, сессия и база чатов лежат в ~/.config/tguser/, поэтому результат не зависит от рабочей директории (см. 03. Конфигурация).
  • Файлы состояния не трогать. tguser.session и tguser.db в ~/.config/tguser/ удалять нельзя: первый — авторизация в Telegram, второй — все сохранённые имена чатов. Их удаление ломает агента полностью и требует участия человека (повторный интерактивный tguser login, ручное восстановление alias) — см. 03. Конфигурация.
  • Авторизация интерактивна. tguser login спрашивает телефон и код — это делает человек один раз. Агенту остаётся только отправка; повторный вход не нужен.
  • Цель (--to) лучше задавать именем чата. Человек один раз сохраняет alias (tguser chat add work -1001234567890), а агент использует понятное --to work вместо числового ID (см. 04. Управление чатами).
  • Коды выхода. Успех — 0, ошибка — 1 (в том числе ошибки Telegram), прерывание — 130. Текст ошибки печатается в stderr, поэтому агент может отличить успешную отправку от неудачной.
  • Язык вывода. По умолчанию английский; TGUSER_LANG=ru переключает сообщения на русский.

Типовые вызовы

tguser send "Задача завершена" --to work
tguser sendfile report.pdf --to work --caption "Отчёт за неделю"
tguser sendphoto chart.png --to me

Полный список команд и синтаксис — в 05. Отправка сообщений.

Готовый skill

Чтобы не объяснять агенту устройство tguser каждый раз, установите готовый Agent Skill — подготовленное описание инструмента (когда его применять, какие команды, где подводные камни), которое агент подгружает сам, как только задача касается Telegram.

npx skills add https://github.com/yerza06/tguser-cli --skills tguser

Установщик спросит, для каких агентов настроить skill, и скопирует его в их каталог:

АгентКуда попадёт skill
Claude Code~/.claude/skills/tguser/
Codex CLI~/.codex/skills/tguser/
Cursor~/.cursor/skills/tguser/
OpenCode~/.config/opencode/skills/tguser/
OpenClaw~/.openclaw/skills/tguser/
Cline, Zed, Warp и другие~/.agents/skills/tguser/

Skill написан по открытой спецификации Agent Skills, поэтому работает в любом агенте с её поддержкой — список выше не полный. Исходник лежит в этом репозитории в skills/tguser/: SKILL.md — краткая инструкция, references/reference.md — полные таблицы флагов и разбор ошибок.

Skill по-прежнему требует, чтобы человек один раз выполнил tguser login: войти сам он не может и прямо запрещает агенту это пытаться.