Руководство по интеграции через REST API

Для команд, встраивающих Qwen Code в собственный продукт поверх HTTP: запустите qwen serve как бэкенд и управляйте им из собственного фронтенда.

Эта страница — отправная точка. Полный справочник маршрутов находится в qwen-serve-protocol.md; внутреннее устройство описано в углублённом руководстве по демону; рабочий пример на TypeScript — в examples/daemon-client-quickstart.md.

Какие пути существуют

Шесть способов построения на базе демона, разделённых одним вопросом — какую часть фронтенда вы контролируете?

Headless qwen -p и ACP через stdio для редакторов — это отдельные пути интеграции. Каналы и расширения также могут работать через демон; см. руководство по каналам и справочник расширений.

Что нужно знать перед проектированием

Демон не выполняет инференс внутри своего процесса. Он порождает дочерние процессы qwen --acp и выступает посредником между ними и HTTP. Он запускает входной скрипт CLI под тем же бинарём Node, используя QWEN_CLI_ENTRY или, иначе, process.argv[1]. Встраиваемый Node-бэкенд должен указывать в QWEN_CLI_ENTRY путь к установленному входному скрипту Qwen CLI; поиск qwen в PATH не производится. Отсутствие точки входа проявляется как MissingCliEntryError.

В установившемся режиме существует один дочерний процесс на активное рабочее пространство, а не по одному на сессию. Каждая сессия в рабочем пространстве мультиплексируется на этот дочерний процесс и разделяет его процесс, состояние OAuth, файловый кэш и разбор иерархической памяти. Таким образом, домен отказа — это рабочее пространство: если дочерний процесс завершается, все мультиплексированные на него сессии уничтожаются вместе. Рассчитывайте контейнер на демон плюс один дочерний процесс на зарегистрированное рабочее пространство, с запасом на один дополнительный дочерний процесс на среду выполнения при переключении канала. Когда сессии должны отказывать независимо, запускайте отдельные демоны — --max-sessions ограничивает параллелизм, а не радиус поражения.

Аутентификация рассчитана на одного оператора. Runtime bearer-токен предоставляет доступ ко всему bearer-защищённому API, а доверенный loopback-вызывающий получает полные полномочия, включая выполнение кода от имени пользователя демона. Модели принципала для каждого конечного пользователя нет. Если вы размещаете это за мультипользовательским продуктом, ваш бэкенд отвечает за идентификацию пользователей и не должен передавать токен демона в браузеры. Контейнеризированное и мультитенантное развёртывание явно отложено — см. «v0.16-alpha known limits» в руководстве пользователя.

Настроенный вход webhook канала (POST /channels/:channelName/webhooks/:source) использует собственную аутентификацию x-qwen-webhook-secret до bearer-аутентификации; он неактивен, пока не настроен источник webhook канала.

Запуск демона

export QWEN_SERVER_TOKEN="$(openssl rand -hex 32)"
 
qwen serve --no-web --require-auth \
  --hostname 0.0.0.0 --port 4170 \
  --workspace /srv/project

--no-web сохраняет перечисленные ниже маршруты, но отключает ресурсы Web Shell и зависимые поверхности: на macOS — маршруты /live/* и сокет /live/host, а на каждой платформе — GET /mcp-app-sandbox. Передавайте токен через переменную окружения, а не через --token, который доступен любому локальному пользователю через /proc/<pid>/cmdline.

Примеры Bash ниже передают заголовок Authorization через файловый дескриптор с помощью встроенной команды printf оболочки, не включая токен в аргументы curl.

Маршруты, которые реально использует интеграция

Большая часть того, что регистрирует демон, существует для работы Web Shell — операции git, установка расширений, доверие к рабочему пространству, голос, запланированные задачи — и меняется вместе с этим UI. Нижеприведённое подмножество на порядок меньше.

Это то, что нужно REST-интеграции. Остальное считайте внутренним.

Обнаружение

Жизненный цикл сессии

Промптинг и потоковая передача

Разрешения

Контекст рабочего пространства только для чтения

Покрытие справочника. 17 из 25 вышеперечисленных маршрутов имеют отдельные разделы. Из 8 отмеченных иначе некоторые упомянуты лишь вскользь, а три отсутствуют полностью: GET /session/:id/pending-prompts, POST /session/:id/permission/:requestId и GET /workspace/tools. Закрытие этого пробела отслеживается в #11359 .

Минимальный поток

1. Предварительный запрос. Прочитайте workspaceCwd (чтобы не передавать cwd при создании) и policy.permission (чтобы знать, кто может отвечать на запросы разрешений).

curl -sH @<(printf 'Authorization: Bearer %s\n' "$QWEN_SERVER_TOKEN") http://daemon:4170/capabilities

2. Создание сессии. Используйте sessionScope: "thread", если вызывающие не должны разделять один разговор — значение по умолчанию "single" заставляет повторное создание в том же рабочем пространстве переиспользовать существующую сессию, сериализуя независимых вызывающих через одну очередь.

curl -sX POST http://daemon:4170/session \
  -H @<(printf 'Authorization: Bearer %s\n' "$QWEN_SERVER_TOKEN") -H 'Content-Type: application/json' \
  -d '{"sessionScope":"thread"}'
# → {"sessionId":"…","workspaceCwd":"/srv/project","attached":false}

3. Подписка до отправки промпта. Last-Event-ID: 0 воспроизводит с самого старого сохранённого события — так вы ловите события, возникшие между созданием и подпиской, в частности model_switch_failed. При подключении (значение по умолчанию sessionScope: "single" переиспользует существующую сессию) это событие — единственный сигнал того, что некорректный modelServiceId был отклонён, потому что ошибка намеренно не передаётся как HTTP-ошибка. При новом создании с modelServiceId — чего тело шага 2 не содержит — тело 200 также содержит modelApplied, false если переключение было отклонено, и это детерминированный сигнал для действия, в отличие от события на кольце с ограниченным буфером. Создание без modelServiceId вообще не имеет ключа modelApplied.

curl -N http://daemon:4170/session/$SID/events \
  -H @<(printf 'Authorization: Bearer %s\n' "$QWEN_SERVER_TOKEN") \
  -H 'Accept: text/event-stream' -H 'Last-Event-ID: 0'

Каждая строка data: — это полный Envelope на одной строке; type Envelope совпадает со строкой event:.

Воспроизведение ограничено --event-ring-size и фиксированным байтовым бюджетом 8 МиБ на подписку. Если поток выдаёт state_resync_required с reason: "replay_budget_exceeded", восстановитесь через POST /session/:id/load, а не считайте воспроизведение завершённым.

4. Промптинг. 202 означает допуск, а не завершение. Соотнесите turn_complete / turn_error в потоке по promptId. Читайте stopReason в turn_complete; в turn_error читайте message и необязательные code / errorKind — см. POST /session/:id/prompt.

curl -sX POST http://daemon:4170/session/$SID/prompt \
  -H @<(printf 'Authorization: Bearer %s\n' "$QWEN_SERVER_TOKEN") -H 'Content-Type: application/json' \
  -d '{"prompt":[{"type":"text","text":"What does src/main.ts do?"}]}'
# → 202 {"promptId":"…","lastEventId":42}

5. Ответы на запросы разрешений. Когда агент хочет выполнить инструмент и его режим одобрения требует подтверждения, он выдаёт permission_request, и ход блокируется, пока кто-то не ответит или вы не отмените — по умолчанию таймаута нет (--permission-response-timeout-ms по умолчанию 0 = ждать бесконечно), поэтому неотвеченный запрос продолжает занимать слот в очереди промптов сессии, пока вы не отмените или не закроете сессию. Установите собственный дедлайн, если потоку он нужен.

Режим — это собственная настройка Qwen дочернего процесса tools.approvalMode, разрешаемая из настроек хоста демона и каталога --workspace; демон ничего не фиксирует при запуске. По умолчанию auto, который одобряет один класс вызовов инструментов без спрашивания — те не выдают permission_request вообще — и продолжает спрашивать для остальных. Недоверенная папка рабочего пространства принудительно переключается на default (спрашивать), поэтому одна инсталляция видит эти события, а другая нет, и GET /capabilities сообщает политику посредничества голосов, а не режим одобрения, так что предварительный запрос не скажет, в какой позиции вы находитесь. Если ваша интеграция зависит от гейтинга одобрения, зафиксируйте tools.approvalMode явно и решите заранее, как он отвечает: автоодобрение уже может действовать без того, чтобы кто-либо его выбирал.

Отвечайте на маршруте сессии: он маршрутизируется к среде выполнения, владеющей сессией, поэтому работает при любой конфигурации рабочего пространства.

curl -sX POST http://daemon:4170/session/$SID/permission/$REQUEST_ID \
  -H @<(printf 'Authorization: Bearer %s\n' "$QWEN_SERVER_TOKEN") -H 'Content-Type: application/json' \
  -d '{"outcome":{"outcome":"selected","optionId":"proceed_once"}}'

6. Закрытие. DELETE /session/$SID → 204. Сессия на диске сохраняется.

Эксплуатация