OpenCode v2 远程开发实战：Web UI、Pair、SSH 隧道与 OpenTunnel 安全接入

这是《OpenCode v2 实战：从零搭建企业级 AI 编程助手》专题的第 17 篇。前一篇梳理了文件、Shell、Code Mode 与浏览器工具的安全编排；本文把执行面延伸到远程访问，讲清怎样在不牺牲主机安全边界的前提下，让浏览器、终端和移动设备连接同一个 OpenCode 服务。

很多团队第一次使用 OpenCode，都是在项目目录中执行一个命令，然后把它理解成"终端里的 AI 对话框"。到了 v2，这个认知已经不够准确：本地客户端背后有一个共享后台服务，TUI、Web、Desktop 和显式连接的 CLI 都可以成为客户端；会话、配置、集成、权限判断和工具执行则由服务端统一承载。

这套架构让远程开发自然成立，也让风险边界发生变化。开放一个端口，不只是开放聊天界面，还可能间接开放代码读取、命令执行、凭据使用和外部系统调用能力。因此，远程接入不能只讨论"怎么连上"，还必须同时回答认证、网络暴露、会话撤销、权限最小化、审计和故障恢复。

本文依据 2026 年 10 月 27 日可见的 OpenCode v2 官方文档和更新记录整理，并把官方命令转换成可执行的工程方案。

一、先理解 v2 的客户端---服务端模型

1. 共享后台服务不是普通常驻窗口

OpenCode v2 默认会为当前用户发现或启动一个共享后台服务。多个本地客户端连接到它，由它统一管理会话、配置、集成、权限和工具执行。

text 复制代码

TUI ───────────────┐
Desktop ───────────┼── OpenCode Background Service ── Project / Tools / Providers
Web UI ────────────┤                 │
CLI --server ──────┘                 └── Sessions / Permissions / Events

这意味着关闭一个 TUI 窗口，不一定等于停止服务；在 Web 中看到的会话，也不是复制出来的静态记录，而是同一服务上的实时状态。

2. 三种运行形态的差异

形态	启动方式	状态归属	典型用途
共享后台服务	默认自动发现，或 `opencode service start`	当前用户的共享服务	日常本机使用、TUI 与 Web 共用会话
私有实例	`opencode --standalone`	当前进程	一次性任务、隔离测试、CI
前台专用服务	`opencode serve`	指定服务进程	远程主机、容器、systemd、固定端口

选择原则不是"哪个命令更新"，而是状态是否应该共享。个人工作站通常适合共享服务；流水线应优先私有实例；常驻开发机或受控服务器适合 serve。

3. 服务端才是真正的信任边界

浏览器只是输入输出端。真正读取仓库、执行 Shell、调用 Provider 和 MCP 的主体是服务所在机器。因此远程访问 OpenCode，本质上是在授权远端客户端驱动这台机器上的 Agent。

text 复制代码

远端设备可信
    ↓
连接链路可信
    ↓
OpenCode 认证有效
    ↓
项目权限策略仍然生效
    ↓
工具操作留下可验证证据

任何一层缺失，都不应通过扩大权限来"临时解决"。

二、五种接入方案怎么选

1. 本机 Pair：默认且最简单

bash 复制代码

opencode pair

该命令输出一次性连接链接和二维码。官方文档说明，链接只能使用一次，并在 5 分钟后过期；打开链接后，浏览器会获得会话 Cookie 并进入 Web UI。

适合场景：同一台电脑上的浏览器或可信移动设备临时连接。

2. SSH 隧道：企业内网的优先方案

bash 复制代码

ssh -L 49374:127.0.0.1:49374 dev@example-host

服务仍然只监听远端主机的 127.0.0.1，本地通过 SSH 加密隧道访问。它复用了已有的主机认证、堡垒机、MFA、访问日志和账号回收体系，不必把 OpenCode 端口直接暴露到局域网或公网。

3. OpenTunnel：跨网络临时访问

bash 复制代码

opencode pair --remote

官方说明该模式会通过 OpenTunnel 提供远程地址，链路端到端加密，并仍要求服务密码。首次开启会明确提示正在把服务暴露到互联网；非交互环境必须显式传入 --yes。

4. 固定 Server：受控的常驻部署

bash 复制代码

opencode serve --hostname 127.0.0.1 --port 4096
opencode --server http://127.0.0.1:4096

serve 在前台运行与 Web/TUI 同源的服务，适合交给 systemd、容器编排或进程守护器管理。

5. 直接监听局域网：只用于受控网络

bash 复制代码

opencode service set hostname 0.0.0.0
opencode service set port 49374
opencode service start

0.0.0.0 会让服务监听所有网卡。它操作简单，但扩大了攻击面，不应成为跨公网访问的默认做法。

三、本机 Web UI 与 Pair 的完整流程

1. 先读取真实地址

不同系统的默认端口并不完全相同。官方文档当前列出的默认值是：macOS、Linux 与 WSL 通常为 49374，Windows 通常为 28894。不要把示例端口写死到脚本中，应先读取实际状态。

powershell 复制代码

opencode service status

建议把输出中的协议、主机和端口作为后续检查的唯一来源。

2. 生成一次性连接链接

powershell 复制代码

opencode pair

安全流程应满足三个条件：链接只在可信渠道展示；使用后不再转发；过期后重新生成，而不是尝试保存和复用旧链接。

3. 验证连接后状态

连接成功后，至少检查以下内容：

text 复制代码

能看到预期项目和会话
服务地址与预期一致
当前工作目录没有误指向其他仓库
权限询问仍然生效
工具执行发生在预期主机

不要仅凭 Web 页面能打开就判断部署完成。真正的完成证据应包含会话可访问、项目边界正确和权限策略有效。

1. 三者承担不同职责

凭据	生命周期	主要作用	处置方式
Pair 链接	单次、5 分钟	首次交换登录状态	用后即弃，不进工单和聊天记录
会话 Cookie	官方文档当前说明为 30 天	浏览器持续访问	只存可信浏览器，设备丢失时主动撤销
服务密码	持续有效，直到变更	服务端认证根	使用高强度随机值并受控保存

Pair 链接不是长期密码，Cookie 也不是永久授权。三者分层后，才能设计正确的撤销流程。

2. 轮换密码会让所有会话退出

bash 复制代码

opencode service set password "replace-with-a-long-random-secret"
opencode service start

官方文档说明，修改服务密码会让所有已登录会话退出。设备丢失、链接误发、成员离组或怀疑 Cookie 泄漏时，这是最直接的全局撤销方式。

3. 不把秘密写进脚本和历史

下面这种写法会把密码留在 Shell 历史中：

bash 复制代码

# 不推荐：仅用于说明风险
opencode service set password "plain-text-secret"

生产环境应通过组织认可的 Secret Manager、受限环境变量注入或交互式配置完成，且日志只能记录"轮换成功"和时间，不能记录真实值。

五、SSH 隧道：默认不开放服务端口

1. 标准端口转发

假设远端服务实际监听 127.0.0.1:49374：

bash 复制代码

ssh -N \
  -L 49374:127.0.0.1:49374 \
  dev@example-host

本地浏览器访问 http://127.0.0.1:49374，流量经 SSH 到达远端回环地址。-N 表示不启动远端 Shell，只建立转发。

2. 避免本地端口冲突

bash 复制代码

ssh -N \
  -L 59374:127.0.0.1:49374 \
  dev@example-host

此时本地访问 http://127.0.0.1:59374。左侧是本地端口，右侧是远端监听地址，二者不必相同。

3. 经过堡垒机

bash 复制代码

ssh -N \
  -J user@bastion.example.com \
  -L 59374:127.0.0.1:49374 \
  dev@private-host

团队可以继续使用现有堡垒机的身份认证、审计和网络策略。OpenCode 本身无需监听 0.0.0.0。

4. 隧道模式的验收证据

text 复制代码

远端 netstat/ss：仅监听 127.0.0.1
本地浏览器：可打开 Pair 链接
断开 SSH：本地端口立即不可用
防火墙：未新增 OpenCode 公网入站规则

这四项比"页面能打开"更能说明边界配置正确。

六、OpenTunnel 远程配对

1. 什么时候使用

OpenTunnel 适合没有 VPN、不能配置 SSH 转发，又需要从外部网络短时接入的情况，例如从移动设备查看长任务，或临时连接一台受控开发机。

bash 复制代码

opencode pair --remote

首次执行时应由人确认互联网暴露风险。自动化脚本中的 --yes 代表事先完成了风险审批，而不是绕过审批。

2. 远程地址不等于公开分享链接

2026 年 10 月的 v2 更新已经移除了旧的会话分享后端和不可用的 /share 命令。远程 Pair 是"连接到你的服务"，不是把一份只读对话发布到公开网页。

text 复制代码

旧式分享：导出或公开某段会话
远程 Pair：认证设备成为服务客户端

因此远程 Pair 的权限风险更高，不能把链接当作普通文章链接转发。

3. 用完后关闭远程访问

bash 复制代码

opencode service set remote false
opencode service start

关闭隧道后还应检查服务状态，并根据风险决定是否轮换密码。需要注意：官方文档说明，首次确认记录可能被保留；以后重新开启时未必再次出现相同提示，所以组织策略不能依赖这一次交互弹窗。

七、Service 与 Serve 的边界

1. 共享服务的生命周期

bash 复制代码

opencode service start
opencode service status
opencode service restart
opencode service stop

修改 hostname、port、password、cors 等设置会停止后台服务，需要再次启动才能应用新配置。

2. 前台 Serve 适合被进程管理器托管

bash 复制代码

opencode serve \
  --hostname 127.0.0.1 \
  --port 4096

它适合放在 systemd、Docker 或其他前台进程模型中。服务日志、退出码、资源限制和重启策略都由外部管理器统一控制。

3. 客户端显式连接

bash 复制代码

opencode --server http://127.0.0.1:4096

显式 --server 能避免客户端误连到另一个自动发现的共享服务。在同一机器上运行测试、生产或多个租户实例时，这一点尤其重要。

八、CORS、反向代理与 TLS

1. CORS 不是认证机制

bash 复制代码

opencode service set cors https://dev.example.com
opencode service start

CORS 决定哪些浏览器 Origin 可以跨源访问服务，但它不能替代服务密码、网络访问控制或 TLS。非浏览器客户端也不受浏览器 CORS 策略保护。

2. 只允许精确 Origin

text 复制代码

推荐：https://dev.example.com
谨慎：https://*.example.com
避免：*

Origin 应包含协议、主机和必要端口。测试域名、临时预览域名和生产域名应分别登记，避免为了省事设置过宽范围。

3. 反向代理参考结构

nginx 复制代码

server {
    listen 443 ssl;
    server_name dev.example.com;

    location / {
        proxy_pass http://127.0.0.1:4096;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

示例只展示代理方向。生产环境还应配置证书自动续期、访问日志脱敏、请求大小限制、超时和上游健康检查。

4. Pair 外部地址

bash 复制代码

opencode pair --url https://dev.example.com

当服务位于反向代理后面时，可用外部 URL 生成客户端实际可访问的连接链接。外部 URL 必须与证书、代理路由和 CORS 设置一致。

九、权限模型不能被远程访问绕过

1. 网络认证只回答"谁能进入"

OpenCode 权限规则继续回答"进入后能做什么"。即使只有可信工程师能登录，也不应该默认允许任意 Shell、删除、推送、部署或生产系统写操作。

json 复制代码

{
  "permissions": [
    { "action": "read", "resource": "*", "effect": "allow" },
    { "action": "edit", "resource": "src/**", "effect": "ask" },
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "shell", "resource": "rm -rf *", "effect": "deny" }
  ]
}

2. 远程场景要收紧交互式批准

手机或 Web 客户端上的一次误触，可能批准高风险操作。建议把生产部署、外部消息、删除、推送、付款和密钥写入设置为独立授权，并在批准界面展示目标资源。

3. 服务账号与个人账号分离

text 复制代码

个人工作站：个人 Provider 凭据 + 个人项目权限
共享开发机：受限服务账号 + 仓库白名单
CI：短期凭据 + standalone + 无交互最小权限

不要让一台共享远程服务同时继承管理员云凭据、生产数据库凭据和无限制 Shell。

十、会话、项目与多客户端一致性

1. 多客户端看到的是同一状态

text 复制代码

终端发起任务 → Web 查看进度 → Desktop 处理权限请求

这种能力很方便，但也会产生并发操作。两个客户端同时修改同一会话、切换工作目录或响应权限请求时，必须以服务端最终状态为准。

2. 不要把"会话共享"误解为"多人协作锁"

OpenCode 可以让多个客户端连接同一服务，但这不自动提供文档式多人锁、审批流或冲突合并。团队仍应使用 Git 分支、Worktree、代码评审和文件所有权约定。

3. 为会话绑定明确目录

bash 复制代码

opencode /srv/repos/project-a

远程服务往往同时托管多个仓库。每个任务开始前应验证项目根目录、Git 分支和未提交修改，避免在错误仓库里执行正确命令。

十一、通过 API 和事件流做受控集成

1. 服务公开 OpenAPI 文档

官方 Server 文档列出 /doc，用于查看 OpenAPI 3.1 规范。自动化集成应从规范生成或校验客户端，而不是长期依赖手写、未版本化的请求。

bash 复制代码

opencode api GET /api/session
opencode api session.list --param limit=10

2. 用异步请求避免长连接阻塞

服务提供异步会话消息接口，并通过事件流反馈状态。典型架构如下：

text 复制代码

Job Runner ── POST prompt_async ──> OpenCode Server
Job Runner <──── Server-Sent Events ────────┘

调用方需要为每个任务保存 session ID、请求时间和幂等键，网络超时后先查询状态，而不是盲目重复发送。

3. API 不应直接暴露到公网

text 复制代码

公网入口 → SSO / VPN / WAF → 反向代理 → OpenCode 127.0.0.1

服务密码是最后一道认证，不应承担全部边界防护。生产接入还应限制来源网段、并发数和请求频率。

十二、日志、指标与审计

1. 最小审计字段

json 复制代码

{
  "time": "2026-10-27T09:30:00+08:00",
  "client": "web",
  "sessionId": "ses_example",
  "project": "project-a",
  "action": "shell",
  "resource": "npm test",
  "decision": "allow",
  "result": "succeeded"
}

日志不应记录 Pair 链接、Cookie、服务密码、Provider 密钥或完整敏感提示词。

2. 关键指标

text 复制代码

认证失败率
活跃设备与会话数
远程入口在线时长
权限询问、拒绝与超时数量
高风险工具调用量
未知结果与重复提交数量
密码轮换和远程入口关闭时间

3. 完成证据与审计证据分开

"测试通过"是任务完成证据；"谁从哪个客户端批准了 Shell"是审计证据。二者都要保留，但保存周期和访问权限可以不同。

十三、故障排查顺序

1. 先查服务，而不是先改防火墙

bash 复制代码

opencode service status
opencode debug paths log
opencode debug config

先确认服务是否运行、实际地址、配置来源和日志路径，再判断网络问题。

2. 分层定位

层级	典型症状	优先检查
进程层	连接被拒绝	服务状态、端口占用、进程退出码
网络层	本机可用、远端不可用	监听地址、SSH 隧道、VPN、防火墙
TLS/代理层	502、证书或 WebSocket 异常	上游地址、证书链、代理头、超时
认证层	反复回到登录页	Pair 是否过期、Cookie、密码是否轮换
应用层	页面打开但任务失败	项目目录、Provider、权限、工具日志

3. 常见误区

text 复制代码

误区一：把 127.0.0.1 改成 0.0.0.0 后仍无认证
误区二：Pair 链接过期后持续刷新旧页面
误区三：修改 service 设置后忘记重新 start
误区四：本地和远端端口写反
误区五：CORS 报错时直接允许所有 Origin
误区六：提交结果未知时重复触发发布或部署

十四、三套可落地部署蓝图

1. 个人开发机

text 复制代码

OpenCode shared service：127.0.0.1
访问：本机 Pair
远程：公司 VPN + SSH 隧道
认证：随机服务密码
权限：按项目询问写入和 Shell

这是成本最低、边界最清楚的方案。

2. 团队远程开发机

text 复制代码

SSO / VPN
    ↓
受控跳板机
    ↓ SSH Tunnel
OpenCode serve@127.0.0.1
    ↓
白名单仓库 + 受限服务账号

每个团队或安全域使用独立实例，不共享管理员凭据；高风险操作仍进入代码评审或部署审批系统。

3. 自动化任务节点

yaml 复制代码

steps:
  - name: Run isolated OpenCode task
    run: opencode run --standalone "Review this repository and emit JSON"
    env:
      PROVIDER_API_KEY: ${{ secrets.PROVIDER_API_KEY }}

CI 优先 --standalone，任务结束即回收进程和短期密钥，不需要 Pair，也不开放远程 Web。

十五、上线检查清单与总结

1. 上线前检查

已确认使用共享服务、standalone 还是专用 serve；
服务默认只监听回环地址；
远程访问优先使用 VPN 或 SSH 隧道；
Pair 链接未进入群聊、工单和持久日志；
服务密码为高强度随机值并可轮换；
CORS 只允许精确可信 Origin；
公网入口具备 TLS、SSO/VPN、限流和访问审计；
项目目录、账号、Provider 凭据按安全域隔离；
删除、推送、发布、部署和外部写操作需要独立授权；
多客户端并发时有 Git 分支或 Worktree 隔离；
网络超时后先查状态，不盲目重放副作用；
日志已脱敏，不记录链接、Cookie 和密钥；
设备丢失和成员离组时可以立即轮换密码；
已演练停止服务、关闭远程入口和撤销会话。

2. 总结

OpenCode v2 的远程能力不是额外附加的一层网页，而是客户端---服务端架构的自然结果。Pair 解决设备首次认证，Web UI 提供跨终端入口，SSH 隧道保留回环监听边界，OpenTunnel解决跨网络临时连接，serve 则为常驻和受控部署提供稳定进程模型。

真正可靠的方案通常遵循同一条原则：服务尽量不直接暴露，身份与网络双重收口，项目与凭据按安全域隔离，高风险工具保留独立授权，并用服务状态、会话 ID、审计日志和业务结果证明操作完成。

远程访问的价值，是让 Agent 跨设备持续工作；远程访问的底线，则是任何便利都不能绕过原有工程权限和安全边界。

3. 参考资料

本文依据 2026 年 10 月 27 日可见的官方文档整理。远程 Pair、OpenTunnel、默认端口、会话时长和服务配置仍可能随版本调整；生产环境应固定版本，并以当前命令帮助、官方文档和实际服务状态为准。

OpenCode v2 远程开发实战：Web UI、Pair、SSH 隧道与 OpenTunnel 安全接入