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 делает → результат тебе.

```bash
# Запуск задачи вручную
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 с вашим аккаунтом
- **Лимиты:** зависят от тарифа, при интенсивном использовании могут кончаться
- **Подходит для:** редких задач, человек инициирует каждую задачу

**Авторизация на сервере:**
```bash
# Установка
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](https://console.anthropic.com)
2. Settings → API Keys → Create Key
3. Пополнить баланс через Settings → Billing (минимум $5)

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

---

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

```bash
# Установить 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/` с нужными ключами и репозиторием:

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

Файл `/opt/claude-agent/.env`:
```bash
ANTHROPIC_API_KEY=sk-ant-...
VAULT_PASSWORD=xXx9uZa_L1Zn!
```

Скрипт запуска `/opt/claude-agent/run-task.sh`:
```bash
#!/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

```python
# /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 сервис:
```ini
# /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](https://console.anthropic.com), пополнить на $20 (хватит на несколько месяцев)
2. **VPS-2** на Timeweb Cloud — 2 ГБ RAM, 2 vCPU (~400 руб/мес)
3. **Telegram Bot Token** — через @BotFather в Telegram (бесплатно)

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