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

В сопряжении, принадлежащем Gateway, Gateway является источником истины о том, какие узлы разрешены для присоединения. UI (приложение macOS, будущие клиенты) - это просто фронтенды, которые одобряют или отклоняют ожидающие запросы.

Важно: WS узлы используют сопряжение устройств (роль node) во время connect. node.pair.* - это отдельное хранилище сопряжения и не контролирует WS handshake. Только клиенты, которые явно вызывают node.pair.*, используют этот поток.

Концепции

  • Ожидающий запрос: узел попросил присоединиться; требуется одобрение.
  • Сопряженный узел: одобренный узел с выданным токеном аутентификации.
  • Транспорт: конечная точка Gateway WS пересылает запросы, но не принимает решения о членстве. (Поддержка legacy TCP моста устарела/удалена.)

Как работает сопряжение

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

Ожидающие запросы автоматически истекают через 5 минут.

Рабочий процесс CLI (дружественный к headless)

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 (протокол gateway)

События:

  • node.pair.requested — испускается при создании нового ожидающего запроса.
  • node.pair.resolved — испускается, когда запрос одобрен/отклонен/истек.

Методы:

  • node.pair.request — создать или повторно использовать ожидающий запрос.
  • node.pair.list — список ожидающих + сопряженных узлов.
  • node.pair.approve — одобрить ожидающий запрос (выдает токен).
  • node.pair.reject — отклонить ожидающий запрос.
  • node.pair.verify — проверить \{ nodeId, token \}.

Примечания:

  • node.pair.request идемпотентен для каждого узла: повторные вызовы возвращают тот же ожидающий запрос.
  • Одобрение всегда генерирует свежий токен; токен никогда не возвращается из node.pair.request.
  • Запросы могут включать silent: true как подсказку для потоков автоодобрения.

Автоодобрение (приложение macOS)

Приложение macOS может опционально попытаться тихое одобрение, когда:

  • запрос помечен silent, и
  • приложение может проверить SSH соединение к хосту gateway, используя того же пользователя.

Если тихое одобрение не удается, оно откатывается к обычному приглашению "Одобрить/Отклонить".

Хранилище (локальное, приватное)

Состояние сопряжения хранится в каталоге состояния Gateway (по умолчанию ~/.openclaw):

  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json

Если вы переопределяете OPENCLAW_STATE_DIR, папка nodes/ перемещается вместе с ним.

Примечания по безопасности:

  • Токены являются секретами; обращайтесь с paired.json как с конфиденциальным.
  • Ротация токена требует повторного одобрения (или удаления записи узла).

Поведение транспорта

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