在 Windows WSL 中使用 OpenCode

OpenCode 可以直接在 Windows 上运行，但真实 coding agent 工作依赖 shell、Git、语言工具链、文件系统性能和终端交互。Windows 用户第一次上手，优先用 WSL 会更稳。

这一篇用 8 分钟换什么：你会知道为什么推荐 WSL、仓库应该放在哪里、Desktop/Web 怎么连接 WSL 里的 OpenCode server，以及什么时候需要设置 server password。

先给结论：开发链路优先放 WSL

如果只是试用，可以在 Windows 原生环境里跑；如果要进入真实项目，优先把开发链路放在 WSL 里。

flowchart LR
  Windows["Windows 桌面"] --> WSL["WSL Linux 环境"]
  WSL --> Repo["仓库优先放 ~/code"]
  WSL --> TUI["opencode TUI"]
  WSL --> Server["opencode serve / web"]
  Server --> Desktop["Windows Desktop / 浏览器连接"]

  style WSL fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
  style Repo fill:#dcfce7,stroke:#22c55e
  style Server fill:#fef3c7,stroke:#f59e0b

WSL 的价值不是“Linux 更高级”，而是它让终端、文件权限、语言工具链和开源项目默认假设更一致。

安装路径

如果还没有 WSL，先按 Microsoft 官方文档安装 WSL。完成后打开 WSL 终端，在 WSL 里安装 OpenCode：

curl -fsSL https://opencode.ai/install | bash

安装后先验证命令：

opencode --help

不要在 PowerShell 和 WSL 里各装一套后混着用。先选一条主路径，否则后面会分不清配置、凭据和会话数据到底在哪个环境里。

仓库放在哪里

WSL 可以通过 /mnt/ 访问 Windows 文件：

C: 盘对应 /mnt/c/
D: 盘对应 /mnt/d/
其他盘符以此类推

例如：

cd /mnt/c/Users/YourName/Documents/project
opencode

但长期开发更推荐把仓库克隆到 WSL 文件系统，例如：

mkdir -p ~/code
cd ~/code
git clone <repo-url>
cd <repo>
opencode

原因很简单：跨 /mnt/c 访问 Windows 文件通常性能和权限语义都更复杂。真实项目、频繁读写、依赖安装、测试和格式化，放在 WSL 文件系统里更稳。

Desktop 应用连接 WSL server

如果你希望用 Windows 上的 OpenCode Desktop，同时让实际 server 跑在 WSL 中，可以在 WSL 里启动：

OPENCODE_SERVER_PASSWORD=change-me opencode serve --hostname 0.0.0.0 --port 4096

然后在 Desktop 里连接：

http://localhost:4096

如果 localhost 在你的环境里无法使用，在 WSL 中查看 IP：

hostname -I

再用：

http://<wsl-ip>:4096

使用 --hostname 0.0.0.0 时必须设置 OPENCODE_SERVER_PASSWORD。不要把没有认证的 OpenCode server 暴露给局域网或公网。

Web 客户端连接 WSL

如果要用 Web UI，也建议在 WSL 终端中运行，而不是在 PowerShell 中运行：

opencode web --hostname 0.0.0.0

OpenCode 会输出访问 URL。然后在 Windows 浏览器里打开对应地址。

这样做能让文件系统访问和终端工具链留在 WSL，同时保留 Windows 浏览器使用体验。

配置和数据在哪里

在 WSL 中运行 OpenCode 时，配置和会话数据属于 WSL 环境，不是 Windows 用户目录。

常见路径：

WSL OpenCode 数据：~/.local/share/opencode/
WSL 全局配置：~/.config/opencode/
项目配置：仓库里的 opencode.json 和 .opencode/

如果你在 Windows 原生环境和 WSL 里都运行过 OpenCode，不要假设它们共享同一份 auth、session、plugin 或配置。

使用建议

真实项目优先放 ~/code/ 这类 WSL 文件系统目录。
需要 Windows IDE 时，用 VS Code WSL 扩展连接 WSL 项目。
在 WSL 里安装项目依赖、运行测试和启动 OpenCode。
只把 Desktop 或浏览器当客户端，不要把真实开发链路拆到两个系统里。
server 绑定到 0.0.0.0 前，先设置密码并确认网络边界。

常见问题先这样排

opencode 找不到：确认你在 WSL 里安装，并检查 WSL 的 $PATH。
Windows 浏览器连不上 WSL server：先试 localhost，再查 hostname -I。
文件读写很慢：确认仓库是否在 /mnt/c，长期项目迁到 ~/code/。
Desktop 连接失败：确认 WSL 里的 server 是否启动，端口是否一致，密码是否设置。
provider 失败：检查 WSL 环境里的网络、代理和凭据，不要只看 Windows 侧配置。

接下来去哪

入门

按第一天安全闭环重新确认安装、provider、项目初始化和低风险写入。

排查故障

Windows、Desktop、provider、日志和本地数据问题按层级排查。

CLI 入口

确认 `serve`、`web`、`attach` 和 server 认证参数的边界。

配置网络

公司代理、NO_PROXY、自签证书和 server 访问问题继续看网络配置。

官方资料

OpenCode Windows / WSL：https://opencode.ai/docs/windows-wsl
Microsoft WSL install：https://learn.microsoft.com/en-us/windows/wsl/install
VS Code WSL：https://code.visualstudio.com/docs/remote/wsl
OpenCode troubleshooting：https://opencode.ai/docs/troubleshooting

在 Windows WSL 中使用 OpenCode

入门

排查故障

CLI 入口

配置网络

本页目录