远程接入

选一条网络路径让你的手机能连上 OpenCode。

KKCode 可以走本地地址、私有 VPN、HTTPS 隧道、反向代理、内置扫码隧道。它只要求一个 OpenCode API 基址 —— 不绑定任何具体隧道方案。

最近更新: 2026-08-03中文

连接需要什么

每种方法都需要这三项：

  • Server URL —— origin 加可能需要的 API 路径前缀（例如 https://dev.example.com/api）。
  • Username —— OPENCODE_SERVER_USERNAME 的值。
  • Password —— OPENCODE_SERVER_PASSWORD 的值。

缺失的协议会被自动补全，配置的路径前缀会被保留，可选 HTTP Basic 鉴权会被加上，会话、文件、事件请求都限制在选中项目内。

方法 1 —— 可信局域网

当手机和 OpenCode 机器在同一个私有 Wi-Fi 或局域网时用。

export OPENCODE_SERVER_USERNAME=your-user
export OPENCODE_SERVER_PASSWORD='use-a-strong-password'
opencode serve --hostname 0.0.0.0 --port 4096

找到机器的私网地址，把 http://192.168.1.20:4096 这样的 URL 填进 KKCode。只在私有网络防火墙配置里放开 TCP 4096，不要在路由器上做端口转发，更不要在不可信网络上使用。

方法 2 —— Tailscale

Tailscale 让 OpenCode 继续绑在 loopback，同时在 tailnet 内提供私有 HTTPS 地址。只有你自己设备需要访问时，它是首选。

让 OpenCode 绑 loopback：

export OPENCODE_SERVER_USERNAME=your-user
export OPENCODE_SERVER_PASSWORD='use-a-strong-password'
opencode serve --hostname 127.0.0.1 --port 4096

在 tailnet 内发布：

tailscale serve --bg 4096
tailscale serve status

status 输出里给一个类似 https://machine-name.tailnet-name.ts.net 的地址。iPhone 装 Tailscale、登同一个 tailnet，把这个 HTTPS 地址填进 KKCode。

从一台 tailnet 设备验证：

curl -u your-user:use-a-strong-password \
  https://machine-name.tailnet-name.ts.net/global/health

方法 3 —— Cloudflare Tunnel

Cloudflare Tunnel 提供公网 HTTPS 地址但不用路由器端口转发。因为 hostname 公网可达，OpenCode 鉴权是必须开的。如果只需要自己设备访问，优先用 Tailscale。

Quick tunnel —— 短测用：

cloudflared tunnel --url http://127.0.0.1:4096

Cloudflare 会打印一个临时的公网 HTTPS URL。把它填进 KKCode，保持 OpenCode 鉴权开启。

Named tunnel —— 稳定 hostname：

cloudflared tunnel login
cloudflared tunnel create opencode-mobile
cloudflared tunnel route dns opencode-mobile opencode.example.com

配置示例：

tunnel: opencode-mobile
credentials-file: /home/your-user/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: opencode.example.com
    service: http://127.0.0.1:4096
  - service: http_status:404

跑 cloudflared tunnel run opencode-mobile，然后在 KKCode 里用 https://opencode.example.com。

方法 4 —— 反向代理或 API 路径前缀

KKCode 接受带前缀的基址，例如 https://dev.example.com/api。这样设置之后，health 与会话请求都走在前缀下面，SSE 流和任何 terminal 通道在 HTTPS origin 下自动切到 wss:。

下面这些场景该用这种形式：

  • / 路径跑的是 Web 应用而不是 OpenCode API。
  • 反向代理把 OpenCode 挂在 /api 或别的子路径下。
  • KKCode 报服务端返回 HTML、JSON 解析错误、404 或其他非 API 响应。

不要无脑加 /api。先把 /global/health 验证通。

方法 5 —— 内置扫码隧道

如果你不想管 Tailscale、Cloudflare、反向代理，在开发机上跑 KKCode agent：

npx -y @kkcode-app/agent@latest

它会起 opencode serve、开一条中继隧道、打印一个二维码。在 KKCode 里扫一下，连接页自动填好。蜂窝和 Wi-Fi 都能用，不用路由器配置，不用公网 IP。

按方法分的安全要点

方法暴露面最低要求
局域网私网开启鉴权、信任 Wi-Fi、配私网防火墙
Tailscale仅 tailnet开启鉴权、限制 tailnet 成员/ACL
Cloudflare Tunnel公网 HTTPS URL始终开 OpenCode 鉴权；URL 当公网凭证、用完即弃
反向代理取决于代理HTTPS、保留 streaming、强制 OpenCode 鉴权
内置扫码隧道出站中继保持鉴权开启；二维码泄露立刻轮换密码
← 返回 OpenCode Mobile 文档·回到 kkcode.app