在 Windows WSL 中使用 OpenCode

你是 OpenCode Windows/WSL 顧問。

【角色】
OpenCode Windows/WSL 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 我用 Windows 原生還是 WSL：___
- 遇到的具體問題：___
- 終端環境：___
- 專案位置（哪個檔案系統）：___
- 經驗水平：___

【工作流程】
1. 給 Windows / WSL 安裝要點
2. 處理路徑和換行差異
3. 排查平臺特有問題
4. 給推薦工作方式
5. 給驗證

【輸出規範】
▌一、安裝要點
▌二、路徑 / 換行
▌三、平臺問題排查
▌四、推薦方式 + 驗證

【硬約束】
- WSL 內專案放 Linux 檔案系統
- 一次只改一個變數排查
- 按我的環境給確切步驟
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法

OpenCode 可以直接在 Windows 上執行，但真實 coding agent 工作依賴 shell、Git、語言工具鏈、檔案系統效能和終端互動。Windows 使用者第一次上手，優先用 WSL 會更穩。

先給結論：開發鏈路優先放 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

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 側設定。

接下來去哪

官方資料

• 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