XuanShu API

Настройка Hermes

Подключите Hermes к XuanShu API через канал Anthropic (Claude) или OpenAI (Codex): установка одной командой, ручная установка, конфигурация, минимальный тест, откат и диагностика.

1. Подготовьте API Key

Если аккаунта ещё нет, зарегистрируйтесь на /register.
Создайте на /keys отдельный ключ только для Hermes; при необходимости задайте квоту, срок действия и ограничения доступа.
Сразу сохраните полный ключ в надёжном месте: позже консоль может показывать только скрытое значение. Не помещайте его в репозиторий, снимок экрана или переписку.

2. Установка одной командой (рекомендуется)

После запуска скрипт попросит выбрать канал и вставить API Key, затем запишет ~/.hermes/config.yaml. Требуется sudo. Исходный код доступен по /install/hermes.sh для предварительной проверки.

curl -fsSL https://www.xuanshuapi.com/install/hermes.sh | sudo bash

Альтернатива: установить Hermes вручнуюРазверните, если нужно проверить каждую команду или скрипт недоступен

3. Установка вручную

Установите через pipx:
```
pipx install hermes-agent
hermes --version
```
Выведенная версия означает успешную установку.

4. Выберите канал и запишите конфигурацию

Модели обновляются, актуальный список смотрите на /available-channels. Существующая конфигурация будет перезаписана — сделайте резервную копию заранее.

mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
model:
  default: claude-opus-4-7
  provider: xuanshu-claude
providers:
  xuanshu-claude:
    api_mode: anthropic_messages
    base_url: https://www.xuanshuapi.com
    api_key: <YOUR_API_KEY>
    default_model: claude-opus-4-7
    models:
      - claude-opus-4-7
EOF

mkdir -p ~/.hermes
cat > ~/.hermes/config.yaml << 'EOF'
model:
  default: gpt-5.6-sol
  provider: xuanshu-codex
providers:
  xuanshu-codex:
    api_mode: codex_responses
    base_url: https://www.xuanshuapi.com/v1
    api_key: <YOUR_API_KEY>
    default_model: gpt-5.6-sol
    models:
      - gpt-5.6-sol
EOF

5. Выполните минимальный тест

В каталоге проекта выполните команду ниже, чтобы запустить Hermes, задайте любой вопрос и убедитесь, что получен ответ.

hermes

6. Критерии успеха

Hermes запускается нормально и возвращает ответ модели; на /usage виден успешный запрос выбранной модели; отсутствуют 404, 401/403 и 429. Переходите к реальному проекту только после всех трёх проверок.

7. Откатите конфигурацию

Сохраните резервную копию файла конфигурации и очистите связанные переменные окружения в текущем терминале, затем откройте новый login shell.

mv ~/.hermes/config.yaml ~/.hermes/config.yaml.xuanshu-backup
unset ANTHROPIC_API_KEY ANTHROPIC_BASE_URL \
  OPENAI_API_KEY OPENAI_BASE_URL
exec "$SHELL" -l

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

Сначала запишите код статуса, время запроса, ID модели и запись на /usage. Перед передачей логов скройте полный ключ.

Симптом	Проверка	Решение
404	base_url канала Anthropic должен быть строго https://www.xuanshuapi.com (без /v1); канал Codex должен включать /v1.	Исправьте base_url для нужного канала, перезапустите Hermes и повторите.
401 / 403	Убедитесь, что api_key — это полный, неусечённый ключ и он не истёк и не отозван.	Скопируйте или создайте новый ключ на /keys.
Модель недоступна	С тем же ключом проверьте точный ID модели и текущую видимость на /available-channels.	Обновите default и default_model; если модель временно недоступна, выберите доступную модель того же протокола.
429	Проверьте баланс, лимиты ключа и число параллельных запросов на /usage.	Уменьшите параллелизм и дождитесь восстановления окна лимита; используйте ограниченный backoff только для 429.
Конфигурация не применяется	Убедитесь, что запись попала в ~/.hermes/config.yaml и Hermes был перезапущен.	Перезапустите Hermes; уже открытые сессии не перечитывают файл автоматически после записи скриптом.
pipx не найден	pipx не установлен или не в PATH.	Установите pipx (python3 -m pip install --user pipx), затем откройте терминал заново.