251006_zeptoclaw+yGPT

Сводный конспект: ZeptoClaw + YandexGPT через прокси

Дата: 2026-10-06

1. Архитектура

ZeptoClaw (Docker)  →  YandexGPT_to_OpenAI (Docker, порт 8520)  →  Yandex Cloud API
     контейнер              контейнер y2o                              llm.api.cloud.yandex.net

• ZeptoClaw — агентный фреймворк, работает в контейнере.

• YandexGPT_to_OpenAI — локальный прокси, транслирует OpenAI-формат в Yandex API.

• Yandex Cloud — целевой API, принимает запросы с Api-Key и folder_id.

2. Установка Docker на Debian

# Официальный репозиторий Docker
sudo apt remove docker.io docker-compose docker-doc podman-docker containerd runc
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Важно: docker-compose-plugin даёт команду docker compose (через пробел), а не docker-compose.

3. Прокси YandexGPT_to_OpenAI

Клонирование и запуск:

git clone https://github.com/sazonovanton/YandexGPT_to_OpenAI
cd YandexGPT_to_OpenAI
python3 utils/tokens.py          # генерирует data/tokens.json
docker compose up -d
docker compose logs              # проверить, что слушает 0.0.0.0:8520

GNU:$ nano 8.4 docker-compose.yml # редактирование окружения (чтоб не светить ключи)

services:
  y2o:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: y2o
    environment:
      - Y2O_SecretKey=${Y2O_SECRET_KEY}
      - Y2O_CatalogID=b1g6p77ueu8g3vkat3at
      - Y2O_BringYourOwnKey=false
      - Y2O_ServerURL=http://127.0.0.1:8520
      - Y2O_LogFile=logs/y2o.log
      - Y2O_LogLevel=INFO
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      # - ./certs:/app/certs
    ports:
      - "8520:8520"
    restart: unless-stopped

Токен из data/tokens.json (пример):

<токен из data/tokens.json>

Проверка прокси:

tok=$(jq -r '.. | .token? // empty' data/tokens.json | head -1)
curl http://localhost:8520/v1/models -H "Authorization: Bearer $tok" | jq .

4. Конфиг ZeptoClaw (~/zeptoclaw-data/config.json)

{
  "providers": {
    "openai": {
      "api_key": "<токен из data/tokens.json>",
      "api_base": "http://host.docker.internal:8520/v1",
      "model": "yandexgpt/latest"
    }
  },
  "agents": {
    "defaults": {
      "model": "yandexgpt/latest"
    }
  }
}

Ключевые моменты:

• providers.openai.model — чистое имя yandexgpt/latest без префикса openai/.

• agents.defaults.model — тоже чистое yandexgpt/latest; префикс openai/ ZeptoClaw не срезает и передаёт в прокси, Yandex отвечает invalid model_uri.

• api_key — токен прокси, а не Yandex API-ключ.

• api_base — http://host.docker.internal:8520/v1.

5. Запуск ZeptoClaw

docker rm -f zeptoclaw-agent-a

docker run -d --name zeptoclaw-agent-a \
  -e HOME=/data \
  -v ~/zeptoclaw-data:/data/.zeptoclaw \
  -p 3000:3000 \
  -p 8080:8080 \
  -p 9090:9090 \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/qhkm/zeptoclaw:latest \
  zeptoclaw gateway

Обязательные флаги:

6. Проверка работы

# Диагностика
docker exec -it -e HOME=/data zeptoclaw-agent-a zeptoclaw doctor

# Отправить сообщение
docker exec -it -e HOME=/data zeptoclaw-agent-a zeptoclaw agent -m "Привет!"

# Логи gateway
docker logs zeptoclaw-agent-a

Ожидаемый результат: ответ от YandexGPT в терминале.

7. Управление контейнером

docker ps                        # работающие контейнеры
docker ps -a                     # все, включая остановленные
docker logs -f zeptoclaw-agent-a # логи в реальном времени
docker stop zeptoclaw-agent-a    # остановить (данные сохранятся)
docker start zeptoclaw-agent-a   # запустить снова
docker rm -f zeptoclaw-agent-a   # удалить (данные в volume остаются)
docker restart zeptoclaw-agent-a # перезапустить

8. Грабли, на которые мы наступили

9. Быстрый чек-лист для воспроизведения

1. Установить Docker + docker-compose-plugin.

2. Клонировать YandexGPT_to_OpenAI, запустить python3 utils/tokens.py.

3. docker compose up -d, проверить curl http://localhost:8520/v1/models.

4. Создать ~/zeptoclaw-data/config.json с правильными полями.

5. Запустить ZeptoClaw с -e HOME=/data, -v, --add-host.

6. Проверить zeptoclaw doctor → zeptoclaw agent -m "Привет!".

mcp (встроенный)

docker rm -f zeptoclaw-agent-a

docker run -d --name zeptoclaw-agent-a \
  -i \
  -e HOME=/data \
  -v ~/zeptoclaw-data:/data/.zeptoclaw \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/qhkm/zeptoclaw:latest \
  zeptoclaw mcp-server

#
docker ps | grep zeptoclaw
8c194aee42ae   ghcr.io/qhkm/zeptoclaw:latest   "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes   8080/tcp, 9090 tcp zeptoclaw-agent-a

#
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | docker exec -i zeptoclaw-agent-a zeptoclaw mcp-server
2026-10-06T19:57:14.980974Z  INFO zeptoclaw::kernel: Assembled provider chain provider_chain=openai
2026-10-06T19:57:14.987143Z  INFO zeptoclaw::kernel: Using native runtime for shell commands
2026-10-06T19:57:14.987451Z  INFO zeptoclaw::cron: Cron service started
2026-10-06T19:57:14.996288Z  INFO zeptoclaw::tools::registry: Registering tool tool=echo
2026-10-06T19:57:14.996295Z  INFO zeptoclaw::tools::registry: Registering tool tool=read_file
...
2026-10-06T19:57:14.998124Z  INFO zeptoclaw::kernel::registrar: Registered 20 tools (0 external)
2026-10-06T19:57:14.998133Z  INFO zeptoclaw::kernel: Kernel boot: 20 tools registered
{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{}},"protocolVersion":"2024-11-05","serverInfo":{"name":"zeptoclaw","version":"0.9.2"}}}