Перейти к основному содержанию

​
Сопряжение, принадлежащее Gateway (вариант B)

При сопряжении, принадлежащем Gateway, Gateway является источником истины относительно того, каким узлам разрешено подключаться. UI (приложение для macOS, будущие клиенты) — это лишь фронтенды, которые одобряют или отклоняют ожидающие запросы. Важно: WS‑узлы используют сопряжение устройств (роль node) во время connect. node.pair.* — это отдельное хранилище сопряжений и оно не ограничивает WS‑рукопожатие. Только клиенты, которые явно вызывают node.pair.*, используют этот процесс.

​
Основные понятия

  • Pending request: узел запросил подключение; требуется одобрение.
  • Paired node: одобренный узел с выданным токеном аутентификации.
  • Transport: WS‑эндпоинт Gateway пересылает запросы, но не принимает решений о членстве. (Поддержка устаревшего TCP‑моста устарела/удалена.)

​
How pairing works

  1. Узел подключается к WS Gateway и запрашивает сопряжение.
  2. Gateway сохраняет pending request и генерирует node.pair.requested.
  3. Вы одобряете или отклоняете запрос (CLI или UI).
  4. При одобрении Gateway выдаёт новый токен (токены ротируются при повторном сопряжении).
  5. Узел переподключается с использованием токена и теперь считается «сопряжённым».
Ожидающие запросы автоматически истекают через 5 минут.

​
CLI workflow (headless friendly)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
nodes status показывает сопряжённые/подключённые узлы и их возможности.

​
API surface (gateway protocol)

Events:
  • node.pair.requested — генерируется при создании нового ожидающего запроса.
  • node.pair.resolved — генерируется при одобрении/отклонении/истечении запроса.
Methods:
  • node.pair.request — создать или повторно использовать ожидающий запрос.
  • node.pair.list — вывести список ожидающих + сопряжённых узлов.
  • node.pair.approve — одобрить ожидающий запрос (выдаёт токен).
  • node.pair.reject — отклонить ожидающий запрос.
  • node.pair.verify — проверить { nodeId, token }.
Notes:
  • node.pair.request является идемпотентным для каждого узла: повторные вызовы возвращают один и тот же ожидающий запрос.
  • Одобрение всегда генерирует новый токен; токен никогда не возвращается из node.pair.request.
  • Запросы могут включать silent: true как подсказку для автоматических процессов одобрения.

​
Auto-approval (macOS app)

Приложение для macOS может при необходимости попытаться выполнить тихое одобрение, когда:
  • запрос помечен как silent, и
  • приложение может проверить SSH‑подключение к хосту шлюза Gateway с использованием того же пользователя.
Если тихое одобрение не удаётся, используется обычный запрос «Одобрить/Отклонить».

​
Storage (local, private)

Состояние сопряжения хранится в каталоге состояния Gateway (по умолчанию ~/.openclaw):
  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json
Если вы переопределяете OPENCLAW_STATE_DIR, папка nodes/ перемещается вместе с ним. Примечания по безопасности:
  • Токены являются секретами; рассматривайте paired.json как чувствительные данные.
  • Ротация токена требует повторного одобрения (или удаления записи узла).

​
Transport behavior

  • Транспорт является статeless; он не хранит сведения о членстве.
  • Если Gateway офлайн или сопряжение отключено, узлы не могут выполнить сопряжение.
  • Если Gateway работает в удалённом режиме, сопряжение всё равно происходит с хранилищем удалённого Gateway.