---
title: "在 Windows WSL 中使用 OpenCode"
description: "通过 WSL 在 Windows 上运行 OpenCode，处理文件系统、Desktop/Web 连接和安全边界。"
verifiedAt: "2026-05-09"
---

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

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

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

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

```mermaid
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：

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

安装后先验证命令：

```bash
opencode --help
```

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

## 仓库放在哪里

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

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

例如：

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

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

```bash
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 里启动：

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

然后在 Desktop 里连接：

```text
http://localhost:4096
```

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

```bash
hostname -I
```

再用：

```text
http://<wsl-ip>:4096
```

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

## Web 客户端连接 WSL

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

```bash
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 侧配置。

## 接下来去哪

<Cards>
  <Card title="入门" description="按第一天安全闭环重新确认安装、provider、项目初始化和低风险写入。" href="/docs/opencode/official/00-getting-started" />
  <Card title="排查故障" description="Windows、Desktop、provider、日志和本地数据问题按层级排查。" href="/docs/opencode/official/08-platform/troubleshooting" />
  <Card title="CLI 入口" description="确认 `serve`、`web`、`attach` 和 server 认证参数的边界。" href="/docs/opencode/official/00-getting-started/cli" />
  <Card title="配置网络" description="公司代理、NO_PROXY、自签证书和 server 访问问题继续看网络配置。" href="/docs/opencode/official/05-security/network" />
</Cards>

## 官方资料

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