Настройка удалённого режима / Devcontainer

Что вы сможете сделать

Использовать Plannotator на удалённом сервере через SSH
Настроить и получить доступ к Plannotator в VS Code devcontainer
Использовать Plannotator в среде WSL (Windows Subsystem for Linux)
Настроить перенаправление портов для доступа к Plannotator в удалённой среде с локального браузера

Ваша текущая проблема

Вы используете Claude Code или OpenCode в удалённом сервере, devcontainer или среде WSL. Когда AI генерирует план или требуется рецензирование кода, Plannotator пытается открыть браузер в удалённой среде, но там нет графического интерфейса, или вы хотите просматривать интерфейс рецензирования в локальном браузере.

Когда использовать этот режим

Типичные сценарии использования удалённого режима / Devcontainer:

Сценарий	Описание
SSH-соединение	Вы подключаетесь к удалённому серверу разработки через SSH
Devcontainer	Вы используете devcontainer в VS Code для разработки
WSL	Вы используете WSL в Windows для разработки на Linux
Облачная среда	Ваш код выполняется в контейнере или виртуальной машине в облаке

Основная идея

Использование Plannotator в удалённой среде требует решения двух проблем:

Фиксированный порт: В удалённой среде невозможно автоматически выбрать случайный порт, так как требуется настройка перенаправления портов
Доступ браузера: В удалённой среде нет графического интерфейса, необходимо получать доступ с браузера локальной машины

Plannotator автоматически переходит в «удалённый режим» при обнаружении переменной окружения PLANNOTATOR_REMOTE:

Использует фиксированный порт (по умолчанию 19432) вместо случайного
Пропускает автоматическое открытие браузера
Выводит URL в терминал для удобства ручного доступа с локального браузера

🎒 Подготовка перед началом

Предварительные требования

Перед началом изучения этого урока убедитесь, что:

Завершили Быстрый старт
Установили и настроили плагин Claude Code или плагин OpenCode
Понимаете основные концепции SSH или devcontainer

Практическое руководство

Шаг 1: Понимание переменных окружения удалённого режима

Удалённый режим Plannotator зависит от трёх переменных окружения:

Переменная окружения	Описание	Значение по умолчанию
`PLANNOTATOR_REMOTE`	Включить удалённый режим	Не установлено (локальный режим)
`PLANNOTATOR_PORT`	Фиксированный номер порта	Случайный (локальный) / 19432 (удалённый)
`PLANNOTATOR_BROWSER`	Пользовательский путь к браузеру	Системный браузер по умолчанию

Почему

PLANNOTATOR_REMOTE сообщает Plannotator, что текущая среда является удалённой, и не пытаться открыть браузер
PLANNOTATOR_PORT устанавливает фиксированный порт для удобства настройки перенаправления портов
PLANNOTATOR_BROWSER (опционально) указывает путь к браузеру на локальной машине

Шаг 2: Настройка на удалённом сервере SSH

Настройка перенаправления портов SSH

Отредактируйте файл конфигурации SSH ~/.ssh/config:

bash

Host your-server
    HostName your-server.com
    User your-username
    LocalForward 9999 localhost:9999

Что вы должны увидеть:

Добавлена строка LocalForward 9999 localhost:9999
Это перенаправит трафик с локального порта 9999 на порт 9999 удалённого сервера

Установка переменных окружения на удалённом сервере

После подключения к удалённому серверу установите переменные окружения в терминале:

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

Почему

PLANNOTATOR_REMOTE=1 включает удалённый режим
PLANNOTATOR_PORT=9999 использует фиксированный порт 9999 (совпадает с номером порта в конфигурации SSH)

Постоянная конфигурация

Если утомительно вручную устанавливать переменные окружения при каждом подключении, вы можете добавить эти переменные в файл конфигурации вашей оболочки (~/.bashrc или ~/.zshrc):

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc

Использование Plannotator

Теперь вы можете нормально использовать Claude Code или OpenCode на удалённом сервере. Когда AI генерирует план или требуется рецензирование кода:

bash

# На удалённом сервере терминал выведет примерно следующее:
[Plannotator] Server running at http://localhost:9999
[Plannotator] Access from your local machine: http://localhost:9999

Что вы должны увидеть:

Терминал отображает URL Plannotator
Удалённая среда не открывает браузер (нормальное поведение)

Доступ в локальном браузере

Откройте в браузере на локальной машине:

http://localhost:9999

Что вы должны увидеть:

Интерфейс рецензирования Plannotator отображается корректно
Вы можете проводить рецензирование планов или кода, как в локальной среде

Контрольная точка ✅:

[ ] Перенаправление портов SSH настроено
[ ] Переменные окружения установлены
[ ] Терминал удалённого сервера выводит URL
[ ] Локальный браузер может получить доступ к интерфейсу рецензирования

Шаг 3: Настройка в VS Code Devcontainer

Настройка devcontainer

Отредактируйте файл .devcontainer/devcontainer.json:

json

{
  "name": "Your Devcontainer",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },

  "forwardPorts": [9999]
}

Почему

containerEnv устанавливает переменные окружения внутри контейнера
forwardPorts сообщает VS Code автоматически перенаправлять порты контейнера на локальную машину

Пересборка и запуск devcontainer

Откройте палитру команд VS Code (Ctrl+Shift+P или Cmd+Shift+P)
Введите Dev Containers: Rebuild Container и выполните
Дождитесь завершения пересборки контейнера

Что вы должны увидеть:

В правом нижнем углу VS Code отображается статус перенаправления портов (обычно это маленький значок)
После нажатия вы увидите, что порт 9999 перенаправлен

Использование Plannotator

Используйте Claude Code или OpenCode в devcontainer как обычно. Когда AI генерирует план:

bash

# Вывод терминала внутри контейнера:
[Plannotator] Server running at http://localhost:9999

Что вы должны увидеть:

Терминал отображает URL Plannotator
Контейнер не открывает браузер (нормальное поведение)

Доступ в локальном браузере

Откройте в браузере на локальной машине:

http://localhost:9999

Что вы должны увидеть:

Интерфейс рецензирования Plannotator отображается корректно

Контрольная точка ✅:

[ ] Конфигурация devcontainer добавлена переменными окружения и перенаправлением портов
[ ] Контейнер пересобран
[ ] VS Code отображает, что порт перенаправлен
[ ] Локальный браузер может получить доступ к интерфейсу рецензирования

Шаг 4: Настройка в среде WSL

Настройка среды WSL аналогична SSH-соединению, но не требует ручной настройки перенаправления портов — WSL автоматически перенаправляет трафик localhost в систему Windows.

Установка переменных окружения

Установите переменные окружения в терминале WSL:

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

Постоянная конфигурация

Добавьте эти переменные окружения в файл конфигурации вашей оболочки WSL (~/.bashrc или ~/.zshrc):

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc

Использование Plannotator

Используйте Claude Code или OpenCode в WSL как обычно:

bash

# Вывод терминала WSL:
[Plannotator] Server running at http://localhost:9999

Что вы должны увидеть:

Терминал отображает URL Plannotator
WSL не открывает браузер (нормальное поведение)

Доступ в браузере Windows

Откройте в браузере Windows:

http://localhost:9999

Что вы должны увидеть:

Интерфейс рецензирования Plannotator отображается корректно

Контрольная точка ✅:

[ ] Переменные окружения установлены
[ ] Терминал WSL выводит URL
[ ] Браузер Windows может получить доступ к интерфейсу рецензирования

Предупреждения о возможных проблемах

Порт уже занят

Если вы видите ошибку, подобную этой:

Error: bind: EADDRINUSE: address already in use :::9999

Решение:

Измените номер порта:

bash

export PLANNOTATOR_PORT=10000  # Используйте незанятый порт

Или остановите процесс, занимающий порт 9999:
bash
```
lsof -ti:9999 | xargs kill -9
```

Перенаправление портов SSH не работает

Если локальный браузер не может получить доступ к Plannotator:

Контрольный список:

[ ] Номер порта в LocalForward в файле конфигурации SSH совпадает с PLANNOTATOR_PORT
[ ] Вы отключились и снова подключились к SSH
[ ] Брандмауэр не блокирует перенаправление портов

Перенаправление портов Devcontainer не работает

Если VS Code не автоматически перенаправляет порты:

Решение:

Проверьте конфигурацию forwardPorts в .devcontainer/devcontainer.json
Перенаправьте порт вручную:
- Откройте палитру команд VS Code
- Выполните Forward a Port
- Введите номер порта 9999

Нет доступа в WSL

Если браузер Windows не может получить доступ к Plannotator в WSL:

Решение:

Проверьте, правильно ли установлены переменные окружения
Попробуйте использовать 0.0.0.0 вместо localhost (зависит от версии WSL и сетевой конфигурации)
Проверьте настройки брандмауэра Windows

Итоги урока

Ключевые моменты удалённого режима / Devcontainer:

Пункт	Описание
Переменные окружения	`PLANNOTATOR_REMOTE=1` включает удалённый режим
Фиксированный порт	Используйте `PLANNOTATOR_PORT` для установки фиксированного порта (по умолчанию 19432)
Перенаправление портов	SSH/Devcontainer требуют настройки перенаправления портов, WSL перенаправляет автоматически
Ручной доступ	Удалённый режим не открывает браузер автоматически, требуется ручной доступ с локального браузера
Постоянная конфигурация	Добавьте переменные окружения в файл конфигурации, чтобы избежать повторной настройки

Предварительный просмотр следующего урока

На следующем уроке мы изучим Подробное описание переменных окружения.
Вы узнаете:
Все доступные переменные окружения Plannotator
Назначение и значения по умолчанию каждой переменной окружения
Как комбинировать переменные окружения для разных сценариев

Приложение: справочник по исходному коду

Нажмите, чтобы просмотреть расположение исходного кода

Время обновления: 2026-01-24

Функция	Путь к файлу	Номер строки
Обнаружение удалённой сессии	`packages/server/remote.ts`	16-29
Получение порта сервера	`packages/server/remote.ts`	34-49
Логика запуска сервера	`packages/server/index.ts`	91-97
Логика открытия браузера	`packages/server/browser.ts`	45-74
Обнаружение WSL	`packages/server/browser.ts`	11-34

Ключевые константы:

DEFAULT_REMOTE_PORT = 19432: номер порта по умолчанию в удалённом режиме

Ключевые функции:

isRemoteSession(): обнаруживает, выполняется ли в удалённой сессии
getServerPort(): получает порт сервера (удалённый использует фиксированный порт, локальный — случайный)
openBrowser(url): открывает браузер кроссплатформенно

Настройка удалённого режима / Devcontainer ​

Что вы сможете сделать ​

Ваша текущая проблема ​

Когда использовать этот режим ​

Основная идея ​

🎒 Подготовка перед началом ​

Практическое руководство ​

Шаг 1: Понимание переменных окружения удалённого режима ​

Шаг 2: Настройка на удалённом сервере SSH ​

Настройка перенаправления портов SSH ​

Установка переменных окружения на удалённом сервере ​

Использование Plannotator ​

Доступ в локальном браузере ​

Шаг 3: Настройка в VS Code Devcontainer ​

Настройка devcontainer ​

Пересборка и запуск devcontainer ​

Использование Plannotator ​

Доступ в локальном браузере ​

Шаг 4: Настройка в среде WSL ​

Установка переменных окружения ​

Использование Plannotator ​

Доступ в браузере Windows ​

Предупреждения о возможных проблемах ​

Порт уже занят ​

Перенаправление портов SSH не работает ​

Перенаправление портов Devcontainer не работает ​

Нет доступа в WSL ​

Итоги урока ​

Предварительный просмотр следующего урока ​

Приложение: справочник по исходному коду ​

Настройка удалённого режима / Devcontainer

Что вы сможете сделать

Ваша текущая проблема

Когда использовать этот режим

Основная идея

🎒 Подготовка перед началом

Практическое руководство

Шаг 1: Понимание переменных окружения удалённого режима

Шаг 2: Настройка на удалённом сервере SSH

Настройка перенаправления портов SSH

Установка переменных окружения на удалённом сервере

Использование Plannotator

Доступ в локальном браузере

Шаг 3: Настройка в VS Code Devcontainer

Настройка devcontainer

Пересборка и запуск devcontainer

Использование Plannotator

Доступ в локальном браузере

Шаг 4: Настройка в среде WSL

Установка переменных окружения

Использование Plannotator

Доступ в браузере Windows

Предупреждения о возможных проблемах

Порт уже занят

Перенаправление портов SSH не работает

Перенаправление портов Devcontainer не работает

Нет доступа в WSL

Итоги урока

Предварительный просмотр следующего урока

Приложение: справочник по исходному коду