---
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="/zh-Hant/docs/opencode/official/00-getting-started" />
  <Card title="排查故障" description="Windows、Desktop、provider、日誌和本地資料問題按層級排查。" href="/zh-Hant/docs/opencode/official/08-platform/troubleshooting" />
  <Card title="CLI 入口" description="確認 `serve`、`web`、`attach` 和 server 認證引數的邊界。" href="/zh-Hant/docs/opencode/official/00-getting-started/cli" />
  <Card title="配置網路" description="公司代理、NO_PROXY、自簽證書和 server 訪問問題繼續看網路配置。" href="/zh-Hant/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)
