Часть I. Самостоятельная настройка с нуля

Назначение. Эта часть не требует предыдущего практикума. Она ведёт от чистой Windows- или macOS-системы до локального голосового и экранного агента, а затем показывает три взаимозаменяемых маршрута LLM: прямой Ollama, Hermes API Server или минимальный local-agent-gateway.

Микрофон -> Sherpa-ONNX ASR -----------------------------+
Скриншот/экран -> Open-LLM-VTuber -> выбранный LLM endpoint |
v
ответ -> pyttsx3 -> динамики

Маршрут A: Open-LLM-VTuber -> Ollama:11434
Маршрут B: Open-LLM-VTuber -> Hermes:8642 -> выбранная Hermes-модель
Маршрут C: Open-LLM-VTuber -> local-agent-gateway:8642 -> Ollama:11434

Главное различие. Codex не является постоянным локальным HTTP gateway. Он может создать, настроить и проверить gateway, но Open-LLM-VTuber не может отправлять runtime-запросы непосредственно в текущий чат Codex.

Рекомендованный учебный маршрут. Сначала докажите прямой Ollama baseline. Затем добавьте ровно один gateway. Так ошибка всегда локализуется между уже проверенными границами.

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

winget install --id Microsoft.PowerShell --source winget
winget install --id Git.Git -e
winget install --id GitHub.cli -e
winget install --id Gyan.FFmpeg -e
winget install --id astral-sh.uv -e
# Ollama: установите официальное Windows-приложение или:
winget install --id Ollama.Ollama -e
# После установки закройте и заново откройте Terminal.

# Установите Homebrew с brew.sh, если его ещё нет.
brew install git gh ffmpeg uv
brew install --cask ollama
# Запустите Ollama из Applications один раз.
exec zsh

pwsh --version
git --version
gh --version
uv --version
ffmpeg -version
ollama --version
gh auth status

zsh --version
git --version
gh --version
uv --version
ffmpeg -version
ollama --version
gh auth status

Нормальный результат. Все version-команды завершаются с кодом 0. `gh auth status` может требовать `gh auth login`; токен нельзя копировать в отчёт.

# Рекомендуется официальный Codex Desktop installer.
# Для CLI используйте официальный установщик, показанный приложением/документацией.
codex --version
Set-Location C:\dev\agent-lab
codex

# Установите Codex Desktop для macOS либо официальный CLI.
codex --version
mkdir -p ~/dev/agent-lab
cd ~/dev/agent-lab
codex

Windows sandbox. Если CLI сообщает, что `codex-windows-sandbox-setup.exe` не найден, сначала обновите Codex и перезапустите терминал. Не обходите проблему постоянным полным разрешением. Для разовой read-only команды допустимо выбрать однократное выполнение вне сломанной sandbox только после проверки команды и cwd.

macOS permissions. Первый доступ Codex к каталогу Desktop/Documents, браузеру или автоматизации может вызвать системный диалог Privacy & Security. Разрешайте только нужный каталог или действие; Full Disk Access для практикума не требуется.

Работай как инженер в режиме контролируемого агента на Windows.
Текущая рабочая папка: C:\dev\agent-lab. Не предполагай, что команды другой ОС работают здесь.

Перед изменением файлов:
1. Покажи карту релевантной части репозитория и входные точки.
2. Сформулируй одну атомарную цель.
3. Перечисли файлы чтения и изменения.
4. Назови риски, предположения и реальные команды проверки.
5. Сначала покажи план. Не меняй файлы до моего явного «одобряю».

Ограничения:
- не используй sudo; не выполняй rm -rf, git reset --hard, git clean -fd и force push;
- не изменяй main и upstream без отдельного явного разрешения;
- не читай и не печатай .env, токены, SSH-ключи, cookies, keychain и полный conf.yaml;
- не трогай файлы вне текущего проекта;
- не ставь глобальные пакеты без отдельного обоснования;
- не скрывай ошибки и не заменяй тест утверждением;
- после изменения покажи краткий diff, реальный минимальный тест и git status --short;
- если требуется расширение scope, остановись и запроси новый атомарный шаг.

Классифицируй ошибки как environment, configuration, dependency, source или test limitation.
Не задавай вопросов, ответ на которые можно безопасно получить read-only проверкой. Останавливайся
только перед секретом, GUI-разрешением ОС, внешней публикацией или расширением scope.

Текущая задача: только инвентаризировать среду. Выполни Get-Location и версии git, gh, uv, ollama. Ничего не изменяй. Не печатай токены.

Работай как инженер в режиме контролируемого агента на macOS.
Текущая рабочая папка: ~/dev/agent-lab. Не предполагай, что команды другой ОС работают здесь.

Перед изменением файлов:
1. Покажи карту релевантной части репозитория и входные точки.
2. Сформулируй одну атомарную цель.
3. Перечисли файлы чтения и изменения.
4. Назови риски, предположения и реальные команды проверки.
5. Сначала покажи план. Не меняй файлы до моего явного «одобряю».

Ограничения:
- не используй sudo; не выполняй rm -rf, git reset --hard, git clean -fd и force push;
- не изменяй main и upstream без отдельного явного разрешения;
- не читай и не печатай .env, токены, SSH-ключи, cookies, keychain и полный conf.yaml;
- не трогай файлы вне текущего проекта;
- не ставь глобальные пакеты без отдельного обоснования;
- не скрывай ошибки и не заменяй тест утверждением;
- после изменения покажи краткий diff, реальный минимальный тест и git status --short;
- если требуется расширение scope, остановись и запроси новый атомарный шаг.

Классифицируй ошибки как environment, configuration, dependency, source или test limitation.
Не задавай вопросов, ответ на которые можно безопасно получить read-only проверкой. Останавливайся
только перед секретом, GUI-разрешением ОС, внешней публикацией или расширением scope.

Текущая задача: только инвентаризировать среду. Выполни pwd и версии git, gh, uv, ollama. Ничего не изменяй. Не читай Keychain.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)
# Откройте новый PowerShell
hermes --version
hermes doctor
hermes setup --portal

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
exec zsh
hermes --version
hermes doctor
hermes setup --portal

hermes profile create olv-runtime
olv-runtime setup
olv-runtime tools
# Для разработки отдельно:
hermes profile create coder
coder setup

hermes profile create olv-runtime
olv-runtime setup
olv-runtime tools
# Для разработки отдельно:
hermes profile create coder
coder setup

Ограничение toolset. API Server Hermes даёт доступ к инструментам агента. Для профиля `olv-runtime` отключите terminal, file, browser, code_execution, delegation и cronjob, если VTuber не должен управлять компьютером. Профиль разделяет состояние, но не является filesystem sandbox.

API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_KEY=<UNIQUE_LOCAL_KEY>
# CORS не задавайте, если браузер не вызывает Hermes напрямую.

olv-runtime gateway
# В другом окне:
Invoke-RestMethod http://127.0.0.1:8642/health

olv-runtime gateway
# В другом окне:
curl -fsS http://127.0.0.1:8642/health

Проведи настройку отдельного Hermes-профиля `olv-runtime` как loopback-only OpenAI-compatible API Server.
Сначала read-only проверь текущую версию Hermes и актуальный синтаксис через `hermes --help` и `hermes gateway --help`.
Не читай и не печатай существующие secret files. Не генерируй ключ в сообщении. Попроси меня один раз ввести новый локальный bearer key через безопасный локальный ввод.
Настрой host 127.0.0.1, port 8642, обязательную bearer-аутентификацию и минимальный toolset без terminal, file, browser, code_execution, delegation и cronjob.
Не ослабляй CORS. До изменения покажи точные параметры и план. После подтверждения запусти gateway, проверь /health, отрицательный запрос без auth и один обезличенный chat-completions smoke test. В отчёте покажи только статусы, request id и redacted key length.

Граница данных. Облачная модель получает содержимое prompt и переданные изображения. Локальный Ollama не отправляет inference-запрос в облако, но первоначальная загрузка модели требует сети.

New-Item -ItemType Directory -Force C:\dev\agent-lab | Out-Null
Set-Location C:\dev\agent-lab
git clone --recursive https://github.com/Open-LLM-VTuber/Open-LLM-VTuber.git
Set-Location .\Open-LLM-VTuber
git submodule status
git status --short

mkdir -p ~/dev/agent-lab
cd ~/dev/agent-lab
git clone --recursive https://github.com/Open-LLM-VTuber/Open-LLM-VTuber.git
cd Open-LLM-VTuber
git submodule status
git status --short

Не используйте Code → Download ZIP. Frontend является Git submodule. Обычный ZIP может дать `Detail Not Found` и лишить проект корректной Git-истории.

uv sync

uv sync

Set-Location C:\dev\agent-lab\Open-LLM-VTuber
uv sync
uv run run_server.py --verbose

cd ~/dev/agent-lab/Open-LLM-VTuber
uv sync
uv run run_server.py --verbose

ollama list
ollama pull qwen3-vl:4b
Invoke-RestMethod http://127.0.0.1:11434/api/tags | Select-Object -ExpandProperty models

ollama list
ollama pull qwen3-vl:4b
curl -fsS http://127.0.0.1:11434/api/tags

Порт занят. На Windows Ollama tray app и на macOS Ollama.app уже могут слушать 11434. Не запускайте второй `ollama serve`, если health check работает.

$body = @{model='qwen3-vl:4b'; messages=@(@{role='user';content='Ответь одним словом: готово'}); stream=$false} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri http://127.0.0.1:11434/v1/chat/completions -ContentType 'application/json' -Body $body

curl -sS http://127.0.0.1:11434/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"qwen3-vl:4b","messages":[{"role":"user","content":"Ответь одним словом: готово"}],"stream":false}'

Версия важнее примера. Не заменяйте весь `conf.yaml` фрагментом из другого релиза. Сначала найдите существующие ключи и их реальные отступы, затем меняйте только значения.

Copy-Item .\conf.yaml ".\conf.yaml.before-setup.$(Get-Date -Format yyyyMMdd-HHmmss)"
# Откройте файл в локальном редакторе, не выводите его в терминал.
uv run python -c "from pathlib import Path; import yaml; yaml.safe_load(Path('conf.yaml').read_text(encoding='utf-8')); print('YAML_OK')

cp conf.yaml "conf.yaml.before-setup.$(date +%Y%m%d-%H%M%S)"
# Откройте файл в локальном редакторе, не выводите его в терминал.
uv run python -c "from pathlib import Path; import yaml; yaml.safe_load(Path('conf.yaml').read_text()); print('YAML_OK')

Реальная ошибка, которую нужно узнавать. Если `basic_memory_agent` и `llm_provider` имеют одинаковый отступ, provider становится соседним ключом и Pydantic/YAML падает. Исправляйте только отступ конкретной строки, затем полностью разбирайте YAML.

Работай только с локальным игнорируемым conf.yaml Open-LLM-VTuber. Не печатай весь файл и секреты.
Сначала разберись с реальной YAML-структурой программно и покажи существующие пути для basic_memory_agent.llm_provider, openai_compatible_llm.base_url, llm_api_key и model. Не полагайся на путь из моего текста, если схема отличается.
Атомарная цель: настроить выбранный мной маршрут, изменив минимальное число scalar values. Создай timestamped backup. До изменения покажи безопасный redacted diff и дождись подтверждения. После изменения полностью распарсь YAML и проверь точные пути, показывая ключ как <redacted> и только его длину. Source, templates и dependencies не меняй.

Критерий. Уникальное число и смысл русской фразы распознаны приемлемо; в логах нет cloud request. Ошибки выбора микрофона — environment, неверный backend — configuration.

uv run python -c "import pyttsx3; e=pyttsx3.init(); [print(i, v.name, getattr(v,'languages',[])) for i,v in enumerate(e.getProperty('voices'),1)]

uv run python -c "import pyttsx3; e=pyttsx3.init(); [print(i, v.name, getattr(v,'languages',[])) for i,v in enumerate(e.getProperty('voices'),1)]

uv run python -c "import pyttsx3; e=pyttsx3.init(); v=next(x for x in e.getProperty('voices') if x.name=='Microsoft Irina Desktop'); e.setProperty('voice',v.id); e.say('Проверка локального синтеза 4827'); e.runAndWait(); print('TTS_COMPLETED')

# Замените <RUSSIAN_VOICE_NAME> только именем из предыдущего вывода.
uv run python -c "import pyttsx3; e=pyttsx3.init(); v=next(x for x in e.getProperty('voices') if x.name=='<RUSSIAN_VOICE_NAME>'); e.setProperty('voice',v.id); e.say('Проверка локального синтеза 4827'); e.runAndWait(); print('TTS_COMPLETED')

Неинтерактивная сессия. COMError на Windows или отсутствие слышимого звука в sandbox/SSH не доказывает поломку pyttsx3. Повторите тест в обычном пользовательском Terminal с доступом к аудиосессии. На macOS проверьте выбранный output device и системный голос.

Set-Location C:\dev\agent-lab
git clone --branch agent/local-gateway https://github.com/aka-gst/local-agent-gateway.git
Set-Location .\local-agent-gateway
uv sync --extra test
Copy-Item .\.env.example .\.env
# Заполните .env локально, не печатая его.
uv run pytest -q

cd ~/dev/agent-lab
git clone --branch agent/local-gateway https://github.com/aka-gst/local-agent-gateway.git
cd local-agent-gateway
uv sync --extra test
cp .env.example .env
# Заполните .env локально, не печатая его.
uv run pytest -q

GATEWAY_BEARER_TOKEN=<32 RANDOM BYTES, BASE64URL>
GATEWAY_ALLOWED_BACKENDS=ollama
GATEWAY_ALLOWED_MODELS=qwen3-vl:4b
GATEWAY_DEFAULT_BACKEND=ollama
GATEWAY_OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
GATEWAY_UPSTREAM_TIMEOUT_SECONDS=120
GATEWAY_MAX_REQUEST_BYTES=1048576

uv run local-agent-gateway
# Отдельное окно:
Invoke-RestMethod http://127.0.0.1:8642/health

uv run local-agent-gateway
# Отдельное окно:
curl -fsS http://127.0.0.1:8642/health

Почему timeout 120. При первом запросе qwen3-vl:4b может загружаться в память дольше 30 секунд. Сначала измерьте прямой Ollama-вызов; только затем увеличивайте timeout. `upstream unavailable` при рабочем Ollama часто является timeout, а не ошибкой модели.

Streaming. Open-LLM-VTuber фактически отправляет `stream=true`. Gateway должен передавать поток без накопления всего ответа, не пересылать клиентский Authorization в Ollama и закрывать upstream при disconnect.

Get-NetTCPConnection -State Listen -LocalPort 11434,8642,12393 -ErrorAction SilentlyContinue | Select-Object LocalAddress,LocalPort,OwningProcess

lsof -nP -iTCP:11434 -iTCP:8642 -iTCP:12393 -sTCP:LISTEN

Чего не доказывает UI-ответ. Сам ответ не доказывает маршрут. Нужны request id/HTTP 200 gateway и лог выбранного upstream без prompt/response содержимого.

Я хочу с нуля настроить локальную связку Open-LLM-VTuber + Ollama qwen3-vl:4b + sherpa_onnx_asr + pyttsx3_tts на <Windows|macOS>.
LLM-маршрут: <прямой Ollama|Hermes API Server|local-agent-gateway>.

Работай как контролируемый инженер. Самостоятельно выполняй все безопасные read-only проверки и не задавай вопросы, ответ на которые виден в документации, --help, репозитории или локальном состоянии. Перед каждой группой изменений покажи атомарную цель, точные файлы, redacted diff, риски и команды теста; жди моего «одобряю». После одобрения заверши группу целиком.

Не используй sudo, destructive Git, force push, изменение main/upstream, глобальные пакеты без обоснования. Не читай и не печатай .env, conf.yaml целиком, token, SSH, cookies или keychain. Секрет запрашивай только через безопасный локальный ввод и показывай лишь match/length. Не меняй source Open-LLM-VTuber, templates или dependencies, пока не доказан source defect и я отдельно не расширил scope.

Порядок:
1. Проверь ОС, shell, cwd, git, gh, uv, ffmpeg, ollama и выбранного агента. Классифицируй проблемы.
2. Получи Open-LLM-VTuber recursive clone в коротком несинхронизируемом пути; прочитай README/CLAUDE/pyproject/quick-start; покажи карту.
3. Выполни upstream baseline: uv sync, verbose server, HTTP 200, shutdown, source-tree unchanged.
4. Проверь Ollama, скачай qwen3-vl:4b только после подтверждения, выполни text-only smoke.
5. Создай backup conf.yaml и настрой минимальные реальные YAML paths выбранного маршрута; не заменяй файл шаблоном. Полностью распарсь YAML.
6. Настрой sherpa_onnx_asr. Получи список pyttsx3 voices без путей; выбери доступный русский системный голос, на Windows предпочти Microsoft Irina Desktop, на macOS используй фактически установленный русский голос.
7. Если выбран gateway: настрой loopback 127.0.0.1:8642, bearer auth, allowlists, request id, безопасные ошибки и streaming. Для Hermes отключи опасные toolsets runtime-профиля. Для local-agent-gateway запусти pytest.
8. Запусти компоненты в правильном порядке и выполни health checks.
9. Остановись для моих ручных действий только четыре раза: browser login, secret input, microphone/screen permission и подтверждение слышимого звука.
10. Проведи text, voice, TTS, 15-second loop и доступный vision smoke. Не выдавай NOT RUN за PASS.
11. Покажи sanitised evidence: версии, backend names, request id/status, transcript тестовой фразы, TTS user-confirmed, loop result, source-tree status. Не показывай полный prompt/response.
12. Останови сервисы в обратном порядке и предложи ровно один следующий шаг.

Если команда одной ОС не подходит, сначала переведи её в native PowerShell 7 или zsh. Bash heredoc `<<'PY'` не используй в PowerShell. При любой ошибке покажи реальный вывод и не продолжай к следующей границе, пока текущая не доказана.

ОС: Windows / macOS
Маршрут: direct Ollama / Hermes / local-agent-gateway
Ollama model: <exact tag>
ASR: sherpa_onnx_asr — PASS / FAIL / NOT PROVEN
TTS: pyttsx3_tts, voice=<name> — PASS / FAIL / NOT PROVEN
Gateway: HTTP status=<code>, request_id=<sanitized>
Vision: PASS / FAIL / NOT RUN; method=<screen/camera/file>
Loop control: PASS / FAIL / NOT RUN; observation=15 s
Source tree: unchanged / known diff
Secrets printed: no
Не доказано: <ограничения>
Следующий атомарный шаг: <ровно один>

Правило версий. Команды этого руководства сверены с локальным Open-LLM-VTuber 1.2.1 и окружением практикума. Если точный YAML path или CLI-флаг отличается, сначала прочитайте локальные README/CLAUDE/pyproject и --help, затем меняйте только фактически существующий ключ.