Сопряжение, принадлежащее 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.