infra/docs/claude-agent.md

Claude Code Agent на сервере

Это руководство объясняет как запустить Claude Code как автономного агента на сервере, который будет управлять инфраструктурой без участия человека.

---

Что это такое

Claude Code — CLI-инструмент от Anthropic, тот самый с которым ты сейчас работаешь. Его можно запустить на сервере в режиме автономного агента. Агент:

• Имеет доступ к файлам репозитория
• Может запускать shell-команды (Ansible, Docker, Git)
• Слушает задачи через API и выполняет их
• Работает в рамках твоей подписки Anthropic

---

Два режима работы

Режим 1: "Разбуди и сделай" (простой)

Ты пишешь задачу (в Telegram боте, через web-форму, вручную) → скрипт запускает Claude Code с этой задачей → Claude делает → результат тебе.

# Запуск задачи вручную
claude --print "Задача: обнови Forgejo до последней версии, протестируй, задеплой" \
  --allowedTools "Bash,Read,Edit,Write,Glob,Grep"

Режим 2: Постоянный агент (сложнее)

Claude Code запущен как сервис, слушает очередь задач (через Redis или простой API).

---

Что нужно купить / активировать

Вариант A: Claude.ai Pro или Max (подписка)

• Цена: Pro $20/мес, Max $100/мес
• Что даёт: Claude Code работает через OAuth с вашим аккаунтом
• Лимиты: зависят от тарифа, при интенсивном использовании могут кончаться
• Подходит для: редких задач, человек инициирует каждую задачу

Авторизация на сервере:

# Установка
npm install -g @anthropic-ai/claude-code

# Авторизация (один раз, браузер не нужен — используй --print с токеном)
claude auth login
# Или через переменную среды:
export ANTHROPIC_API_KEY=sk-ant-...

Вариант B: Anthropic API Key (рекомендуется для сервера)

• Цена: pay-per-use, ~$3-15 за 1M токенов (зависит от модели)
• Типичный расход: одна задача "задеплой сервис" ≈ $0.05-0.30
• Что даёт: полный контроль, нет лимитов по частоте (только по деньгам)
• Подходит для: автоматического агента, частых задач

Как получить:

1. Зайти на console.anthropic.com
2. Settings → API Keys → Create Key
3. Пополнить баланс через Settings → Billing (минимум $5)

Рекомендуемая модель: claude-sonnet-4-6 — баланс цены и качества для инфра-задач.

---

Установка Claude Code на VPS-2

# Установить Node.js 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Установить Claude Code
sudo npm install -g @anthropic-ai/claude-code

# Проверить
claude --version

---

Конфигурация для инфра-агента

Создать /opt/claude-agent/ с нужными ключами и репозиторием:

mkdir -p /opt/claude-agent
cd /opt/claude-agent
git clone git@git.csrx.ru:jack/infra.git repo

Файл /opt/claude-agent/.env:

ANTHROPIC_API_KEY=sk-ant-...
VAULT_PASSWORD=xXx9uZa_L1Zn!

Скрипт запуска /opt/claude-agent/run-task.sh:

#!/bin/bash
set -euo pipefail

TASK="${1:-}"
if [ -z "$TASK" ]; then
  echo "Usage: $0 'task description'"
  exit 1
fi

source /opt/claude-agent/.env
export ANTHROPIC_API_KEY

cd /opt/claude-agent/repo
git pull origin master

echo "$VAULT_PASSWORD" > ~/.vault-password-file
chmod 600 ~/.vault-password-file

claude --print "$TASK" \
  --allowedTools "Bash,Read,Edit,Write,Glob,Grep" \
  --model claude-sonnet-4-6 \
  2>&1 | tee /opt/claude-agent/logs/$(date +%Y%m%d-%H%M%S).log

---

Простой Telegram-бот для управления агентом

Самый удобный интерфейс — бот в Telegram. Ты пишешь задачу, бот запускает Claude, присылает результат.

Стек: Python + python-telegram-bot + subprocess

# /opt/claude-agent/bot.py
import subprocess, logging
from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

ALLOWED_USER_ID = 123456789  # твой Telegram ID

async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if update.effective_user.id != ALLOWED_USER_ID:
        return

    task = update.message.text
    await update.message.reply_text(f"🤖 Запускаю задачу:\n{task}")

    result = subprocess.run(
        ["/opt/claude-agent/run-task.sh", task],
        capture_output=True, text=True, timeout=600
    )

    output = result.stdout[-4000:] if len(result.stdout) > 4000 else result.stdout
    await update.message.reply_text(f"✅ Готово:\n```{output}```", parse_mode="Markdown")

app = Application.builder().token("BOT_TOKEN").build()
app.add_handler(MessageHandler(filters.TEXT, handle_message))
app.run_polling()

Запуск как systemd сервис:

# /etc/systemd/system/claude-agent-bot.service
[Unit]
Description=Claude Code Infrastructure Agent Bot
After=network.target

[Service]
WorkingDirectory=/opt/claude-agent
ExecStart=/usr/bin/python3 bot.py
Restart=always
EnvironmentFile=/opt/claude-agent/.env

[Install]
WantedBy=multi-user.target

---

Права и безопасность

Агент имеет доступ к:

• Репозиторию инфры (git clone)
• SSH-ключу для деплоя на серверы
• Vault-паролю

Минимально необходимые права:

• SSH-ключ с правами deploy пользователя (не root)
• Ansible vault password
• Git push права в репозиторий

Что НЕ давать агенту:

• Root SSH-доступ
• Доступ к продакшен БД напрямую
• Billing API ключи облачного провайдера

---

Стоимость использования

Типичные задачи и примерная стоимость (claude-sonnet-4-6):

Задача	Токены (≈)	Стоимость
Проверить статус сервисов	5K	$0.02
Обновить один сервис	20K	$0.06
Добавить новый сервис в инфру	50K	$0.15
Полный деплой с отладкой	100-200K	$0.30-0.60

При 10-20 задачах в месяц: $2-10/мес на API.

---

Итого: что покупать

1. Anthropic API Key — console.anthropic.com, пополнить на $20 (хватит на несколько месяцев)
2. VPS-2 на Timeweb Cloud — 2 ГБ RAM, 2 vCPU (~400 руб/мес)
3. Telegram Bot Token — через @BotFather в Telegram (бесплатно)

Итого: ~$20 единоразово + ~$5-10/мес на использование.