# Удалённое управление

Удалённое управление позволяет сопряжённому браузеру или настольному клиенту использовать работающую серверную часть CodeNomad без открытия входящего сетевого порта. Не нужны пароль сервера, `--host` вне loopback или VPN. Это отдельный путь от [прямых подключений](remote-access.md).

## Запуск и сопряжение {#start-and-pair}

1. На хосте откройте **Настройки → Удалённый доступ**.
2. Выберите **Запустить удалённое управление**. Дождитесь **Готово к удалённым подключениям**; первое использование может занять время для подготовки идентичности туннеля и сертификата.
3. В **Подключить другое устройство** отсканируйте QR-код или нажмите **Копировать ссылку**, затем откройте одноразовую ссылку на нужном устройстве.
4. Сохраняйте данные сайта сопряжённого браузера. Снова откройте адрес туннеля для подключения, пока серверная часть работает.

Ссылка действует **пять минут** и срабатывает **один раз**. Считайте её учётными данными: любой использовавший её может стать сопряжённым устройством. Код находится во фрагменте URL, не в строке запроса. **Создать новую ссылку сопряжения** немедленно делает предыдущую неиспользованную ссылку недействительной. Остановка, завершение серверной части и сбой туннеля отменяют ожидающие ссылки сопряжения.

Для сопряжения другого настольного CodeNomad выберите **Подключить сервер CodeNomad** на его главной странице, вставьте ссылку в **URL сервера** и нажмите **Подключиться**. Ссылка сопряжения открывает своё окно даже по **Сохранить**, потому что её открытие использует код. В закладке сохраняется только origin туннеля; код не хранится. Проверка TLS для ссылок сопряжения остаётся включённой.

## Управление сопряжёнными устройствами {#paired-devices}

1. На хосте вернитесь в **Настройки → Удалённый доступ → Удалённое управление**.
2. Проверьте **Сопряжённые устройства** и время **Последняя активность**. Каждое устройство названо по платформе и браузеру, с которых выполнено сопряжение, например `iPhone · Safari`.
3. Нажмите **Отозвать** для устройства, которому больше нельзя подключаться.

Отзыв завершает текущие HTTP/SSE-подключения устройства и будущий доступ. Для восстановления выполните сопряжение по новой ссылке. Устройство истекает после **30 дней без использования**. При **лимите 32 устройства** новое сопряжение заменяет устройство с самой давней активностью и закрывает его подключения.

Серверная часть хранит хэши, не исходные учётные данные устройств, в `remote-control-devices.json` в базе конфигурации. Клиент хранит cookie устройства с областью хоста и атрибутами `Secure`, `HttpOnly`, `SameSite=Lax`. Срок в браузере может превышать серверный 30-дневный лимит бездействия; достоверен реестр. Очистка данных сайта, смена профиля браузера или приватный режим могут потребовать нового сопряжения.

Изменение пароля прямого доступа **не** отзывает устройства. **Остановить удалённое управление** отключает туннель, но сохраняет список устройств; используйте **Отозвать**, чтобы убрать авторизацию.

### Повторное сопряжение без потери места {#re-pair}

1. Если клиент показывает **Повторно сопрягите это устройство**, оставьте эту страницу открытой.
2. На хосте выберите **Создать новую ссылку сопряжения** и откройте в **том же браузере/профиле клиента**. Для сохранённого настольного сервера переподключитесь по свежей ссылке, чтобы использовать существующее хранилище удалённого окна.
3. Вернитесь на ожидающую страницу и нажмите **Проверить соединение**; проверка также повторяется, когда страница снова получает фокус.

Восстановление сохраняет открытую страницу и черновики; не повторяет неудачное действие. Перед повтором проверьте, сработала ли отправка, ответ или удаление. Пароль прямого доступа не восстанавливает сопряжение удалённого управления.

## Доступность и время жизни {#lifetime}

| Действие/состояние | Эффект |
| --- | --- |
| Запустить удалённое управление | Подключает эту серверную часть и запоминает выбор для будущих запусков. |
| Закрыть удалённый браузер | Не останавливает серверную часть хоста и не отзывает устройство. |
| Остановить удалённое управление | Отключает доступ и убирает автоматическое возобновление при запуске; сохраняет записи устройств. |
| Завершение серверной части / закрытие последнего настольного окна и выход из приложения | Удалённое управление становится недоступным. Общая служба OpenCode может продолжать работать, но не может предоставлять этот интерфейс через остановленную серверную часть. |
| Запуск после оставленного включённым удалённого управления | Переподключается в фоне без новой ссылки сопряжения. Установки, где его никогда не запускали, не включаются сами. |
| Неудачное возобновление или фатальный сбой туннеля | Сохранённый выбор остаётся, а хост показывает ошибку; значок обновления карточки удалённого управления перечитывает её состояние. **Запустить удалённое управление** повторяет попытку сейчас; **Остановить удалённое управление** очищает выбор. Иначе последующий запуск повторяет попытку. |

Автовозобновление ограничено одной серверной частью на каталог конфигурации. Не запускайте конкурирующие хосты с одной конфигурацией ради дополнительной ёмкости туннеля. Для доступности после выхода из настольного приложения разверните отдельно управляемый [отдельный сервер](server.md); удалённое управление — не независимый демон.

## Доступные и недоступные поверхности {#remote-surface}

Сопряжённые устройства могут использовать обычные API проектов/разговоров, отправлять запросы, просматривать файлы и отвечать на разрешения/формы с теми же проверками принадлежности. Сопряжение даёт мощный доступ, не ссылку просмотра. Оно никогда не предоставляет loopback-привилегии, хотя туннель перенаправляет трафик внутри хоста.

| Поверхность | Через удалённое управление |
| --- | --- |
| Обычный аутентифицированный интерфейс, рабочие пространства, разговоры и SSE | Доступны сопряжённому устройству. |
| Вход/выход по паролю, изменение пароля, локальная начальная настройка токеном | Недоступны; учётные данные устройства обязательны даже при отключённой прямой аутентификации. |
| Статус удалённого управления | Читается сопряжённым устройством; управление недоступно. Запуск/остановка, создание сопряжения, список устройств и отзыв остаются на пути доступа хоста. |
| Управление настольными удалёнными окнами/серверами и маршруты прокси | Недоступны (`/api/remote-servers/`, `/api/remote-proxy/`). |
| **Прокси содержимого** SideCar | Недоступен (`/sidecars/`). Это **не** означает блокировку всех API SideCar: сопряжённые клиенты всё ещё имеют доступ к API регистрации `/api/sidecars`. |
| Содержимое веб-предпросмотра | Доступно, пока на хосте включён **Веб-предпросмотр** (по умолчанию) в **Настройки → Удалённый доступ → Удалённое управление**. Адрес каждого предпросмотра открывает его страницу без сопряжения, поэтому держите его в тайне. Выключение переключателя останавливает обслуживаемые предпросмотры и их WebSocket; сопряжённые устройства скрывают **Открыть веб-предпросмотр** после перезагрузки страницы. |
| Мост автоматизации | Недоступен (`/api/opencode-plugin/`). Нативные возможности рабочего стола не становятся возможностями браузера. |
| Обновления соединения до WebSocket | Доступны только для веб-предпросмотра. |

Используйте должным образом защищённое [прямое подключение](remote-access.md), если нужны заблокированные поверхности прокси/WebSocket. Удалённое управление автоматически на этот путь не переключается.

## Ретранслятор и конфиденциальность {#relay-privacy}

CodeNomad использует [OpenTunnel](https://github.com/anomalyco/opentunnel) и занимает один случайный маршрут на общей идентичности туннеля компьютера по умолчанию. Остановка освобождает мост CodeNomad, не общую идентичность других приложений.

TLS завершается в серверной части CodeNomad. Ретранслятор передаёт шифротекст и не может читать содержимое приложения, но видит имена хостов, время соединений и объёмы трафика. Сертификат/закрытый ключ туннеля остаются на хосте. Защищайте хранилище туннеля хоста и конфигурацию CodeNomad как учётные данные; неугадываемый адрес — не авторизация.

`CODENOMAD_REMOTE_CONTROL_API` выбирает собственный API OpenTunnel; без значения используется размещённая служба. Это меняет развёртывание туннеля, не требования сопряжения и не заблокированные поверхности. Обращение с учётными данными и диагностикой см. в разделе [Безопасность](security.md).