遠端/Devcontainer 模式設定
學完你能做什麼
- 在 SSH 連線的遠端伺服器上使用 Plannotator
- 在 VS Code devcontainer 中設定並存取 Plannotator
- 在 WSL (Windows Subsystem for Linux) 環境中使用 Plannotator
- 設定連接埠轉發，讓本機瀏覽器存取遠端環境的 Plannotator
你現在的困境
你在遠端伺服器、devcontainer 或 WSL 環境中使用 Claude Code 或 OpenCode，當 AI 產生計畫或需要程式碼審查時，Plannotator 嘗試在遠端環境開啟瀏覽器——但那裡沒有圖形介面，或者你希望在本機瀏覽器中檢視審查介面。
什麼時候用這一招
需要使用遠端/Devcontainer 模式的典型情境：
| 情境 | 說明 |
|---|---|
| SSH 連線 | 你透過 SSH 連線到遠端開發伺服器 |
| Devcontainer | 你在 VS Code 中使用 devcontainer 進行開發 |
| WSL | 你在 Windows 上使用 WSL 進行 Linux 開發 |
| 雲端環境 | 你的程式碼在雲端的容器或虛擬機器中執行 |
核心思路
在遠端環境中使用 Plannotator 需要解決兩個問題：
- 連接埠固定：遠端環境無法自動選擇隨機連接埠，因為需要設定連接埠轉發
- 瀏覽器存取：遠端環境沒有圖形介面，需要在本機的瀏覽器中存取
Plannotator 透過偵測 PLANNOTATOR_REMOTE 環境變數自動進入「遠端模式」：
- 使用固定連接埠（預設 19432）而非隨機連接埠
- 跳過自動開啟瀏覽器
- 在終端機輸出 URL，方便你手動在本機瀏覽器中存取
🎒 開始前的準備
跟我做
第 1 步：理解遠端模式的環境變數
Plannotator 遠端模式依賴三個環境變數：
| 環境變數 | 說明 | 預設值 |
|---|---|---|
PLANNOTATOR_REMOTE | 啟用遠端模式 | 未設定（本機模式） |
PLANNOTATOR_PORT | 固定連接埠號 | 隨機（本機）/ 19432（遠端） |
PLANNOTATOR_BROWSER | 自訂瀏覽器路徑 | 系統預設瀏覽器 |
為什麼
PLANNOTATOR_REMOTE告訴 Plannotator 目前是遠端環境，不要嘗試開啟瀏覽器PLANNOTATOR_PORT設定固定連接埠，方便設定連接埠轉發PLANNOTATOR_BROWSER（選用）指定在本機使用的瀏覽器路徑
第 2 步：在 SSH 遠端伺服器上設定
設定 SSH 連接埠轉發
編輯你的 SSH 設定檔 ~/.ssh/config：
Host your-server
HostName your-server.com
User your-username
LocalForward 9999 localhost:9999你應該看到：
- 新增了
LocalForward 9999 localhost:9999這一行 - 這會將本機 9999 連接埠的流量轉發到遠端伺服器的 9999 連接埠
在遠端伺服器上設定環境變數
連線到遠端伺服器後，在終端機中設定環境變數：
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999為什麼
PLANNOTATOR_REMOTE=1啟用遠端模式PLANNOTATOR_PORT=9999使用固定連接埠 9999（與 SSH 設定中的連接埠號一致）
持久化設定
如果每次連線都要手動設定環境變數很麻煩，可以將這些環境變數新增到你的 shell 設定檔（~/.bashrc 或 ~/.zshrc）中：
echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc使用 Plannotator
現在你可以在遠端伺服器上正常使用 Claude Code 或 OpenCode，當 AI 產生計畫或需要程式碼審查時：
# 在遠端伺服器上，終端機會輸出類似資訊：
[Plannotator] Server running at http://localhost:9999
[Plannotator] Access from your local machine: http://localhost:9999你應該看到：
- 終端機顯示了 Plannotator 的 URL
- 遠端環境沒有開啟瀏覽器（正常行為）
在本機瀏覽器中存取
在本機的瀏覽器中開啟：
http://localhost:9999你應該看到：
- Plannotator 的審查介面正常顯示
- 你可以像在本機環境一樣進行計畫審查或程式碼審查
檢查點 ✅：
- [ ] SSH 連接埠轉發已設定
- [ ] 環境變數已設定
- [ ] 遠端伺服器終端機輸出 URL
- [ ] 本機瀏覽器可以存取審查介面
第 3 步：在 VS Code Devcontainer 中設定
設定 devcontainer
編輯你的 .devcontainer/devcontainer.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 右下角顯示連接埠轉發狀態（通常是一個小圖示）
- 點擊後可以看到 "Port 9999" 已轉發
使用 Plannotator
在 devcontainer 中正常使用 Claude Code 或 OpenCode，當 AI 產生計畫時：
# 容器內終端機輸出：
[Plannotator] Server running at http://localhost:9999你應該看到：
- 終端機顯示了 Plannotator 的 URL
- 容器沒有開啟瀏覽器（正常行為）
在本機瀏覽器中存取
在本機的瀏覽器中開啟：
http://localhost:9999你應該看到：
- Plannotator 的審查介面正常顯示
檢查點 ✅：
- [ ] devcontainer 設定已新增環境變數和連接埠轉發
- [ ] 容器已重建
- [ ] VS Code 顯示連接埠已轉發
- [ ] 本機瀏覽器可以存取審查介面
第 4 步：在 WSL 環境中設定
WSL 環境的設定與 SSH 連線類似，但不需要手動設定連接埠轉發——WSL 會自動將 localhost 流量轉發到 Windows 系統。
設定環境變數
在 WSL 終端機中設定環境變數：
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999持久化設定
將這些環境變數新增到你的 WSL shell 設定檔（~/.bashrc 或 ~/.zshrc）中：
echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc使用 Plannotator
在 WSL 中正常使用 Claude Code 或 OpenCode：
# WSL 終端機輸出：
[Plannotator] Server running at http://localhost:9999你應該看到：
- 終端機顯示了 Plannotator 的 URL
- 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：
檢查清單：
- [ ] SSH 設定檔中
LocalForward的連接埠號與PLANNOTATOR_PORT一致 - [ ] 已斷開並重新連線 SSH
- [ ] 防火牆沒有阻止連接埠轉發
Devcontainer 連接埠轉發不生效
如果 VS Code 沒有自動轉發連接埠：
解決方法：
- 檢查
.devcontainer/devcontainer.json中的forwardPorts設定 - 手動轉發連接埠：
- 開啟 VS Code 命令面板
- 執行
Forward a Port - 輸入連接埠號
9999
WSL 中無法存取
如果 Windows 瀏覽器無法存取 WSL 中的 Plannotator：
解決方法：
- 檢查環境變數是否設定正確
- 嘗試使用
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)：跨平台開啟瀏覽器