@emaxe/agento

v0.7.0

Published

3 days ago

Manage AI agent configurations with profiles and providers

0High
0Medium
0Low

emaxe

ai agent cli configuration claude codex qwen opencode profile provider terminal tui

AgentO — Менеджер конфигураций AI-агентов

Управляйте конфигурациями AI-агентов с помощью профилей и провайдеров. Переключайтесь между моделями, провайдерами и агентами без лишних усилий.

AgentO — это CLI-инструмент для централизованного управления конфигурациями популярных AI-агентов для программирования. Задайте API-провайдеры один раз, создайте профили с разными комбинациями моделей и переключайтесь между ними одной командой.

English version: README.md

Поддерживаемые агенты

| Агент | Команда | Формат конфига | Поддерживаемые провайдеры | Особенности | |-------|---------|----------------|---|-------------| | Claude Code | claude | JSON | anthropic, fireworks, openrouter, openai-compatible, responses-compatible | Поддержка уровней (small/base/smart). Для не-Anthropic провайдеров используется локальный proxy. | | OpenCode | opencode | JSON | anthropic, openai-compatible, fireworks, openrouter | Полная поддержка function calling через Vercel AI SDK; пробрасывает модальности | | Qwen CLI | qwen | JSON | openai-compatible, fireworks, openrouter | Структура OpenAI-совместимого API; пробрасывает модальности | | Codex CLI | codex | TOML | openai-compatible, fireworks, openrouter | wire_api: responses. Профиль в отдельном default.config.toml. | | Kimi Code | kimi | JSON | openai-compatible, fireworks, openrouter | Конфиг через ~/.kimi-cli/.env (DEFAULT_PROVIDER, DEFAULT_MODEL, BASE_URL). | | Kilo Code | kilo | JSON | anthropic, openai-compatible, fireworks, openrouter | Читает defaultProvider/defaultModel из ~/.kilocode/settings.json. Кастомный baseUrl из ~/.kilocode/models.json. | | PI | pi | JSON | anthropic-compatible, openai-compatible, fireworks, openrouter, custom-api | Читает defaultProvider/defaultModel из ~/.pi/agent/settings.json. Кастомный baseUrl из ~/.pi/agent/models.json. | | Copilot | copilot | только env-переменные | anthropic, openai-compatible, fireworks, openrouter | Весь конфиг передаётся через переменные окружения — файл настроек не изменяется. | | Goose | goose | только env-переменные | anthropic, openai-compatible, fireworks, openrouter | Весь конфиг через env vars (GOOSE_PROVIDER, GOOSE_MODEL). |

Поддерживаемые типы провайдеров

| Тип провайдера | Совместимые агенты | Примеры | |---|---|---| | anthropic | claude-code, opencode, copilot, goose | Anthropic | | openai-compatible | opencode, qwen, copilot, goose | OpenAI, Together.ai, Cerebras, Perplexity, DeepSeek и т. д. | | fireworks | claude-code, opencode, qwen, codex, copilot, goose | Fireworks AI (поддерживает все 3 типа API) | | openrouter | claude-code, opencode, qwen, codex, copilot, goose | OpenRouter — универсальный шлюз (Anthropic Skin / OpenAI / Responses API) | | responses-compatible | claude-code | OpenAI и любой провайдер, поддерживающий OpenAI Responses API |

Примечания:

claude-code работает со всеми 5 типами провайдеров. Для не-anthropic провайдеров используется локальный proxy: Anthropic Scrubber для fireworks/openrouter; OpenAI-to-Anthropic proxy для openai-compatible; Responses Proxy для responses-compatible. Для openrouter использует Anthropic Skin — ANTHROPIC_AUTH_TOKEN (Bearer).
copilot и goose работают со всеми 4 стандартными типами провайдеров; конфиг передаётся через переменные окружения, файл настроек не изменяется.
openrouter наиболее универсален среди стандартных типов — работает со всеми 6 агентами.

Флаги возможностей моделей

Каждая модель внутри провайдера хранит три флага возможностей:

image — модель принимает изображения на вход
video — модель принимает видео на вход
audio — модель принимает аудио на вход

Значения по умолчанию при добавлении: image=true, video=false, audio=false.

Формат маркера: в TUI и agento provider list возможности отображаются как [iva] (всё включено), [i--] (только image), [---] (только текст) и т. п. Маркер информационный — он никогда не записывается в конфиг агента.

Зачем это нужно:

Qwen получает generationConfig.modalities из этих флагов (раньше всё было захардкожено в false — изображения не работали).
OpenCode генерирует на каждую модель modalities: { input: ["text", "image", ...], output: ["text"] }, чтобы агент знал, что модель принимает.
Claude Code и Codex пока эти флаги игнорируют (Anthropic SDK и Codex responses API не имеют поля для модальностей).

Переключение возможностей: TUI → Провайдеры → Edit, наведите курсор на модель и нажимайте i / v / a, чтобы переключать флаги. Новые модели добавляются строкой [+ add model] (Enter). CLI provider add -M ... создаёт модели с дефолтными значениями.

Конфиги, созданные старыми версиями (с string[] моделями), мигрируются автоматически при чтении с дефолтными значениями возможностей.

Установка

Глобальная установка (рекомендуется)

npm install -g @emaxe/agento

Локальная установка

npm install --save-dev @emaxe/agento
npx @emaxe/agento

Требования

Node.js ≥ 18
Один или несколько установленных CLI-инструментов поддерживаемых агентов

Быстрый старт

1. Добавьте API-провайдер

# OpenAI-совместимый провайдер (например, Fireworks AI)
agento provider add \
  -n "Fireworks AI" \
  -t openai-compatible \
  -k "sk-your-api-key" \
  -u "https://api.fireworks.ai/inference/v1" \
  -M "accounts/fireworks/models/llama-v3p1-70b-instruct,accounts/fireworks/models/kimi-k2p6"

# Провайдер Anthropic
agento provider add \
  -n "Anthropic" \
  -t anthropic \
  -k "sk-ant-your-key" \
  -M "claude-sonnet-4-20250514,claude-3-5-haiku-20241022"

2. Создайте профиль

# Профиль с одной моделью
agento profile add -n "default" -m "provider-id:claude-sonnet-4-20250514"

# Многоуровневый профиль (требуются уровни: small/base/smart)
agento profile add -n "multi" -m "provider-id:claude-3-5-haiku-20241022:small,provider-id:claude-sonnet-4-20250514:base,provider-id:claude-opus-4-20250514:smart"

3. Запустите агента

# Интерактивный TUI-режим (по умолчанию)
agento

# Прямой запуск
agento launch -p default -a claude-code

# Запуск с указанием режима и области видимости
agento launch -p default -a qwen -m child -s project

Интерактивный TUI

Запуск agento без аргументов открывает интерактивный терминальный интерфейс (TUI), построенный на Ink и React.

Главное меню

┌────────── AgentO v0.4.4 ──────────┐
│                                   │
│ ▶  Запустить агента               │
│    Провайдеры                     │
│    Профили                        │
│    Агенты                         │
│    Настройки                      │
│                                   │
└───────────────────────────────────┘

Навигация: ↑↓ перемещение, Enter выбор, Esc / q выход.

Обзор экранов

| Экран | Возможности | Горячие клавиши | |-------|-------------|-----------------| | Запуск агента | Выбор профиля → агента → запуск; статус установки кешируется на диск; при ENOENT — перезапуск TUI с ошибкой. На установленном агенте: u — обновить, d — удалить | Enter выбор, Esc назад, u обновить, d удалить | | Провайдеры | Просмотр, добавление, редактирование, удаление провайдеров; переключение возможностей моделей | Enter детали / добавить модель, a добавить провайдер, e редактировать, d удалить, i/v/a переключить флаг, Esc назад | | Профили | Просмотр, добавление, удаление профилей. В деталях: добавление/удаление/редактирование моделей | Enter детали, a добавить, d удалить, Esc назад | | Агенты | Проверка статуса конфигов (global/project), наличие бэкапов | Enter детали, Esc назад | | Настройки | Изменение режима запуска и области конфига; выделенная настройка показывает описание текущего значения | ↑↓ навигация, Enter/Space переключение, Esc сохранить и назад |

Сценарий запуска агента

Выбор профиля — выберите один из сохранённых профилей
Выбор агента — AgentO проверяет статус установки всех агентов (спиннер). Неустановленные агенты отмечены (not installed). Установленные агенты при выделении показывают (u update, d delete). Статусы кешируются в ~/.agento/agent-status.json — при следующем открытии уже известные агенты не перепроверяются.
- Агент установлен → нажмите Enter для запуска, u для обновления или d для удаления
- Агент не установлен → открывается Мастер установки
- Команда не найдена при запуске (ENOENT) → TUI перезапускается с ошибкой, агент помечается как не установленный
Мастер установки (при необходимости):
- Автоустановка — проверка окружения (требуется npm/brew/uv), затем установка через нативный пакетный менеджер агента
- Ручная установка — показывает точную команду и URL документации
Обновление / Удаление агента (если нажали u/d на установленном агенте):
- Диалог подтверждения (Да/Нет)
- Выполнение команды (npm update -g, brew upgrade, uv tool uninstall и т.д.) с живым спиннером
- При успехе → возврат к списку агентов с обновлённым статусом
- При ошибке → показ stderr; возможность повторить или вернуться назад
Запуск — AgentO применяет конфиг агента и запускает его

Profile: default
├─ Agent: claude-code
├─ Mode: child
├─ Scope: global
└─ [ Запуск ]

В режиме child после выхода агента вы вернётесь в AgentO, а оригинальный конфиг будет автоматически восстановлен.

В режиме independent AgentO завершается сразу, а изменённый конфиг остаётся на месте.

Экран провайдеров

Управляйте API-провайдерами без необходимости запоминать CLI-флаги:

Просмотр всех провайдеров с типом, моделями, маркерами возможностей и base URL
Добавление нового провайдера с подсказками (имя, тип, API-ключ, модели, base URL)
Редактирование существующих провайдеров — включая флаги возможностей моделей (i/v/a)
Удаление ненужных провайдеров

В режиме редактирования модели отображаются как ▶ [i--] model-name. Когда выделена модель, нажимайте i / v / a, чтобы переключать image / video / audio. Используйте строку [+ add model] (Enter) для добавления моделей, d — удалить, e — переименовать.

Экран профилей

Организуйте конфигурации моделей:

Просмотр всех профилей с моделями и уровнями
Добавление профилей с одной или несколькими моделями
В деталях профиля: добавление/удаление/редактирование отдельных моделей

Экран агентов

Следите за статусом конфигураций агентов:

Увидеть, есть ли у каждого агента глобальный или проектный конфиг
Проверить, есть ли бэкапы (признак того, что AgentO ранее изменял конфиг)
Посмотреть пути к конфигам для каждого агента

Экран настроек

Настройте поведение AgentO по умолчанию:

| Настройка | Варианты | Описание | |-----------|----------|----------| | Режим запуска по умолчанию | child / independent | Как запускать агентов по умолчанию | | Область конфига по умолчанию | global / project | Куда записывать конфиги агентов | | Слияние конфигов агентов | true / false | Сохранять неизвестные ключи при записи конфига агента (conservative merge) |

При навигации выделенная настройка показывает пояснение к текущему значению прямо под строкой.

Управление: ↑↓ навигация, Enter или Space переключение значений, Esc сохранить и вернуться.

TUI vs CLI

| Задача | TUI | CLI | |--------|-----|-----| | Визуальный просмотр провайдеров | ✅ | — | | Быстрый разовый запуск | — | agento launch -p <p> -a <a> | | Автоматизация скриптами | — | ✅ | | Проверка статуса конфига | ✅ | agento agent status | | Пошаговое создание провайдера/профиля | ✅ | Ручная сборка флагов |

Используйте TUI для изучения и интерактивных сценариев. Используйте CLI для скриптов, алиасов и быстрых запусков.

Справочник по CLI

`agento` — Главная команда

По умолчанию запускает интерактивный TUI.

agento          # Запуск интерактивного TUI
agento --dev    # Показать development-агентов в TUI

`agento launch` — Запуск агента

agento launch -p <profile> -a <agent> [options]

Опции:
  -p, --profile <name>   Имя профиля (обязательно)
  -a, --agent <id>       Агент: claude-code, opencode, qwen, codex (обязательно)
  -m, --mode <mode>      Режим запуска: child или independent (по умолчанию из настроек)
  -s, --scope <scope>    Область конфига: global или project (по умолчанию из настроек)
  -d, --dev              Показать development-агентов

Режимы запуска:

Child (по умолчанию): Временно заменяет конфиг агента, запускает его, восстанавливает оригинальный конфиг при выходе
Independent: Постоянно заменяет конфиг; восстановление вручную

Области конфига:

Global: ~/.<agent>/settings.*
Project: ./.<agent>/settings.* или ./<agent>.*

`agento provider` — Управление провайдерами

agento provider list                          # Список всех провайдеров (с маркерами возможностей)
agento provider add [options]                 # Добавить провайдер
  -n, --name <name>         Отображаемое имя (обязательно)
  -t, --type <type>         Тип: anthropic, openai-compatible или fireworks (обязательно)
  -k, --api-key <key>       API-ключ (обязательно)
  -u, --base-url <url>      Base URL (обязателен для openai-compatible, опциональный для других)
  -M, --models <models>     Список моделей через запятую (обязательно). Возможности по умолчанию:
                            image=true, video=false, audio=false. Меняйте в TUI клавишами i/v/a.
agento provider remove <name>                 # Удалить провайдер

Дефолты Base URL:

anthropic: использует стандартный endpoint Anthropic
fireworks: автоматически https://api.fireworks.ai/inference, если не указан
openrouter: автоматически https://openrouter.ai/api/v1 (Claude Code: https://openrouter.ai/api), если не указан
openai-compatible: автоматически https://api.openai.com/v1, если не указан; для нестандартных провайдеров указывайте явно через -u

`agento profile` — Управление профилями

agento profile list                           # Список всех профилей
agento profile add [options]                  # Добавить профиль
  -n, --name <name>         Имя профиля (обязательно)
  -m, --models <models>     Список providerId:modelName[:tier] через запятую (обязательно)
                            Tier опционален для одномодельных профилей.
                            Для многоуровневых: tier должен быть small|base|smart, минимум один base.
agento profile remove <name>                  # Удалить профиль

`agento agent` — Статус агентов

agento agent status                           # Статус конфигов всех агентов
agento agent status --dev                     # Включая development-агентов

`agento restore` — Восстановление конфига

agento restore -a <agent> -s <scope>          # Восстановить конфиг агента из бэкапа

Опции:
  -a, --agent <id>         ID агента (обязательно)
  -s, --scope <scope>      Область конфига: global или project (обязательно)

Конфигурация

AgentO хранит свою конфигурацию в ~/.agento/config.json:

{
  "providers": [
    {
      "id": "uuid",
      "name": "Fireworks AI",
      "type": "fireworks",
      "apiKey": "fw-...",
      "models": [
        { "name": "accounts/fireworks/models/llama-v3p1-70b-instruct", "capabilities": { "image": false, "video": false, "audio": false } },
        { "name": "accounts/fireworks/models/kimi-k2", "capabilities": { "image": true, "video": false, "audio": false } }
      ]
    }
  ],
  "profiles": [
    {
      "id": "uuid",
      "name": "default",
      "models": [
        {
          "providerId": "uuid",
          "model": "accounts/fireworks/models/llama-v3p1-70b-instruct",
          "tier": "base"
        }
      ]
    }
  ],
  "settings": {
    "defaultLaunchMode": "child",
    "defaultConfigScope": "global",
    "mergeAgentConfigs": true
  }
}

Конфиги, созданные AgentO < 0.2.0, имеют models как массив строк. Они мигрируются автоматически при чтении; возможности по умолчанию { image: true, video: false, audio: false }, меняются в TUI.

Как это работает

Адаптеры агентов

Каждый поддерживаемый агент имеет адаптер, который переводит универсальный формат AgentO в специфичный конфиг агента:

Claude Code (anthropic, fireworks, openrouter, openai-compatible, responses-compatible): Генерирует ~/.claude/settings.json с выбором модели по уровням и переменными окружения ANTHROPIC_*. Использует Anthropic SDK.
- Для fireworks и openrouter: автоматически стартует локальный Anthropic Scrubber proxy, вырезающий неподдерживаемые поля из запросов.
- Для openai-compatible: автоматически стартует локальный OpenAI-to-Anthropic proxy, транслирующий OpenAI API (включая SSE streaming) в Anthropic-формат.
- Для responses-compatible: автоматически стартует локальный Responses Proxy (src/proxy/responses-proxy.ts), транслирующий Anthropic-запросы в формат OpenAI Responses API с поддержкой streaming.
- Для openrouter использует Anthropic Skin — ANTHROPIC_AUTH_TOKEN (Bearer). Флаги возможностей не пробрасываются.
OpenCode (anthropic, openai-compatible, fireworks, openrouter): Генерирует ~/.config/opencode/config.json через Vercel AI SDK. Использует нативный @ai-sdk/openai для реальных OpenAI API (автоопределение по baseUrl). Полная поддержка function calling. Для каждой модели генерируется modalities: { input: [...], output: ["text"] } из флагов возможностей.
Qwen CLI (openai-compatible, fireworks, openrouter): Генерирует ~/.qwen/settings.json со структурой OpenAI-совместимого провайдера. Требует baseUrl. Пробрасывает флаги возможностей через generationConfig.modalities.
Codex CLI: Генерирует ~/.codex/config.toml с wire_api: responses и model_providers, а профиль (model + model_provider) записывает в отдельный ~/.codex/default.config.toml (новый формат Codex CLI v0.134.0+). При project-области разделяет конфиг между глобальным и проектным. Поддерживает openai-compatible, fireworks, openrouter. Флаги возможностей не пробрасываются.
Copilot (все 4 типа провайдеров): Не записывает и не изменяет файл настроек. Весь конфиг передаётся через COPILOT_MODEL, COPILOT_PROVIDER_TYPE, COPILOT_PROVIDER_API_KEY, COPILOT_PROVIDER_BASE_URL. Типы fireworks и openrouter отображаются как COPILOT_PROVIDER_TYPE=openai. Для моделей семейства gpt-5 автоматически добавляется COPILOT_PROVIDER_WIRE_API=responses.
Goose (все 4 типа провайдеров): Не изменяет файл настроек. Весь конфиг через GOOSE_PROVIDER + GOOSE_MODEL + ключи провайдера. anthropic → ANTHROPIC_API_KEY; openrouter → OPENROUTER_API_KEY; fireworks/openai-compatible → OPENAI_API_KEY + OPENAI_HOST. Суффикс /v1 автоматически убирается из OPENAI_HOST (Goose сам дописывает /v1/chat/completions).

Conservative Config Merge: При mergeAgentConfigs=true (по умолчанию) адаптеры Claude Code, Qwen и OpenCode сохраняют неизвестные top-level ключи из существующего конфига. Перезаписываются только ключи, генерируемые AgentO. Вложенные объекты заменяются целиком, за исключением env — они мержатся flat (существующие переменные окружения, не управляемые AgentO, сохраняются). Copilot и Goose не затронуты (env-only, нет записи в файл). Codex использует собственную логику split-file merge и игнорирует этот флаг.

Бэкап и восстановление

Перед изменением любого конфига агента AgentO создаёт v2 manifest-бэкап в ~/.agento/backups/<agent>/<scope>.bak.json.

Если активный бэкап для того же agent/scope уже существует, запуск блокируется до agento restore -a <agent> -s <scope>. Это защищает original backup от перезаписи при повторных Independent-запусках.

В режиме Child оригинальный конфиг автоматически восстанавливается при выходе агента или получении SIGTERM/SIGINT.

В режиме Independent конфиг остаётся изменённым. Восстановите вручную через agento restore. Если файла конфига до запуска не было, restore удалит сгенерированный файл вместо записи пустого конфига.

Разработка

Настройка

git clone https://github.com/emaxe/agentO.git
cd agentO
npm install

Скрипты

npm run build      # Компиляция TypeScript в dist/
npm run dev        # Режим наблюдения
npm test           # Запуск всех тестов
npm run test:watch # Режим наблюдения для тестов
npm run typecheck  # Проверка типов TypeScript
npm run lint       # ESLint
npm run format     # Prettier

Архитектура

src/
├── adapters/         # Адаптеры конфигов для конкретных агентов
├── cli/commands/     # Реализация CLI-команд
├── config/           # Схема и хранилище конфига
├── launcher/         # Логика запуска агентов
├── profiles/         # Управление профилями
├── providers/        # Управление провайдерами
└── tui/              # Терминальный UI (Ink + React)

Устранение неполадок

Изменения в `src/` не применяются

Глобальная команда AgentO использует скомпилированный код из dist/, а не src/. После любых изменений исходников:

npm run build

Тесты проходят, но глобальная команда ведёт себя иначе

Папка dist/ устарела. Пересоберите:

npm run build

В конфиге Qwen CLI отображается "omni" вместо "openai"

Это был баг в версиях < 0.1.1. Обновитесь до последней версии или пересоберите.

Участие в проекте

Вклад приветствуется! Пожалуйста:

Форкните репозиторий
Создайте ветку с фичей
Напишите тесты для новой функциональности
Убедитесь, что все тесты проходят (npm test)
Отправьте pull request