1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
15 KiB
Прямой удалённый доступ
Прямой доступ подключается к HTTP/HTTPS-слушателям CodeNomad с паролем сервера. Он отделён от удалённого управления: сопряжению не нужны привязка к LAN или входящий порт, и ни один путь не переключается незаметно на другой.
Выбор пути доступа
| Путь | Чем вы управляете |
|---|---|
| Браузер на том же компьютере | Сохраните loopback-привязку; используйте напечатанный локальный URL. |
| LAN или VPN | Привяжите доступный интерфейс, ограничьте брандмауэр нужными клиентами и используйте доверенный HTTPS. VPN не настраивает слушатель CodeNomad за вас. |
| Перенаправление SSH | Оставьте серверную часть на loopback; перенаправьте её фактически напечатанный порт. Туннель защищает транспорт, но не заменяет аутентификацию CodeNomad. |
| Обратный прокси | Оставьте серверную часть на частном/loopback-интерфейсе; завершайте доверенный TLS на прокси, защитите участок до серверной части и поддерживайте длительные SSE и WebSockets, необходимые инструментам прямого доступа. |
| Удалённое управление | Сопрягите устройство с хоста; более узкая поверхность и время жизни описаны в удалённом управлении. |
Привязка не создаёт правила брандмауэра, перенаправление портов, DNS или VPN. Не публикуйте неаутентифицированный HTTP-слушатель в Интернет. Корень рабочего пространства — не защитная песочница; прочитайте безопасность перед открытием сервера.
Включение прямого доступа
- На хосте откройте Настройки → Удалённый доступ и раскройте Прямой доступ (локальная сеть, для опытных).
- В Пароль сервера выберите Установить пароль или Изменить пароль, введите Новый пароль и Подтвердите пароль, затем Сохранить пароль. Пароли, переданные при запуске, здесь менять нельзя; см. безопасность.
- Включите Разрешить подключения с других IP в Режим прослушивания. Прочитайте предупреждение о перезапуске и выберите Перезапустить сейчас, только когда готовы к временному прерыванию.
- После перезапуска нажмите Обновить и проверьте Доступные адреса. Откройте доступный HTTPS-адрес на другом устройстве или выберите Показать QR на хосте и отсканируйте другим устройством, затем войдите.
Это меняет режим прямого прослушивания хоста, а не один проект и не удалённое управление. Раздел автоматически раскрывается, пока сервер слушает вне localhost. Если автоперезапуск недоступен, перезапустите CodeNomad вручную; отдельные развёртывания должны согласованно задавать --host при запуске. Для закрытия доступа выключите переключатель и перезапустите либо запустите CLI заново с loopback-привязкой. Это не отзывает сопряжённые устройства удалённого управления.
Матрица привязки слушателей
--host по умолчанию равен 127.0.0.1; localhost нормализуется в этот адрес. Для включённых слушателей действуют следующие правила:
| Запуск/режим | Привязка HTTP | Привязка HTTPS |
|---|---|---|
| Отдельный сервер, только HTTPS (по умолчанию) | Только частный loopback-слушатель (см. ниже) | --host |
| Отдельный сервер, только HTTP | --host, включая LAN/подстановочный адрес |
Не включён |
| Отдельный сервер, оба слушателя | 127.0.0.1 независимо от --host |
--host |
| Нативная настольная серверная часть | HTTP остаётся на 127.0.0.1, включая внутренний слушатель хоста |
--host, когда HTTPS включён |
Каждая серверная часть также держит HTTP-слушатель на 127.0.0.1 для собственных встроенных плагинов OpenCode от CodeNomad, например миссий. Если HTTP не был запрошен или запрошенный HTTP-слушатель привязан к адресу, отличному от 127.0.0.1 или 0.0.0.0, серверная часть добавляет частный HTTP-слушатель на случайном порту 127.0.0.1. Он никогда не печатается и не предлагается как адрес подключения, недоступен с других компьютеров и обслуживает то же приложение с аутентификацией.
Конкретный LAN-адрес не обязан принимать loopback-подключения. 0.0.0.0 означает все IPv4-интерфейсы; :: — подстановочный слушатель двух стеков. Используйте реальный доступный адрес в браузере, не подстановочный. Идентификаторы зоны IPv6 в --host не поддерживаются.
Для отдельного HTTPS-развёртывания задайте пароль через начальную настройку, затем выполните:
codenomad --host 0.0.0.0 --https=true --http=false
Для HTTP только на loopback, например за локальным доверенным прокси:
codenomad --host 127.0.0.1 --https=false --http=true
Не рассчитывайте на порт 9898 или 9899: незаданные порты могут заменяться при занятости. Явный ненулевой --https-port, либо --http-port при включённом HTTP, фиксирует порт и даёт ошибку при невозможности привязки; 0 просит ОС назначить порт. Напечатанные Local Connection URL и Remote Connection URL, а также обновлённые Доступные адреса достоверны для данного запуска. См. полный справочник CLI сервера.
Настройка доверенного TLS
Собственный сертификат
- Получите сертификат, чьи Subject Alternative Names (SAN) покрывают реальное имя хоста или IP клиентов.
- Передайте и
--tls-key <path>, и--tls-cert <path>как PEM-файлы. Добавьте--tls-ca <path>, если нужна цепочка/набор CA. - Перезапустите CodeNomad и проверьте сертификат и напечатанный HTTPS-адрес с устройства клиента.
Файлы пользовательского сертификата читаются при запуске и никогда не перезаписываются CodeNomad. Вы отвечаете за продление и необходимый перезапуск для загрузки новых файлов. --tlsSANs настраивает генерируемые сертификаты; он не добавляет имена в переданный сертификат. Защищайте закрытые ключи и доверяйте только сертификатам с проверенной идентичностью хоста.
Созданный локальный CA
При включённом HTTPS без переданной пары ключ/сертификат CodeNomad создаёт локальный CA и серверный сертификат в базе конфигурации:
| Файл | Назначение |
|---|---|
tls/ca-cert.pem |
Открытый сертификат CA для безопасного распространения на администрируемые клиенты. |
tls/ca-key.pem |
Закрытый ключ CA; никогда не распространяйте. |
tls/server-cert.pem |
Серверный сертификат. |
tls/server-key.pem |
Закрытый ключ сервера; никогда не распространяйте. |
- Добавьте все клиентские DNS-имена/IP через
--tlsSANs "host.example.test,192.0.2.10". Подстановочная привязка не обнаруживает все LAN-адреса для SAN. - Перезапустите серверную часть для создания/перепроверки сертификата.
- Проверьте хост/CA по доверенному каналу, затем импортируйте только сертификат CA в хранилище доверия каждого нужного клиента/браузера. Альтернатива — публично доверенный сертификат или обратный TLS-прокси.
Созданный серверный сертификат действует 30 дней. При запуске сертификат обновляется, если до истечения осталось не более трёх дней, отсутствуют нужные SAN, сертификат не проходит проверки или отсутствует файл закрытого ключа. Созданный CA действует 365 дней и заменяется при истечении, непрохождении проверок сертификата или отсутствии файла закрытого ключа; замена также перевыпускает серверный сертификат. Существующие повреждённые, нечитаемые или несовпадающие закрытые ключи автоматически не исправляются. Клиенты должны доверять заменённому CA. Непрерывного продления внутри процесса нет: для длительных развёртываний организуйте осознанный перезапуск до истечения.
При предупреждении сертификата на клиенте остановитесь и проверьте имя хоста, SAN, хранилище доверия и срок. Не отключайте проверку и не превращайте обход предупреждений в процедуру развёртывания. Доверенный HTTPS также нужен удалённым функциям браузера, таким как установка PWA и доступ к микрофону.
Сохранение удалённого сервера
- На главной странице настольного приложения выберите Подключить сервер CodeNomad. Та же кнопка есть на пустой вкладке Серверы и в Настройки → Удалённый доступ → Серверы.
- В Подключиться к серверу введите Имя сервера и URL сервера, используя доверенный HTTPS-origin. Оставьте Пропустить проверку TLS для самоподписанных сертификатов. выключенным; вместо этого настройте доверие.
- Нажмите Сохранить для закладки или Подключиться для сохранения и открытия. Войдите на этом сервере.
Чтобы снова открыть сохранённый сервер, выберите его на вкладке Серверы главной страницы. Закладки принадлежат этой конфигурации CodeNomad, не проектам удалённого сервера. Сохранение URL не запускает сервер и не предоставляет доступ. Удалить сохраненный сервер удаляет закладку, не удалённые разговоры, серверную часть или её учётные данные.
Для удалённого управления вместо этого вставьте свежую ссылку сопряжения в URL сервера. Закладка хранит только origin туннеля, никогда одноразовый код; повторное сопряжение после потери cookie устройства описано в удалённом управлении.