Инструкция запуска Alice Agent Gateway

Страница для двух ролей: админ поднимает сервер и выпускает токен, клиент создает навык Алисы и запускает локальный агент рядом со своим кодовым агентом.

Адреса для настройки

Backend навыка Алисыhttps://alisa.zhdandesignbureau.ru/alice/webhook
OAuth authorize URLhttps://alisa.zhdandesignbureau.ru/oauth/authorize
OAuth token URLhttps://alisa.zhdandesignbureau.ru/oauth/token
Local agent WebSocketwss://alisa.zhdandesignbureau.ru/agent/connect

Для админа сервера

1

Поднять gateway

На сервере должен быть публичный HTTPS-домен. Для локальной разработки подойдет http://127.0.0.1:3000, но Яндекс.Навык снаружи сможет ходить только в публичный HTTPS.

npm install
PUBLIC_BASE_URL=https://alisa.zhdandesignbureau.ru ADMIN_TOKEN=aR3xQFadhgpP0r6vh0B8NjemtBvmSReeY2HKZpl8 npm run dev
2

Получить от клиента Skill ID

Клиент создает навык в консоли Яндекс Диалогов и передает вам его skill_id. После этого вы регистрируете навык в gateway.

curl -sS -X POST https://alisa.zhdandesignbureau.ru/admin/skills \
  -H 'Authorization: Bearer aR3xQFadhgpP0r6vh0B8NjemtBvmSReeY2HKZpl8' \
  -H 'Content-Type: application/json' \
  -d '{"skillId":"CLIENT_SKILL_ID","tenantName":"Client Name"}'
3

Выпустить токен локального агента

Из ответа предыдущей команды возьмите tenant.id. Секретный token показывается один раз и передается клиенту по защищенному каналу.

curl -sS -X POST https://alisa.zhdandesignbureau.ru/admin/agents \
  -H 'Authorization: Bearer aR3xQFadhgpP0r6vh0B8NjemtBvmSReeY2HKZpl8' \
  -H 'Content-Type: application/json' \
  -d '{"tenantId":"TENANT_ID","name":"Client local machine"}'
4

Отключить клиента при необходимости

Для неоплаты или компрометации отключайте tenant или конкретный agent token. Токены в базе хранятся только в виде hash.

curl -sS -X POST https://alisa.zhdandesignbureau.ru/admin/tenants/TENANT_ID/suspend \
  -H 'Authorization: Bearer aR3xQFadhgpP0r6vh0B8NjemtBvmSReeY2HKZpl8'

curl -sS -X POST https://alisa.zhdandesignbureau.ru/admin/agents/AGENT_ID/revoke \
  -H 'Authorization: Bearer aR3xQFadhgpP0r6vh0B8NjemtBvmSReeY2HKZpl8'

Для клиента с Алисой

Настройка Яндекс.Навыка

1

Откройте консоль Яндекс Диалогов и создайте приватный навык.

2

В поле Backend укажите:

https://alisa.zhdandesignbureau.ru/alice/webhook
3

В настройках авторизации укажите OAuth endpoints:

https://alisa.zhdandesignbureau.ru/oauth/authorize
https://alisa.zhdandesignbureau.ru/oauth/token

Client ID для MVP: alice-local-gateway. Client Secret должен совпадать с настройкой сервера.

4

Передайте админу skill_id, получите от него AGENT_TOKEN и опубликуйте навык как приватный для тестирования.

Запуск локального агента

Агент запускается на той же машине, где доступен Codex или другой локальный кодовый агент.

npm run agent -- start \
  --server wss://alisa.zhdandesignbureau.ru/agent/connect \
  --token AGENT_TOKEN \
  --workdir /path/to/project

Если нужно вызвать конкретный бинарь агента, добавьте:

npm run agent -- start \
  --server wss://alisa.zhdandesignbureau.ru/agent/connect \
  --token AGENT_TOKEN \
  --workdir /path/to/project \
  --command codex
Без --command запускается безопасный echo-adapter: он подтверждает получение команды, но не выполняет локальные процессы.

Защита и правила MVP

Что защищает сервер

  • Проверяет session.skill_id от Алисы.
  • Проверяет OAuth-связку пользователя Алисы.
  • Проверяет статус tenant: active или suspended.
  • Проверяет revocable token локального агента.
  • Не логирует agent token и OAuth token.

Что нельзя делать голосом в MVP

  • Deploy, delete, reset, commit без отдельного подтверждения.
  • Изменение секретов и production-настроек.
  • Запуск произвольного shell через gateway.
Команды, похожие на destructive actions, переводятся в waiting_approval.

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

1

Проверить сервер

curl -sS https://alisa.zhdandesignbureau.ru/health
2

Проверить jobs

curl -sS https://alisa.zhdandesignbureau.ru/admin/jobs \
  -H 'Authorization: Bearer aR3xQFadhgpP0r6vh0B8NjemtBvmSReeY2HKZpl8'
3

Проверить голосом

Скажите Алисе: “запусти навык …”, затем: “запусти кодекса и проверь проект”. После этого спросите: “статус задачи”.