在 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 入口

配置網路

本頁目錄