SHiNE-server/codex-agent-VPS/AGENTS.md

AGENTS

Назначение

• codex-agent-VPS — переносимая версия Telegram-бота для запуска codex CLI на VPS.
• Папку можно ставить в любое место на Linux-сервере, если там есть python3, systemd, codex и доступ в интернет.
• Конфигурация делается через .env.

Состав папки

• README.md — краткое описание структуры.
• Agent-server-package/ — готовый набор файлов для копирования на VPS.
• .env.example — пример конфигурации.
• AGENTS.md — инструкция по установке и настройке.

Требования к VPS

• Linux-сервер с systemd.
• Установленные python3, curl, ffmpeg.
• Установленный codex CLI.
• Выполненный codex login под тем пользователем, от которого будет работать сервис.
• Telegram bot token.
• Telegram usernames разрешённых пользователей.

Установка через Codex

1. Скопировать содержимое Agent-server-package/ на сервер в нужное место, например:
   • /home/your_user/codex-agent
2. Установить codex CLI под рабочим пользователем.
3. Выполнить под этим же пользователем:
   • codex login
4. Установить системные зависимости:
   • python3
   • ffmpeg
5. Взять .env.example из корня codex-agent-VPS и создать на сервере .env.
6. В .env заполнить:
   • TELEGRAM_BOT_TOKEN
   • ALLOWED_TELEGRAM_USERNAME
   • ALLOWED_TELEGRAM_PLAYERS
   • BOT_USERNAME
   • CODEX_BIN
   • CODEX_WORKDIR
7. Если нужны voice/audio и голосовые ответы, дополнительно задать:
   • OPENAI_API_KEY
8. В Agent-server-package/scripts/systemd/shine-agent-bot-coder.service заменить:
   • your_user
   • /home/your_user/codex-agent на реальные значения.
9. Скопировать unit в:
   • /etc/systemd/system/shine-agent-bot-coder.service
10. Выполнить:

• sudo systemctl daemon-reload
• sudo systemctl enable --now shine-agent-bot-coder

11. Проверить:

• sudo systemctl status shine-agent-bot-coder --no-pager
• sudo journalctl -u shine-agent-bot-coder -f

Настройка доступа

• ALLOWED_TELEGRAM_USERNAME — основной разрешённый пользователь.
• ALLOWED_TELEGRAM_PLAYERS — дополнительные разрешённые пользователи:
  • username1:Имя 1,username2:Имя 2
• Все пользователи из whitelist в этой версии считаются полноправными.
• Все входящие задачи попадают в одну общую очередь и выполняются строго последовательно.

Поведение агента

• Бот принимает текст, voice и audio.
• Для каждого пользователя ведётся отдельная история.
• Все задачи запускаются через codex exec.
• Рабочая директория задаётся через CODEX_WORKDIR.
• Вызов идёт без sandbox/approval ограничений: --dangerously-bypass-approvals-and-sandbox.

Что обычно меняют при переносе

• .env
• Agent-server-package/scripts/systemd/shine-agent-bot-coder.service
• при необходимости Agent-server-package/AGENT.md

Полезные команды

• Проверка установки Codex:
  • codex --version
  • codex doctor
• Self-test без Telegram:
  • python3 py_bot_service.py --selftest-codex "Ответь одной строкой: Codex работает"
• Проверка сервиса:
  • sudo systemctl status shine-agent-bot-coder --no-pager
  • sudo journalctl -u shine-agent-bot-coder -f

Примечания

• Если codex doctor пишет, что credentials не найдены, нужно выполнить codex login.
• Если OPENAI_API_KEY пустой, текстовые задачи через codex будут работать, а voice/audio и TTS-функции — нет.
• Если у пользователя в Telegram нет username, whitelist по username его не пропустит.