Сетевое взаимодействие и обнаружение

Gateway-Owned Pairing

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

Концепции

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

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

  1. Узел подключается к WS Шлюза и запрашивает сопряжение.
  2. Шлюз сохраняет ожидающий запрос и генерирует событие node.pair.requested.
  3. Вы утверждаете или отклоняете запрос (CLI или UI).
  4. При утверждении Шлюз выдает новый токен (токены обновляются при повторном сопряжении).
  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 (протокол шлюза)

События:

  • 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-подключение к хосту шлюза, используя того же пользователя.

Если тихое утверждение не удается, происходит откат к обычному запросу «Утвердить/Отклонить».

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

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

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

Если вы переопределите OPENCLAW_STATE_DIR, папка nodes/ переместится вместе с ним. Замечания по безопасности:

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

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

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

Сетевая модельОбнаружение и Транспорты