Appearance
OpenCode 可以直接在 Windows 上运行，但推荐通过 WSL（Windows Subsystem for Linux）获得更好的文件系统性能和终端兼容性。本文介绍 WSL 安装 OpenCode、桌面端连接 WSL 服务器、Web 客户端配合 WSL 使用的完整步骤。
OpenCode 可以直接在 Windows 上运行，但官方推荐使用 WSL（Windows Subsystem for Linux）。WSL 提供 Linux 环境，在文件系统性能、终端兼容性和开发工具集成上都有明显优势。
为什么用 WSL？ WSL 拥有更好的文件 I/O 性能、完整的终端支持，以及 OpenCode 依赖的各类 Linux 工具的原生兼容性。
WSL 安装 OpenCode
第一步：安装 WSL
如果还没有安装，参照 微软官方文档 完成安装。
第二步：在 WSL 中安装 OpenCode
打开 WSL 终端，执行：
bash
curl -fsSL https://opencode.ai/install | bash第三步：在项目目录中启动
WSL 通过 /mnt/ 访问 Windows 盘符（C 盘 → /mnt/c/，D 盘 → /mnt/d/）：
bash
cd /mnt/c/Users/YourName/project
opencode桌面端 + WSL 服务器
如果你更喜欢使用图形化桌面端，但想让服务器运行在 WSL 中（享受 Linux 文件系统性能）：
第一步：在 WSL 中启动服务器
bash
opencode serve --hostname 0.0.0.0 --port 4096--hostname 0.0.0.0 让 Windows 可以通过 localhost 访问 WSL 内的服务。
第二步：在桌面端连接
打开 OpenCode 桌面端，在服务器连接处填写 http://localhost:4096。
注意：如果
localhost连接失败，在 WSL 中执行hostname -I获取 WSL IP，改用http://<wsl-ip>:4096连接。
安全提示：对外开放
0.0.0.0时，务必设置OPENCODE_SERVER_PASSWORD：bashOPENCODE_SERVER_PASSWORD=your-password opencode serve --hostname 0.0.0.0
Web 客户端 + WSL
Windows 上最推荐的 Web 使用方式是在 WSL 中启动 Web 服务器：
bash
# 在 WSL 终端中运行
opencode web --hostname 0.0.0.0然后在 Windows 浏览器中打开 OpenCode 显示的 URL（通常是 http://localhost:<port>）。
相比在 PowerShell 中直接运行 opencode web，从 WSL 启动可以获得：
- 正确的文件系统访问（尤其是符号链接和权限）
- 完整的终端集成
- 更好的 Linux 工具链兼容性
访问 Windows 文件
WSL 挂载了所有 Windows 盘符：
| Windows | WSL 路径 |
|---|---|
| C: | /mnt/c/ |
| D: | /mnt/d/ |
| E: | /mnt/e/ |
示例：
bash
cd /mnt/c/Users/YourName/Documents/project
opencode性能提示：如果项目对文件 I/O 性能敏感，考虑把仓库 clone 到 WSL 的 Linux 文件系统（如
~/code/）而不是通过/mnt/访问 Windows 文件。WSL 文件系统的读写速度比跨边界访问快约 5-10 倍。
实用配置建议
- 配合 VS Code：安装 VS Code 的 WSL 扩展，在 WSL 环境中直接打开项目，同时使用 OpenCode TUI 和编辑器
- 会话数据：OpenCode 的配置和会话数据存储在 WSL 环境的
~/.local/share/opencode/中，随 WSL 发行版迁移时记得备份 - 存在 Windows 盘符上的项目：通过
/mnt/c/...路径可以正常工作，只是文件 I/O 比 WSL 原生路径慢
常见问题
Q: WSL 和直接在 Windows PowerShell 中运行 OpenCode 有什么实质区别？
A: 主要区别在于文件系统性能和工具兼容性。PowerShell 环境下，OpenCode 的某些功能（特别是调用 Linux CLI 工具时）可能出现兼容性问题；WSL 提供原生 Linux 环境，这些问题基本不存在。
Q: 安装 WSL 后，原来在 PowerShell 中配置的 OpenCode 还能用吗？
A: 两套环境完全独立，各自有自己的配置和会话数据。建议在 WSL 中重新配置 OpenCode，把 provider API 密钥重新填入。
Q: WSL 中运行 opencode serve --hostname 0.0.0.0 安全吗？
A: 在局域网内使用是可以的，但务必设置 OPENCODE_SERVER_PASSWORD。如果你的电脑在可信局域网内，风险较低；公共网络上不建议暴露。