远程/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)：跨平台打开浏览器