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 使用教程