Windows WSL 部署本地 Agent 教程：Ollama、Codex OSS 和權限控制

在 Windows 上部署本地 Agent，最省心的結構通常不是把模型服務、Docker、終端和代碼工具散落在 Windows、WSL 與多個虛擬環境裏，而是把它們放進同一個 WSL2 Ubuntu 發行版：

1
2
3
4
5
6

Windows
└─ WSL2 Ubuntu
   ├─ Ollama：本地模型服务
   ├─ 本地模型：聊天、代码、Embedding
   ├─ Codex OSS：Agent 客户端
   └─ 项目目录：代码、Git、测试命令

這樣 Ollama 和 Agent 直接通過 WSL 內的 localhost 通信，路徑、權限和日誌都在 Linux 環境內。Windows 端可以繼續用 Windows Terminal、VS Code Remote WSL 或資源管理器訪問項目。

先說結論

最小可用路線是：

1
2
3
4
5
6

安装 WSL2 Ubuntu
-> 在 Ubuntu 安装 Ollama 和一个小模型
-> 在 Ubuntu 内验证 ollama run
-> 用 codex --oss --local-provider ollama 启动 Agent
-> 先执行只读任务
-> 再逐步允许修改、测试和工具调用

不要一開始就讓本地 Agent 獲得全盤權限，也不要先追求最大的模型。先用能穩定運行的模型驗證流程，比先折騰複雜代理、遠程端口和多 Agent 編排更重要。

第一步：安裝 WSL2 和 Ubuntu

在 Windows 的管理員 PowerShell 中執行：

1

wsl --install

重啓後，默認會安裝 Ubuntu。首次打開 Ubuntu 時，按提示創建 Linux 用戶名和密碼。

確認發行版使用 WSL2：

1

wsl -l -v

如果舊發行版仍是版本 1，可轉換：

1

wsl --set-version Ubuntu 2

進入 Ubuntu：

1

wsl

後續大部分命令都在 Ubuntu 終端裏執行，而不是 PowerShell。

第二步：準備 Ubuntu 基礎環境

進入 WSL 後先更新系統：

1
2
3

sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git ca-certificates

確認環境：

1
2
3

uname -a
pwd
git --version

項目建議放在 Linux 文件系統內，例如：

1
2

mkdir -p ~/projects
cd ~/projects

不要把高頻 Git、Node.js、Python 虛擬環境和大規模依賴都放在 /mnt/c/... 下運行。跨文件系統訪問在某些開發任務裏會更慢，也更容易遇到權限和文件監聽差異。需要從 Windows 打開項目時，可使用 VS Code 的 Remote WSL 功能。

第三步：在 WSL 內安裝並驗證 Ollama

按 Ollama Linux 安裝方式執行：

1

curl -fsSL https://ollama.com/install.sh | sh

先在當前終端啓動服務：

1

ollama serve

另開一個 WSL 終端，下載並測試一個模型：

1
2

ollama pull qwen3:8b
ollama run qwen3:8b

模型選擇必須按你的 GPU 顯存或 CPU/內存決定。沒有可用 GPU 時，先用更小模型驗證流程；不要把“大模型文件能下載”誤認爲“本機能流暢推理”。

確認服務和模型狀態：

1
2

ollama ls
ollama ps

如果 ollama run 本身不能穩定輸出，先解決模型、顯存、驅動或內存問題，再接 Agent。

第四步：檢查 WSL GPU 是否真的可用

有 NVIDIA GPU 時，在 WSL 內執行：

1

nvidia-smi

能顯示顯卡不等於 Ollama 已經使用 GPU，但它至少證明 WSL 看到了驅動。啓動模型後，再執行：

1
2

ollama ps
nvidia-smi

觀察模型是否使用 GPU、顯存是否增長。

如果 nvidia-smi 不存在或報錯，先檢查 Windows 的 NVIDIA 驅動、WSL 版本和 GPU 支持，不要急着在 Ubuntu 內反覆安裝桌面 Linux 驅動。WSL 的 GPU 支持有自己的驅動鏈路。

第五步：讓 Codex 使用本地 Ollama

Codex 提供 OSS 模式，可選擇 Ollama 或 LM Studio 作爲本地提供方。在 WSL 內安裝並可運行 Codex 後，進入你的項目目錄：

1

cd ~/projects/your-project

首次建議使用只讀權限啓動：

1

codex --oss --local-provider ollama --sandbox read-only

先給一個不修改文件的任務：

1

阅读当前仓库的 README 和目录结构，说明启动、测试和构建命令。不要修改任何文件。

確認本地模型能讀懂倉庫、回答穩定後，再按需使用 workspace 寫入權限。不要因爲它是本地模型，就跳過 Git、測試和權限控制。

如果想把 Ollama 作爲默認本地提供方，在用戶級 Codex 配置 ~/.codex/config.toml 加入：

1

oss_provider = "ollama"

之後用下面命令即可：

1

codex --oss

注意，提供方相關配置應放在用戶級配置中，而不是項目裏的 .codex/config.toml。項目配置不應偷偷改變你機器的模型提供方。

第六步：需要常駐服務時啓用 systemd

新安裝的 WSL Ubuntu 通常已默認使用 systemd。先檢查：

1

systemctl status

若當前發行版沒有啓用 systemd，編輯：

1

sudo nano /etc/wsl.conf

加入：

1
2

[boot]
systemd=true

然後回到 Windows PowerShell：

1

wsl --shutdown

重新進入 Ubuntu 後再檢查 systemctl status。

是否把 Ollama 做成常駐服務，要看安裝方式和你是否需要後臺 API。剛開始學習時，保持一個 ollama serve 終端最容易看到日誌；確認穩定後，再用 systemd 管理服務。

WSL 內的路徑、端口和 API

默認情況下，Ollama 服務使用：

1

http://localhost:11434

如果 Agent、腳本和 Ollama 都在同一個 WSL 發行版中，優先使用這個本地地址，不需要先開放局域網端口。

測試 API：

1

curl http://localhost:11434/api/tags

需要在 Windows 程序、手機或局域網其他設備中調用時，再單獨設計網絡暴露方式、反向代理和鑑權。不要把裸露的本地模型端口直接映射到公網。

推薦的資源分級

模型越大不代表 Agent 越可靠。對本地 Agent 來說，命令執行穩定性、上下文、工具調用能力和任務拆分方式，同樣影響結果。

最容易踩的坑

1. Windows 和 WSL 各跑了一套 Ollama

這會讓你分不清 Agent 實際連到哪一個服務。初次部署建議只在 WSL 內運行一套 Ollama，所有測試都在同一個 WSL 終端完成。

2. 在 /mnt/c 裏跑所有開發任務

可以訪問，但依賴安裝、文件監聽、Git 性能和 Linux 權限行爲未必理想。優先把活躍項目放到 ~/projects。

3. 本地模型一開始就允許寫文件

先用 --sandbox read-only 驗證模型是否理解任務。進入修改階段後，也應先讓它說明計劃，再檢查 diff、運行測試並用 Git 保留回退點。

4. 端口開放後沒有鑑權

本地 API 一旦允許局域網訪問，就不再只是“自己電腦上的服務”。至少限制防火牆來源，必要時在反向代理層增加鑑權和 HTTPS。

5. 以爲安裝成功就會自動後臺運行

WSL 關閉或發行版被停止後，前臺進程會退出。需要長期 API 時，先確認 systemd、服務狀態和 Windows/WSL 的運行策略。

總結

Windows WSL 部署本地 Agent，最可靠的第一版是：

1
2
3
4
5

WSL2 Ubuntu
-> Ollama 跑通小模型
-> Codex OSS 模式只读分析仓库
-> Git 和测试验证
-> 再增加写权限、服务常驻和局域网 API

讓模型、Agent 和代碼都在同一個 WSL 環境裏，能減少一半以上的路徑、端口和權限問題。等最小流程穩定後，再考慮 Docker、多模型路由、RAG 或遠程訪問。

參考：

• Microsoft Learn：安裝 WSL
• Microsoft Learn：WSL systemd
• Ollama Linux 文檔
• Codex OSS 本地提供方
• 本地大模型 API 給 Codex 使用教程