1. 为什么要在 WSL 里用浏览器跑 OpenCodeOpenCode 不只是终端里的一个 TUI 工具它还能以完整的 Web 应用形态跑起来直接在浏览器里管理会话、挂载终端、切换模型。对长期在 Windows 上做开发的人来说这件事的价值在于你不需要为了用 AI 编码助手而改变自己的工作流浏览器标签页就是入口。但 Windows 原生环境跑opencode web有几个绕不开的坑。文件系统访问路径和 Linux 不一致终端集成经常出现字符编码或 PTY 分配问题某些依赖在 PowerShell 下的行为和在 bash 下完全不同。我试过直接在 PowerShell 里启动会话能开但挂载终端时反复报错最后还是在 WSL 里跑才稳定下来。所以这篇的路线是在 WSLUbuntu 为例里启动 OpenCode Web 服务通过 TaoToken 统一 Key 接入模型通道再从 Windows 侧的浏览器访问 WSL 的服务端口。整条链路涉及三个配置点——OpenCode 的config.toml、TaoToken 的 Key 管理、WSL 的端口转发。下面按可复制的顺序拆开讲。适合谁看已经在用 WSL 做日常开发、想用浏览器界面管理 OpenCode 会话、并且希望用一个统一 Key 接入多家模型通道的人。如果你还没装 WSL先装好 Ubuntu 发行版再回来后面的命令都假设你在 WSL 终端里执行。2. TaoToken 前置统一 Key 与通道准备TaoToken 在这里的角色是「统一 Key 通道」。OpenCode 本身支持配置多个 provider但如果你手上有多个模型来源逐个配 API Key、逐个改 base_url 会很碎。TaoToken 提供一个统一的 API 入口OpenCode 只需要认一个 Key 和一个 base_url模型切换在服务端完成。你需要先拿到两样东西API Key 和 API 地址。Key 在控制台的 API Keys 页面创建地址是固定的https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 使用。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建时建议给 Key 起一个能区分用途的名字比如opencode-wsl这样以后在控制台看用量时能对上。Key 只在创建时完整显示一次复制后先存到 WSL 的环境变量里不要直接写进会提交到 git 的配置文件。接入文档在这里配置字段有疑问时对照查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你只是想先验证模型通道是否通不想动 OpenCode 配置可以先用模型对话页面发一条测试消息模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite这一步的目的是确认 Key 本身有效、账户有可用额度。很多人后面 OpenCode 报 401回头查半天其实 Key 在创建时就没复制全。先在这里发一条消息能省掉后面大量排查时间。3. 可复制配置config.toml 与 settings.json 骨架OpenCode 的配置分两层一层是 OpenCode 自己的config.toml管 provider 和模型另一层是 Web 服务的settings.json或opencode.json管端口、hostname、密码这些。两者不要混在一起写。先建配置目录。WSL 里的路径按 XDG 规范走mkdir -p ~/.config/opencode然后是~/.config/opencode/config.toml的骨架。关键点是把 provider 的 base_url 指向 TaoToken 的 API 地址apiKey 从环境变量读取不要硬编码# ~/.config/opencode/config.toml # OpenCode provider 配置统一走 TaoToken 通道 [provider.taotoken] name TaoToken baseURL https://taotoken.net/api apiKey {env:TAOTOKEN_API_KEY} # 模型列表按你账户可用的填这里给两个常见示例 [[provider.taotoken.models]] id claude-sonnet-4-20250514 name Claude Sonnet 4 [[provider.taotoken.models]] id gpt-4.1 name GPT-4.1 # 默认使用的模型 [model] provider taotoken name claude-sonnet-4-20250514{env:TAOTOKEN_API_KEY}这个写法是让 OpenCode 从环境变量里取 Key这样配置文件本身可以安全地放进 dotfiles 仓库。环境变量在 WSL 的~/.bashrc或~/.zshrc里设置# 追加到 ~/.bashrc export TAOTOKEN_API_KEY你的Key粘贴在这里改完执行source ~/.bashrc让它生效。验证一下echo $TAOTOKEN_API_KEY | head -c 8能打印出 Key 的前几位就说明环境变量挂上了。接下来是 Web 服务的settings.json。这个文件放在 OpenCode 的工作目录或全局配置目录都行内容如下{ server: { port: 4096, hostname: 0.0.0.0, mdns: false, cors: [] } }这里hostname设成0.0.0.0是为了让 Windows 侧的浏览器能访问到 WSL 里的服务。如果你只在 WSL 内部用localhost访问可以保持127.0.0.1但那样 Windows 浏览器就连不上必须做端口转发。两种方案后面都会讲。port固定成 4096 是为了端口转发时不用每次查随机端口。OpenCode 默认会随机挑端口固定下来省事。关于密码如果OPENCODE_SERVER_PASSWORD没设置Web 服务是无保护状态。仅在 WSL 本机访问时问题不大但一旦做了端口转发让 Windows 或局域网访问就必须设密码。启动时这样写export OPENCODE_SERVER_PASSWORD你设一个密码 opencode web --port 4096 --hostname 0.0.0.0访问时的用户名默认是opencode可以用OPENCODE_SERVER_USERNAME改。4. WSL 端口转发与浏览器验证WSL2 的网络是 NAT 模式WSL 里的0.0.0.0:4096并不会自动映射到 Windows 的localhost:4096。有两种方式打通。第一种是 WSL2 自带的 localhost 转发。较新的 WSL2 版本会自动把 WSL 里监听的端口转发到 Windows 的 localhost但前提是服务绑定在0.0.0.0或127.0.0.1且 WSL 版本支持。你可以先在 Windows 浏览器里直接试http://localhost:4096能打开就说明自动转发生效了不用额外操作。如果打不开用第二种手动端口转发。在 Windows 的 PowerShell管理员权限里执行# 先查 WSL 的 IP wsl hostname -I拿到类似172.24.xxx.xxx的地址后做端口转发# 把 Windows 的 4096 转发到 WSL 的 4096 netsh interface portproxy add v4tov4 listenport4096 listenaddress0.0.0.0 connectport4096 connectaddress172.24.xxx.xxxconnectaddress换成你上一步查到的 WSL IP。然后确认转发规则netsh interface portproxy show v4tov4如果 Windows 防火墙拦了加一条入站规则New-NetFirewallRule -DisplayName OpenCode Web 4096 -Direction Inbound -LocalPort 4096 -Protocol TCP -Action Allow现在在 Windows 浏览器打开http://localhost:4096应该能看到 OpenCode 的 Web 界面。如果设了密码会先弹认证框用户名opencode密码是你设的那个。进入界面后验证会话是否真的走了 TaoToken 通道做这几个检查动作第一看主页的会话列表能否正常创建新会话。点新建会话如果 provider 配置有问题这里会直接报错或模型下拉框为空。第二发一条测试消息比如「用一句话说明这个项目是做什么的」。消息发出后观察返回是否正常。如果返回 401说明 Key 没读到或无效如果返回 404 或 model not found说明模型 id 填错了。第三点界面上的「See Servers」按钮查看已连接服务器状态。这里能看到当前会话绑定的 provider 和模型。确认 provider 显示的是taotoken模型是你配置的那个。第四如果想同时用终端 TUI 和 Web 界面在 WSL 里另开一个终端执行挂载opencode attach http://localhost:4096挂载成功后在终端里发的消息会同步出现在浏览器界面两边共享同一套会话状态。这一步能验证 Web 服务和 TUI 是否连的是同一个后端。5. 本篇常见错排查浏览器打不开 localhost:4096。先确认 WSL 里服务真的在跑curl -I http://localhost:4096在 WSL 终端里执行有响应说明服务正常。然后确认hostname是0.0.0.0而不是127.0.0.1。如果 WSL 自动转发没生效走手动 portproxy 那条路。注意 WSL 重启后 IP 会变portproxy 的connectaddress要重新设可以写个脚本每次开机跑。401 Unauthorized。九成是 Key 没读到。在 WSL 里执行echo $TAOTOKEN_API_KEY确认环境变量有值。如果是在opencode web启动之后才设的环境变量服务进程读不到要重启服务。另外确认config.toml里写的是{env:TAOTOKEN_API_KEY}而不是直接写 Key 字符串。模型下拉框为空或报 model not found。config.toml里[[provider.taotoken.models]]的id必须和 TaoToken 侧实际可用的模型 id 完全一致。去模型对话页面确认一下当前账户能用哪些模型把 id 抄准。[model]段的provider和name要和上面定义的对应。挂载终端时报连接被拒绝。opencode attach的地址要和opencode web启动时的 hostname/port 匹配。如果 web 绑的是0.0.0.0:4096attach 用http://localhost:4096通常没问题如果绑的是 WSL IPattach 也要用那个 IP。另外确认没有多个 OpenCode 实例抢同一个端口。改了 settings.json 但端口没变。命令行标志的优先级高于配置文件。如果你启动时带了--port它会覆盖settings.json里的port。想用配置文件的值启动命令里就不要带--port。浏览器界面能开但发消息一直转圈。检查 WSL 到 TaoToken API 地址的网络连通性curl -I https://taotoken.net/api。如果这里不通OpenCode 的请求也出不去。另外看 OpenCode 的日志输出启动时加--verbose能看到请求详情。6. 长期编码场景的接入建议如果你只是偶尔用浏览器开个会话上面的配置够了。但如果是长期做编码、跑 Agent 任务建议把 Key 管理做得更规范一些。在 TaoToken 控制台里按用途分 Key比如opencode-wsl一个、ci-agent一个这样用量和排查都能对上号。Key 不要写进任何会进版本控制的文件统一走环境变量。WSL 的~/.bashrc里只放 export真正的 Key 值可以放在一个不被 git 跟踪的~/.env.local里再 source 进来。对于需要长时间跑的编码任务可以了解一下 Coding Plan 的额度模式比按次调用更适合持续会话Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteWSL 的 IP 会变这个问题长期来看最好写一个开机脚本自动查 IP 并更新 portproxy 规则。或者干脆用 WSL2 的镜像网络模式在.wslconfig里设networkingModemirrored这样 WSL 和 Windows 共享网络栈localhost 直接通省掉 portproxy 这一层。不过镜像模式对某些网络场景有兼容性问题切换前先确认你的 WSL 版本支持。最后OpenCode 的 Web 界面和 TUI 共享会话状态这个特性在长期编码里很实用浏览器里看整体会话列表和状态终端里做具体操作两边同步。把opencode attach加到日常启动脚本里开一个 web 服务再 attach 一个终端工作流就固定下来了。
1. 为什么要在 WSL 里用浏览器跑 OpenCodeOpenCode 不只是终端里的一个 TUI 工具它还能以完整的 Web 应用形态跑起来直接在浏览器里管理会话、挂载终端、切换模型。对长期在 Windows 上做开发的人来说这件事的价值在于你不需要为了用 AI 编码助手而改变自己的工作流浏览器标签页就是入口。但 Windows 原生环境跑opencode web有几个绕不开的坑。文件系统访问路径和 Linux 不一致终端集成经常出现字符编码或 PTY 分配问题某些依赖在 PowerShell 下的行为和在 bash 下完全不同。我试过直接在 PowerShell 里启动会话能开但挂载终端时反复报错最后还是在 WSL 里跑才稳定下来。所以这篇的路线是在 WSLUbuntu 为例里启动 OpenCode Web 服务通过 TaoToken 统一 Key 接入模型通道再从 Windows 侧的浏览器访问 WSL 的服务端口。整条链路涉及三个配置点——OpenCode 的config.toml、TaoToken 的 Key 管理、WSL 的端口转发。下面按可复制的顺序拆开讲。适合谁看已经在用 WSL 做日常开发、想用浏览器界面管理 OpenCode 会话、并且希望用一个统一 Key 接入多家模型通道的人。如果你还没装 WSL先装好 Ubuntu 发行版再回来后面的命令都假设你在 WSL 终端里执行。2. TaoToken 前置统一 Key 与通道准备TaoToken 在这里的角色是「统一 Key 通道」。OpenCode 本身支持配置多个 provider但如果你手上有多个模型来源逐个配 API Key、逐个改 base_url 会很碎。TaoToken 提供一个统一的 API 入口OpenCode 只需要认一个 Key 和一个 base_url模型切换在服务端完成。你需要先拿到两样东西API Key 和 API 地址。Key 在控制台的 API Keys 页面创建地址是固定的https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base_url 使用。创建 Key 的入口在这里控制台 API Keyshttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建时建议给 Key 起一个能区分用途的名字比如opencode-wsl这样以后在控制台看用量时能对上。Key 只在创建时完整显示一次复制后先存到 WSL 的环境变量里不要直接写进会提交到 git 的配置文件。接入文档在这里配置字段有疑问时对照查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你只是想先验证模型通道是否通不想动 OpenCode 配置可以先用模型对话页面发一条测试消息模型对话https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite这一步的目的是确认 Key 本身有效、账户有可用额度。很多人后面 OpenCode 报 401回头查半天其实 Key 在创建时就没复制全。先在这里发一条消息能省掉后面大量排查时间。3. 可复制配置config.toml 与 settings.json 骨架OpenCode 的配置分两层一层是 OpenCode 自己的config.toml管 provider 和模型另一层是 Web 服务的settings.json或opencode.json管端口、hostname、密码这些。两者不要混在一起写。先建配置目录。WSL 里的路径按 XDG 规范走mkdir -p ~/.config/opencode然后是~/.config/opencode/config.toml的骨架。关键点是把 provider 的 base_url 指向 TaoToken 的 API 地址apiKey 从环境变量读取不要硬编码# ~/.config/opencode/config.toml # OpenCode provider 配置统一走 TaoToken 通道 [provider.taotoken] name TaoToken baseURL https://taotoken.net/api apiKey {env:TAOTOKEN_API_KEY} # 模型列表按你账户可用的填这里给两个常见示例 [[provider.taotoken.models]] id claude-sonnet-4-20250514 name Claude Sonnet 4 [[provider.taotoken.models]] id gpt-4.1 name GPT-4.1 # 默认使用的模型 [model] provider taotoken name claude-sonnet-4-20250514{env:TAOTOKEN_API_KEY}这个写法是让 OpenCode 从环境变量里取 Key这样配置文件本身可以安全地放进 dotfiles 仓库。环境变量在 WSL 的~/.bashrc或~/.zshrc里设置# 追加到 ~/.bashrc export TAOTOKEN_API_KEY你的Key粘贴在这里改完执行source ~/.bashrc让它生效。验证一下echo $TAOTOKEN_API_KEY | head -c 8能打印出 Key 的前几位就说明环境变量挂上了。接下来是 Web 服务的settings.json。这个文件放在 OpenCode 的工作目录或全局配置目录都行内容如下{ server: { port: 4096, hostname: 0.0.0.0, mdns: false, cors: [] } }这里hostname设成0.0.0.0是为了让 Windows 侧的浏览器能访问到 WSL 里的服务。如果你只在 WSL 内部用localhost访问可以保持127.0.0.1但那样 Windows 浏览器就连不上必须做端口转发。两种方案后面都会讲。port固定成 4096 是为了端口转发时不用每次查随机端口。OpenCode 默认会随机挑端口固定下来省事。关于密码如果OPENCODE_SERVER_PASSWORD没设置Web 服务是无保护状态。仅在 WSL 本机访问时问题不大但一旦做了端口转发让 Windows 或局域网访问就必须设密码。启动时这样写export OPENCODE_SERVER_PASSWORD你设一个密码 opencode web --port 4096 --hostname 0.0.0.0访问时的用户名默认是opencode可以用OPENCODE_SERVER_USERNAME改。4. WSL 端口转发与浏览器验证WSL2 的网络是 NAT 模式WSL 里的0.0.0.0:4096并不会自动映射到 Windows 的localhost:4096。有两种方式打通。第一种是 WSL2 自带的 localhost 转发。较新的 WSL2 版本会自动把 WSL 里监听的端口转发到 Windows 的 localhost但前提是服务绑定在0.0.0.0或127.0.0.1且 WSL 版本支持。你可以先在 Windows 浏览器里直接试http://localhost:4096能打开就说明自动转发生效了不用额外操作。如果打不开用第二种手动端口转发。在 Windows 的 PowerShell管理员权限里执行# 先查 WSL 的 IP wsl hostname -I拿到类似172.24.xxx.xxx的地址后做端口转发# 把 Windows 的 4096 转发到 WSL 的 4096 netsh interface portproxy add v4tov4 listenport4096 listenaddress0.0.0.0 connectport4096 connectaddress172.24.xxx.xxxconnectaddress换成你上一步查到的 WSL IP。然后确认转发规则netsh interface portproxy show v4tov4如果 Windows 防火墙拦了加一条入站规则New-NetFirewallRule -DisplayName OpenCode Web 4096 -Direction Inbound -LocalPort 4096 -Protocol TCP -Action Allow现在在 Windows 浏览器打开http://localhost:4096应该能看到 OpenCode 的 Web 界面。如果设了密码会先弹认证框用户名opencode密码是你设的那个。进入界面后验证会话是否真的走了 TaoToken 通道做这几个检查动作第一看主页的会话列表能否正常创建新会话。点新建会话如果 provider 配置有问题这里会直接报错或模型下拉框为空。第二发一条测试消息比如「用一句话说明这个项目是做什么的」。消息发出后观察返回是否正常。如果返回 401说明 Key 没读到或无效如果返回 404 或 model not found说明模型 id 填错了。第三点界面上的「See Servers」按钮查看已连接服务器状态。这里能看到当前会话绑定的 provider 和模型。确认 provider 显示的是taotoken模型是你配置的那个。第四如果想同时用终端 TUI 和 Web 界面在 WSL 里另开一个终端执行挂载opencode attach http://localhost:4096挂载成功后在终端里发的消息会同步出现在浏览器界面两边共享同一套会话状态。这一步能验证 Web 服务和 TUI 是否连的是同一个后端。5. 本篇常见错排查浏览器打不开 localhost:4096。先确认 WSL 里服务真的在跑curl -I http://localhost:4096在 WSL 终端里执行有响应说明服务正常。然后确认hostname是0.0.0.0而不是127.0.0.1。如果 WSL 自动转发没生效走手动 portproxy 那条路。注意 WSL 重启后 IP 会变portproxy 的connectaddress要重新设可以写个脚本每次开机跑。401 Unauthorized。九成是 Key 没读到。在 WSL 里执行echo $TAOTOKEN_API_KEY确认环境变量有值。如果是在opencode web启动之后才设的环境变量服务进程读不到要重启服务。另外确认config.toml里写的是{env:TAOTOKEN_API_KEY}而不是直接写 Key 字符串。模型下拉框为空或报 model not found。config.toml里[[provider.taotoken.models]]的id必须和 TaoToken 侧实际可用的模型 id 完全一致。去模型对话页面确认一下当前账户能用哪些模型把 id 抄准。[model]段的provider和name要和上面定义的对应。挂载终端时报连接被拒绝。opencode attach的地址要和opencode web启动时的 hostname/port 匹配。如果 web 绑的是0.0.0.0:4096attach 用http://localhost:4096通常没问题如果绑的是 WSL IPattach 也要用那个 IP。另外确认没有多个 OpenCode 实例抢同一个端口。改了 settings.json 但端口没变。命令行标志的优先级高于配置文件。如果你启动时带了--port它会覆盖settings.json里的port。想用配置文件的值启动命令里就不要带--port。浏览器界面能开但发消息一直转圈。检查 WSL 到 TaoToken API 地址的网络连通性curl -I https://taotoken.net/api。如果这里不通OpenCode 的请求也出不去。另外看 OpenCode 的日志输出启动时加--verbose能看到请求详情。6. 长期编码场景的接入建议如果你只是偶尔用浏览器开个会话上面的配置够了。但如果是长期做编码、跑 Agent 任务建议把 Key 管理做得更规范一些。在 TaoToken 控制台里按用途分 Key比如opencode-wsl一个、ci-agent一个这样用量和排查都能对上号。Key 不要写进任何会进版本控制的文件统一走环境变量。WSL 的~/.bashrc里只放 export真正的 Key 值可以放在一个不被 git 跟踪的~/.env.local里再 source 进来。对于需要长时间跑的编码任务可以了解一下 Coding Plan 的额度模式比按次调用更适合持续会话Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteWSL 的 IP 会变这个问题长期来看最好写一个开机脚本自动查 IP 并更新 portproxy 规则。或者干脆用 WSL2 的镜像网络模式在.wslconfig里设networkingModemirrored这样 WSL 和 Windows 共享网络栈localhost 直接通省掉 portproxy 这一层。不过镜像模式对某些网络场景有兼容性问题切换前先确认你的 WSL 版本支持。最后OpenCode 的 Web 界面和 TUI 共享会话状态这个特性在长期编码里很实用浏览器里看整体会话列表和状态终端里做具体操作两边同步。把opencode attach加到日常启动脚本里开一个 web 服务再 attach 一个终端工作流就固定下来了。
