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

Что вы научитесь делать

✅ Правильно настраивать Plannotator в удалённых средах: SSH, Devcontainer, WSL
✅ Использовать фиксированные порты для избежания конфликтов и частой перенастройки проброса портов
✅ Указывать пользовательский браузер для открытия интерфейса ревью планов
✅ Включать или отключать функцию шаринга URL
✅ Понимать значения по умолчанию и поведение каждой переменной окружения

С какими проблемами вы сталкиваетесь

Проблема 1: При использовании Plannotator через SSH или в Devcontainer браузер не открывается автоматически, или локальный сервер недоступен.

Проблема 2: При каждом перезапуске Plannotator использует случайный порт, что требует постоянного обновления настроек проброса портов.

Проблема 3: Браузер по умолчанию не соответствует вашим предпочтениям, и вы хотите просматривать планы в определённом браузере.

Проблема 4: По соображениям безопасности вы хотите отключить функцию шаринга URL, чтобы предотвратить случайное распространение планов.

Plannotator поможет вам:

Автоматически определять удалённую среду через переменные окружения и отключать автоматическое открытие браузера
Фиксировать порт для удобной настройки проброса
Поддерживать пользовательский браузер
Управлять функцией шаринга URL через переменные окружения

Когда это пригодится

Сценарии использования:

Работа с Claude Code или OpenCode на удалённом сервере через SSH
Разработка в контейнере Devcontainer
Работа в среде WSL (Windows Subsystem for Linux)
Необходимость фиксированного порта для упрощения настройки проброса
Желание использовать определённый браузер (например, Chrome, Firefox)
Корпоративная политика безопасности требует отключения функции шаринга URL

Неподходящие сценарии:

Локальная разработка с браузером по умолчанию (переменные окружения не нужны)
Проброс портов не требуется (полностью локальная разработка)

Основная концепция

Что такое переменные окружения

Переменные окружения — это механизм конфигурации в виде пар ключ-значение, предоставляемый операционной системой. Plannotator считывает переменные окружения для адаптации к различным средам выполнения (локальной или удалённой).

Зачем нужны переменные окружения?

По умолчанию Plannotator предполагает, что вы работаете в локальной среде разработки:

Локальный режим: случайный порт (для избежания конфликтов)
Локальный режим: автоматическое открытие системного браузера по умолчанию
Локальный режим: функция шаринга URL включена

Однако в удалённых средах (SSH, Devcontainer, WSL) это поведение по умолчанию необходимо изменить:

Удалённый режим: фиксированный порт (для удобства проброса)
Удалённый режим: браузер не открывается автоматически (нужно открывать на хост-машине)
Удалённый режим: возможно, требуется отключить шаринг URL (по соображениям безопасности)

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

Приоритет переменных окружения

Приоритет чтения переменных окружения в Plannotator:

Явно заданная переменная > Поведение по умолчанию

Например:
PLANNOTATOR_PORT=3000 > Порт по умолчанию в удалённом режиме 19432 > Случайный порт в локальном режиме

Это означает:

Если задан PLANNOTATOR_PORT, этот порт используется независимо от режима
Если PLANNOTATOR_PORT не задан, в удалённом режиме используется 19432, в локальном — случайный порт

🎒 Подготовка

Перед настройкой переменных окружения убедитесь:

[ ] Установка Plannotator завершена (Установка для Claude Code или Установка для OpenCode)
[ ] Вы знаете свою текущую среду выполнения (локальная, SSH, Devcontainer, WSL)
[ ] (Для удалённой среды) Настроен проброс портов (параметр -L для SSH или forwardPorts для Devcontainer)

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

Шаг 1: Настройка удалённого режима (SSH, Devcontainer, WSL)

Зачем Удалённый режим автоматически использует фиксированный порт и отключает автоматическое открытие браузера — идеально для SSH, Devcontainer, WSL и подобных сред.

Как настроить

macOS/Linux/WSL (Bash)Windows PowerShellWindows CMD

bash

export PLANNOTATOR_REMOTE=1

powershell

$env:PLANNOTATOR_REMOTE="1"

cmd

set PLANNOTATOR_REMOTE=1

Ожидаемый результат: Визуального отклика нет, переменная окружения установлена.

Постоянная настройка (рекомендуется):

~/.bashrc или ~/.zshrcPowerShell ProfileСистемные переменные

bash

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

powershell

[Environment]::SetEnvironmentVariable('PLANNOTATOR_REMOTE', '1', 'User')

cmd

# Добавьте через интерфейс "Свойства системы > Переменные среды"

Шаг 2: Настройка фиксированного порта (обязательно для удалённой среды)

Зачем Удалённая среда требует фиксированного порта для настройки проброса. В локальной среде также можно задать фиксированный порт при необходимости.

Правила выбора порта по умолчанию:

Локальный режим (без PLANNOTATOR_REMOTE): случайный порт (0)
Удалённый режим (PLANNOTATOR_REMOTE=1): по умолчанию 19432
Явно заданный PLANNOTATOR_PORT: используется указанный порт

Как настроить

macOS/Linux/WSL (Bash)Windows PowerShellWindows CMD

bash

# Установить 19432 (по умолчанию для удалённого режима)
export PLANNOTATOR_PORT=19432

# Или пользовательский порт
export PLANNOTATOR_PORT=3000

powershell

$env:PLANNOTATOR_PORT="19432"

cmd

set PLANNOTATOR_PORT=19432

Ожидаемый результат: Визуального отклика нет, переменная окружения установлена.

Контрольная точка ✅: Проверка применения порта

После перезапуска Claude Code или OpenCode инициируйте ревью плана и проверьте URL в выводе терминала:

bash

# Вывод в локальном режиме (случайный порт)
http://localhost:54321

# Вывод в удалённом режиме (фиксированный порт 19432)
http://localhost:19432

Примеры настройки проброса портов:

SSH удалённая разработка:

bash

ssh -L 19432:localhost:19432 user@remote-server

Devcontainer (.devcontainer/devcontainer.json):

json

{
  "forwardPorts": [19432]
}

Шаг 3: Настройка пользовательского браузера

Зачем Браузер по умолчанию может не соответствовать вашим предпочтениям (например, вы работаете в Chrome, но по умолчанию открывается Safari).

Как настроить

macOS (Bash)Linux (Bash)Windows PowerShellWindows CMD

bash

# Использовать имя приложения (поддерживается в macOS)
export PLANNOTATOR_BROWSER="Google Chrome"

# Или полный путь
export PLANNOTATOR_BROWSER="/Applications/Google Chrome.app"

bash

# Использовать путь к исполняемому файлу
export PLANNOTATOR_BROWSER="/usr/bin/firefox"

# Или относительный путь (если в PATH)
export PLANNOTATOR_BROWSER="firefox"

powershell

# Использовать путь к исполняемому файлу
$env:PLANNOTATOR_BROWSER="C:\Program Files\Google\Chrome\Application\chrome.exe"

cmd

set PLANNOTATOR_BROWSER=C:\Program Files\Google\Chrome\Application\chrome.exe

Ожидаемый результат: При следующем ревью плана Plannotator откроет указанный браузер.

Контрольная точка ✅: Проверка применения браузера

После перезапуска инициируйте ревью плана и наблюдайте:

macOS: откроется указанное приложение
Windows: запустится указанный процесс браузера
Linux: выполнится указанная команда браузера

Распространённые пути к браузерам:

ОС	Браузер	Путь/Команда
macOS	Chrome	`Google Chrome` или `/Applications/Google Chrome.app`
macOS	Firefox	`Firefox` или `/Applications/Firefox.app`
macOS	Safari	`Safari`
Linux	Chrome	`google-chrome` или `/usr/bin/google-chrome`
Linux	Firefox	`firefox` или `/usr/bin/firefox`
Windows	Chrome	`C:\Program Files\Google\Chrome\Application\chrome.exe`
Windows	Firefox	`C:\Program Files\Mozilla Firefox\firefox.exe`

Шаг 4: Настройка функции шаринга URL

Зачем Функция шаринга URL включена по умолчанию, но по соображениям безопасности (например, в корпоративной среде) вам может потребоваться её отключить.

Поведение по умолчанию:

PLANNOTATOR_SHARE не задан: шаринг URL включён
Значение disabled: шаринг URL отключён

Как настроить

macOS/Linux/WSL (Bash)Windows PowerShellWindows CMD

bash

# Отключить шаринг URL
export PLANNOTATOR_SHARE="disabled"

powershell

$env:PLANNOTATOR_SHARE="disabled"

cmd

set PLANNOTATOR_SHARE=disabled

Ожидаемый результат: При нажатии кнопки Export опция "Share as URL" исчезнет или станет недоступной.

Контрольная точка ✅: Проверка отключения шаринга URL

Перезапустите Claude Code или OpenCode
Откройте любое ревью плана
Нажмите кнопку "Export" в правом верхнем углу
Проверьте список опций

Включённое состояние (по умолчанию):

✅ Отображаются вкладки "Share" и "Raw Diff"
✅ Вкладка "Share" показывает URL для шаринга и кнопку копирования

Отключённое состояние (PLANNOTATOR_SHARE="disabled"):

✅ Сразу отображается содержимое "Raw Diff"
✅ Отображаются кнопки "Copy" и "Download .diff"
❌ Вкладка "Share" и функция шаринга URL отсутствуют

Шаг 5: Проверка всех переменных окружения

Зачем Убедиться, что все переменные окружения установлены правильно и работают как ожидается.

Метод проверки

bash

# macOS/Linux/WSL
echo "PLANNOTATOR_REMOTE=$PLANNOTATOR_REMOTE"
echo "PLANNOTATOR_PORT=$PLANNOTATOR_PORT"
echo "PLANNOTATOR_BROWSER=$PLANNOTATOR_BROWSER"
echo "PLANNOTATOR_SHARE=$PLANNOTATOR_SHARE"

powershell

# Windows PowerShell
Write-Host "PLANNOTATOR_REMOTE=$env:PLANNOTATOR_REMOTE"
Write-Host "PLANNOTATOR_PORT=$env:PLANNOTATOR_PORT"
Write-Host "PLANNOTATOR_BROWSER=$env:PLANNOTATOR_BROWSER"
Write-Host "PLANNOTATOR_SHARE=$env:PLANNOTATOR_SHARE"

Ожидаемый результат: Все установленные переменные окружения и их значения.

Пример вывода (конфигурация удалённой среды):

bash

PLANNOTATOR_REMOTE=1
PLANNOTATOR_PORT=19432
PLANNOTATOR_BROWSER=
PLANNOTATOR_SHARE=

Пример вывода (конфигурация локальной среды):

bash

PLANNOTATOR_REMOTE=
PLANNOTATOR_PORT=
PLANNOTATOR_BROWSER=Google Chrome
PLANNOTATOR_SHARE=disabled

Типичные ошибки

Ошибка 1: Переменные окружения не применяются

Симптом: После установки переменных окружения поведение Plannotator не изменилось.

Причина: Переменные окружения применяются только в новых сессиях терминала, или требуется перезапуск приложения.

Решение:

Убедитесь, что переменные окружения записаны в конфигурационный файл (например, ~/.bashrc)
Перезапустите терминал или выполните source ~/.bashrc
Перезапустите Claude Code или OpenCode

Ошибка 2: Порт занят

Симптом: После установки PLANNOTATOR_PORT запуск завершается ошибкой.

Причина: Указанный порт уже используется другим процессом.

Решение:

bash

# Проверить занятость порта (macOS/Linux)
lsof -i :19432

# Сменить порт
export PLANNOTATOR_PORT=19433

Ошибка 3: Неверный путь к браузеру

Симптом: После установки PLANNOTATOR_BROWSER браузер не открывается.

Причина: Путь указан неверно или файл не существует.

Решение:

macOS: используйте имя приложения вместо полного пути (например, Google Chrome)
Linux/Windows: используйте команды which или where для проверки пути к исполняемому файлу
bash
```
which firefox  # Linux
where chrome   # Windows
```

Ошибка 4: Браузер неожиданно открывается в удалённом режиме

Симптом: После установки PLANNOTATOR_REMOTE=1 браузер всё ещё открывается на удалённом сервере.

Причина: Значение PLANNOTATOR_REMOTE не равно "1" или "true".

Решение:

bash

# Правильные значения
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_REMOTE=true

# Неправильные значения (не сработают)
export PLANNOTATOR_REMOTE=yes
export PLANNOTATOR_REMOTE=enabled

Ошибка 5: Опция шаринга URL всё ещё отображается после отключения

Симптом: После установки PLANNOTATOR_SHARE=disabled опция "Share as URL" всё ещё видна.

Причина: Требуется перезапуск приложения для применения изменений.

Решение: Перезапустите Claude Code или OpenCode.

Итоги урока

В этом уроке мы изучили 4 основные переменные окружения Plannotator:

Переменная	Назначение	Значение по умолчанию	Сценарий использования
`PLANNOTATOR_REMOTE`	Переключатель удалённого режима	Не задано (локальный режим)	SSH, Devcontainer, WSL
`PLANNOTATOR_PORT`	Фиксированный порт	Удалённый режим: 19432, локальный: случайный	Проброс портов или избежание конфликтов
`PLANNOTATOR_BROWSER`	Пользовательский браузер	Системный браузер по умолчанию	Использование определённого браузера
`PLANNOTATOR_SHARE`	Переключатель шаринга URL	Не задано (включён)	Отключение функции шаринга

Ключевые моменты:

Удалённый режим автоматически использует фиксированный порт и отключает автоматическое открытие браузера
Явно заданные переменные окружения имеют приоритет над поведением по умолчанию
После изменения переменных окружения требуется перезапуск приложения
В корпоративной среде может потребоваться отключение функции шаринга URL

Анонс следующего урока

В следующем уроке мы изучим Устранение типичных проблем.
Вы узнаете:
Как решить проблему занятости порта
Как справиться с ситуацией, когда браузер не открывается
Как исправить ошибку отсутствия плана
Методы отладки и просмотра логов

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

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

Дата обновления: 2026-01-24

Функция	Путь к файлу	Строки
Определение удалённого режима	`packages/server/remote.ts`	16-29
Логика получения порта	`packages/server/remote.ts`	34-49
Логика открытия браузера	`packages/server/browser.ts`	45-74
Переключатель шаринга URL (Hook)	`apps/hook/server/index.ts`	44
Переключатель шаринга URL (OpenCode)	`apps/opencode-plugin/index.ts`	37-51

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

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

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

isRemoteSession(): определяет, выполняется ли код в удалённой среде (SSH, Devcontainer, WSL)
getServerPort(): получает порт сервера (приоритет: переменная окружения, затем значение по умолчанию для удалённого режима, затем случайный)
openBrowser(url): открывает URL в указанном браузере или браузере по умолчанию

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

Что вы научитесь делать ​

С какими проблемами вы сталкиваетесь ​

Когда это пригодится ​

Основная концепция ​

Что такое переменные окружения ​

Приоритет переменных окружения ​

🎒 Подготовка ​

Пошаговая инструкция ​

Шаг 1: Настройка удалённого режима (SSH, Devcontainer, WSL) ​

Шаг 2: Настройка фиксированного порта (обязательно для удалённой среды) ​

Шаг 3: Настройка пользовательского браузера ​

Шаг 4: Настройка функции шаринга URL ​

Шаг 5: Проверка всех переменных окружения ​

Типичные ошибки ​

Ошибка 1: Переменные окружения не применяются ​

Ошибка 2: Порт занят ​

Ошибка 3: Неверный путь к браузеру ​

Ошибка 4: Браузер неожиданно открывается в удалённом режиме ​

Ошибка 5: Опция шаринга URL всё ещё отображается после отключения ​

Итоги урока ​

Анонс следующего урока ​

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

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

Что вы научитесь делать

С какими проблемами вы сталкиваетесь

Когда это пригодится

Основная концепция

Что такое переменные окружения

Приоритет переменных окружения

🎒 Подготовка

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

Шаг 1: Настройка удалённого режима (SSH, Devcontainer, WSL)

Шаг 2: Настройка фиксированного порта (обязательно для удалённой среды)

Шаг 3: Настройка пользовательского браузера

Шаг 4: Настройка функции шаринга URL

Шаг 5: Проверка всех переменных окружения

Типичные ошибки

Ошибка 1: Переменные окружения не применяются

Ошибка 2: Порт занят

Ошибка 3: Неверный путь к браузеру

Ошибка 4: Браузер неожиданно открывается в удалённом режиме

Ошибка 5: Опция шаринга URL всё ещё отображается после отключения

Итоги урока

Анонс следующего урока

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