OpenCode 服务器安全：如何安全运行 opencode serve 和 opencode web
opencode serve 暴露的 HTTP API 可以读取文件、运行 shell 命令。如何让它只监听 localhost、设置密码、加上 TLS 并安全地远程访问。
- CLI
- 0.2.17
- 预览 ref
- a2c45c8
简要回答
opencode serve 和 opencode web 会运行一个 HTTP 服务器，它的 API 可以读取文件、运行 shell 命令、修改配置和设置提供商凭据。请把对它的访问视同对这台机器的 shell 访问。
安全配置，按重要程度排序：
- 保留默认主机名
127.0.0.1。 只在你自己控制的网络中绑定0.0.0.0或使用--mdns。 - 只要服务器能被本机以外的设备访问，就设置
OPENCODE_SERVER_PASSWORD。 OpenCode 的文档说明，没有它服务器就没有任何保护。 - 流量跨网络时在前面加 TLS。 明文 HTTP 上的 Basic 认证发送的密码，路径上的任何人都能读取。
- 通过私有网络或隧道访问，例如 SSH 或 Tailscale，而不是公开端口。
--cors尽量收窄。 只添加你自己运行的源。
问题
OpenCode 的客户端/服务器设计是它的优势之一。TUI 与本地服务器通信，所以你也可以从浏览器、IDE 插件、脚本或另一台电脑操作它。文档展示了只需一个参数就能做到：
opencode web --port 4096 --hostname 0.0.0.0在家里的笔记本上，这行命令没问题。但在咖啡馆网络、共享办公室局域网或安全组开放的云服务器上，它会把编码代理的控制 API 暴露给所有能访问该端口的人。解决办法只是几项设置，但当目标只是让手机连上时，很容易被忽略。
OpenCode 服务器暴露了什么
根据 OpenCode 的服务器文档（2026 年 10 月 26 日查阅），API 包括：
| 端点 | 作用 |
|---|---|
POST /session/:id/shell | 运行 shell 命令 |
POST /session/:id/message | 向代理发送提示 |
GET /file/content?path= | 读取文件 |
GET /find?pattern= | 搜索文件内容 |
PATCH /config | 更新配置 |
PUT /auth/:id | 设置提供商凭据 |
POST /mcp | 添加 MCP 服务器 |
POST /session/:id/permissions/:permissionID | 回答权限请求 |
GET /doc | OpenAPI 3.1 规范 |
能调用这些接口的人，可以做你在那台机器终端里能做的任何事，还能以你的身份回答代理的权限提示。下面所有内容都基于这个威胁模型。
OpenCode 服务器的默认值
根据服务器文档：
| 参数 | 默认值 | 说明 |
|---|---|---|
--port | 4096 | |
--hostname | 127.0.0.1 | 仅回环地址 |
--mdns | false | 开启后主机名变为 0.0.0.0，并广播 opencode.local |
--cors | 无 | 额外允许的浏览器源 |
默认值本身是安全的。不带参数运行 opencode 会启动 TUI 和一个使用随机端口和主机名的服务器，TUI 把它当作后端。风险来自修改主机名或开启 mDNS。
第 1 步：除非确有需要，让 OpenCode 只监听 localhost
如果唯一的客户端在同一台机器上，就完全不要传 --hostname：
opencode serve检查监听情况：
# Linux
ss -ltnp | grep 4096
# macOS
lsof -nP -iTCP:4096 -sTCP:LISTEN你想看到的是 127.0.0.1:4096，而不是 0.0.0.0:4096 或 *:4096。
第 2 步：为 OpenCode 服务器设置密码
服务器通过环境变量支持 HTTP Basic 认证，opencode serve 和 opencode web 都适用：
export OPENCODE_SERVER_PASSWORD="$(openssl rand -base64 32)"
opencode serve用户名默认是 opencode。设置 OPENCODE_SERVER_USERNAME 可以修改。Web 文档中有一条提醒：如果没有设置 OPENCODE_SERVER_PASSWORD，服务器就没有保护，本地使用可以，但网络访问时应当设置。
把 TUI 附加到有密码保护的服务器：
opencode attach http://10.20.30.40:4096 --password "$OPENCODE_SERVER_PASSWORD"--password 默认取 OPENCODE_SERVER_PASSWORD，所以如果该 shell 中已设置这个变量，可以省略此参数。
不要让密码出现在 shell 历史或共享仓库的 dotfiles 中。可以用密码管理器，或者一个只有你能读取、启动时加载的文件。
第 3 步：在 OpenCode 服务器前加上 TLS
Basic 认证每次请求都会发送凭据，只是编码而没有加密。在不完全可信的网络上用明文 HTTP，等于没有密码。可选方案：
-
反向代理，例如 Caddy 或 nginx，终结 HTTPS 并转发到
127.0.0.1:4096。OpenCode 服务器仍只监听回环地址。 -
SSH 隧道，不开新端口就能加密连接：
ssh -N -L 4096:127.0.0.1:4096 you@server然后在你自己的机器上把客户端指向
http://127.0.0.1:4096。 -
私有网络，例如 Tailscale 或 WireGuard，会加密你设备之间的流量。仍要配合密码使用，因为该网络上的其他设备也能访问这个端口。
Cloudflare Tunnel vs Tailscale Funnel vs ngrok 比较了各种隧道方案。对任何把端口发布到公网的方式都要小心。公开 URL 加 Basic 认证，就是一个只靠密码保护的 shell。
第 4 步：限制谁能访问 OpenCode 端口
- 在云服务器上， 不要在安全组中开放 4096。通过 SSH 或私有网络访问。
- 在家庭服务器上， 不要在路由器上为它做端口转发。
- 使用 mDNS 时， 记住
--mdns会绑定0.0.0.0。在家庭网络中很方便，但不适合共享 Wi-Fi。 - 使用主机防火墙时， 只允许需要的地址访问该端口。
第 5 步：收窄 CORS
--cors 会添加允许调用服务器的浏览器源。你添加的每个源，都是一个其脚本可以在能访问服务器的浏览器中与你的代理通信的网站。只添加你自己运行的前端，并使用精确的源：
opencode serve --cors https://app.example.com第 6 步：缩小机器上的影响范围
即使访问控制做得好，服务器也是以你的身份运行的。一些习惯可以限制失误的后果：
- 在共享服务器上，用单独的用户运行 OpenCode，只给它访问所需仓库的权限，不放生产凭据。
- 对 shell 命令保持严格的权限规则。远程客户端回答“允许”，仍然是你在允许。
- 用完就停止服务器。持续运行几周的
opencode serve是一个长期的暴露面。
不开端口也能从手机访问 OpenCode
绑定 0.0.0.0 的常见原因是想从另一台设备使用 OpenCode。其实不让 OpenCode 服务器监听回环以外的地址也能做到。
如果你想从手机操作 OpenCode 而不暴露它的服务器，Happier 是一款开源应用，可以从手机、桌面或网页跨设备运行和编排 Claude Code、Codex、OpenCode 等代理。
它如何处理自己管理的 OpenCode 服务器：
- 仅回环地址。 Happier 用
--hostname=127.0.0.1和一个空闲的本地端口启动受管 OpenCode 服务器，并且只复用地址为回环的受管服务器。 - 每个受管服务器都有密码。 如果你设置了
OPENCODE_PASSWORD或OPENCODE_SERVER_PASSWORD，Happier 会使用你的密码。否则它会为该服务器生成一个，并保存在~/.happier/opencode/managed-servers/下仅所有者可读的状态文件中。 - 密码留在你的机器上。 Happier 的文档说明，密码通过环境变量传给服务器，不会写入 Happier 的 OpenCode 服务器日志，也不会发送到远程端点。
- 远程访问经过 Happier， 而不是 OpenCode 端口。手机、桌面或网页应用通过中继与你电脑上的 Happier 守护进程通信。会话内容默认端到端加密。会话 ID 和时间戳等元数据不加密。你也可以自托管中继。
OpenCode 的权限提示会发到手机上，你在那里回答。happier attach <session-id> 可以在同一台机器上重新打开该会话的 OpenCode TUI。设置方法见如何在手机上使用 Happier。Happier 在 GitHub 上开源，可以在这里下载，还有一个 Discord。
故障排除
每个请求都返回 401
客户端没有发送服务器期望的密码。检查客户端的 OPENCODE_SERVER_PASSWORD 是否与服务器一致，如果改过 OPENCODE_SERVER_USERNAME，用户名也要一致。一些较新的 OpenCode 版本读取的变量名不同，所以请用 opencode --version 对照你所用版本的文档。
服务器能被其他机器访问，但本不应该
用 ss -ltnp 或 lsof 检查监听地址。如果显示 0.0.0.0 或 *，在命令或服务文件中查找 --hostname 0.0.0.0 或 --mdns。
浏览器拦截了来自自定义前端的请求
用 --cors 添加该前端的精确源。不要使用通配符。
opencode attach 无法通过 SSH 连接
检查隧道是否已建立，并指向远端的 127.0.0.1:4096。在本地附加到 http://127.0.0.1:4096，而不是远程 IP。
常见问题
opencode serve 默认安全吗？
它监听 127.0.0.1，所以其他机器无法访问。同一台机器上的任何进程都可以访问。没有 OPENCODE_SERVER_PASSWORD 就没有认证。
opencode web 使用同一个密码吗？
是的。OpenCode 的文档说明，OPENCODE_SERVER_PASSWORD 同时适用于 opencode serve 和 opencode web。
可以把 OpenCode 暴露到互联网吗？
可以，但 API 会运行 shell 命令。如果必须这样做，请使用 TLS、强密码，理想情况下再在前面加一层访问控制，例如 VPN 或身份感知代理。
OpenAPI 规范端点有风险吗？
/doc 描述的是 API。它本身不授予访问权限，但会让攻击面更容易被摸清。它和其他接口受同一个密码保护。