環境変数の設定

この章で学べること

✅ SSH、Devcontainer、WSLなどのリモート環境でPlannotatorを正しく設定する
✅ 固定ポートを使用してポート競合や頻繁なポートフォワーディング設定を回避する
✅ カスタムブラウザを指定してプランレビュー画面を開く
✅ URL共有機能を有効化または無効化する
✅ 各環境変数のデフォルト値と動作を理解する

現在の課題

課題1：SSHやDevcontainerでPlannotatorを使用すると、ブラウザが自動で開かない、またはローカルサーバーにアクセスできない。

課題2：Plannotatorを再起動するたびにランダムなポートが使用され、ポートフォワーディング設定を毎回更新する必要がある。

課題3：システムのデフォルトブラウザが使いたいものと異なり、特定のブラウザでプランを確認したい。

課題4：セキュリティ上の理由から、URL共有機能を無効にして、プランが誤って共有されるのを防ぎたい。

Plannotatorが解決できること：

環境変数でリモート環境を自動検出し、ブラウザの自動起動を無効化
固定ポートでポートフォワーディング設定を簡素化
カスタムブラウザをサポート
環境変数でURL共有のオン/オフを制御

こんなときに使う

使用シナリオ：

SSHリモートサーバーでClaude CodeやOpenCodeを使用している
Devcontainerコンテナ内で開発している
WSL（Windows Subsystem for Linux）環境で作業している
固定ポートでポートフォワーディング設定を簡素化したい
特定のブラウザ（Chrome、Firefoxなど）を使用したい
企業のセキュリティポリシーでURL共有機能を無効にする必要がある

適さないシナリオ：

ローカル開発でデフォルトブラウザを使用している（環境変数は不要）
ポートフォワーディングが不要（完全にローカルで開発している）

コアコンセプト

環境変数とは

環境変数はOSが提供するキーバリュー形式の設定メカニズムです。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）
[ ] （リモート環境）ポートフォワーディングを設定済み（SSHの-LパラメータやDevcontainerのforwardPortsなど）

ステップバイステップ

ステップ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：指定したブラウザコマンドが実行される

よく使うブラウザのパス：

OS	ブラウザ	パス/コマンド
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」の2つのタブが表示される
✅ 「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を再起動してください。

この章のまとめ

この章では、Plannotatorの4つの主要な環境変数を学びました：

環境変数	用途	デフォルト値	使用シナリオ
`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を開く

5分でクイックスタート

AIプランとコードのレビュー

チームコラボ+ノート保存

問題が発生したら

環境変数の設定

この章で学べること

現在の課題

こんなときに使う

コアコンセプト

環境変数とは

環境変数の優先順位

🎒 始める前の準備

ステップバイステップ

ステップ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共有を無効にしてもオプションが表示される ​

この章のまとめ ​

次の章の予告 ​

付録：ソースコード参照 ​

環境変数の設定

この章で学べること

現在の課題

こんなときに使う

コアコンセプト

環境変数とは

環境変数の優先順位

🎒 始める前の準備

ステップバイステップ

ステップ1：リモートモードの設定（SSH、Devcontainer、WSL）

ステップ2：固定ポートの設定（リモート環境では必須）

ステップ3：カスタムブラウザの設定

ステップ4：URL共有のオン/オフ設定

ステップ5：すべての環境変数を確認

よくあるトラブル

トラブル1：環境変数が反映されない

トラブル2：ポートが使用中

トラブル3：ブラウザパスが間違っている

トラブル4：リモートモードでブラウザが意図せず開く

トラブル5：URL共有を無効にしてもオプションが表示される

この章のまとめ

次の章の予告

付録：ソースコード参照