AI工具

Windows 用 WSL + Ollama 本地部署 Hermes Agent，并接入 Telegram

整理一套适合 Windows 用户的 Hermes Agent 本地部署流程：先装 WSL 和 Ubuntu，再装 Ollama、Gemma 4，并完成 Hermes Agent 与 Telegram 的基础接入。

如果你想在 Windows 上尽量低门槛地跑 Hermes Agent，一个比较顺手的路径是：

  • 宿主系统继续用 Windows
  • 在 WSL 里跑 Ubuntu
  • 用 Ollama 提供本地模型
  • 让 Hermes Agent 直接连接本地 Ollama 接口

这样做的好处是环境相对干净，命令大多按 Linux 方式执行，同时又不需要单独准备一台 Linux 机器。

整体流程

这套部署可以拆成 5 步：

  1. 启用 WSL 并安装 Ubuntu
  2. 在 Ubuntu 里补齐 Python、Node.js、Git 等运行环境
  3. 安装 Ollama 并拉取本地模型
  4. 安装 Hermes Agent，再接入 Telegram

如果你只想先把 Hermes Agent 跑起来，其实做到第 4 步就已经接近完成了。

1. 安装 WSL 和 Ubuntu

在管理员权限的 PowerShell 里执行：

1

wsl --install

安装完成后重启电脑，然后继续安装 Ubuntu：

1

wsl --install -d Ubuntu

之后打开 Windows Terminal，切到 Ubuntu 环境，后续命令基本都在这里执行。

2. 更新 Ubuntu，并安装基础环境

先更新系统：

1
2

sudo apt update
sudo apt upgrade -y

然后安装 Python、解压工具、Node.js 和 Git。

安装 Python 

1

sudo apt install python3-pip python3-venv -y

安装 zstd 

1

sudo apt install -y zstd

安装 Node.js 

1
2

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

安装 Git 

1
2

sudo apt update
sudo apt install -y git

安装完成后可以顺手检查一下：

1
2
3

node -v
npm -v
git --version

3. 安装 Ollama，并拉取 Gemma 4

安装 Ollama：

1

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

如果你打算给 Hermes Agent 配一个本地模型，可以直接从 Gemma 4 开始。

例如：

1

ollama run gemma4:e4b

如果机器资源更弱，也可以试：

1

ollama run gemma4:e2b

更大的版本还有：

1
2

ollama run gemma4:26b
ollama run gemma4:31b

对大多数 Windows + WSL 的普通机器来说，gemma4:e4b 通常是一个更实际的起点。

4. 安装并配置 Hermes Agent

安装命令：

1

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后，给它指定 Ollama 的本地接口：

1

http://127.0.0.1:11434

模型名填你本地实际在用的那个，例如：

1

gemma4:e4b

如果安装脚本要求刷新 shell，可以执行：

1

source ~/.bashrc

Hermes Agent 常用命令

平时最常用的是下面几个：

启动 

1

hermes

重新进入配置 

1

hermes setup

配置聊天平台网关 

1

hermes setup gateway

更新 

1

hermes update

接入 Telegram 的基础步骤

如果你要让 Hermes Agent 通过 Telegram 收发消息，核心还是先跑一遍：

1

hermes setup gateway

然后准备 Telegram 侧需要的两个东西：

  • 用 BotFather 创建机器人
  • 用 @userinfobot 获取你的 User ID

拿到这些基础信息后，再按 Hermes Agent 的网关配置继续填入即可。

这一套方案适合什么人

这套方式比较适合下面几类用户：

  • 平时主力系统就是 Windows
  • 不想单独折腾完整 Linux 主机
  • 想先把本地 Agent 跑通，再慢慢扩展聊天平台接入
  • 希望优先用本地模型，不依赖云端 API

如果你只是想本地体验一个 Agent，而不是一开始就做复杂生产部署，这条路线已经足够实用。

需要注意的几个点

  • WSL 本质上还是一层兼容环境，极端场景下稳定性未必和原生 Linux 完全一样
  • 大模型能不能跑得顺，最终还是取决于你的内存、显存和 CPU / GPU 条件
  • gemma4:e4b 虽然是比较现实的起点，但具体体验还是要看机器配置
  • Hermes Agent 的聊天平台接入属于“能力扩展”，先把本地模型链路跑通，再加 Telegram，会更稳

WSL 中接入 Ollama 与 Codex OSS 本地 Agent

在 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 程序、手机或局域网其他设备中调用时，再单独设计网络暴露方式、反向代理和鉴权。不要把裸露的本地模型端口直接映射到公网。

推荐的资源分级

硬件情况 建议的起步方式
无独显、8GB–16GB 内存 小模型、只读分析、摘要和简单脚本
8GB 显存 7B/8B 量化模型，单用户短到中等上下文
12GB–16GB 显存 8B 更舒适，可谨慎尝试更大量化模型
24GB+ 显存 可考虑更大模型、长上下文或更复杂的本地 Agent 任务

模型越大不代表 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 上尽量简单地本地部署 Hermes Agent，比较顺的顺序就是：

WSL -> Ubuntu -> Ollama -> Gemma 4 -> Hermes Agent -> Telegram

先把本地模型跑通，再做网关接入，成功率会高很多。
对大多数用户来说，这比一上来就堆很多组件更容易排错，也更适合后续继续扩展。

替代后端：Qwen3.6、llama.cpp 与本地 API

Ollama 适合快速起步；如果需要精确控制 GGUF 量化、GPU offload、context 和 chat template，可以把 Hermes 的推理后端换成 llama.cpp。下面的做法不绑定某个第三方量化仓库，先从可信模型卡下载与你硬件匹配的 Qwen3.6 GGUF，并记录文件校验值。

在 WSL 中编译 CUDA 后端：

1
2
3
4
5

sudo apt update
sudo apt install -y git cmake build-essential
git clone https://github.com/ggml-org/llama.cpp.git
cmake -S llama.cpp -B llama.cpp/build -DGGML_CUDA=ON
cmake --build llama.cpp/build --config Release -j

先以 8K context 启动服务，模型路径替换为实际文件。--n-gpu-layers 99 只表示尽量 offload，不保证显存足够；OOM 时减少层数或改用更小量化。

1
2
3
4
5
6

./llama.cpp/build/bin/llama-server \
  --model ~/models/qwen3.6-model.gguf \
  --n-gpu-layers 99 \
  --ctx-size 8192 \
  --host 127.0.0.1 \
  --port 8080

从运行 Hermes 的同一 WSL 环境验证 OpenAI-compatible API：

1
2

curl http://127.0.0.1:8080/v1/models
curl http://127.0.0.1:8080/health

然后执行 hermes setup，自定义 endpoint 填 http://127.0.0.1:8080/v1，模型名使用 /v1/models 实际返回的 ID，API Key 仅填本机占位值。先测对话，再测工具调用与文件权限；文字能返回但 tool call 反复失败，通常是模型能力或 chat template 不匹配，不是端口问题。

需要调整 thinking 时，优先使用模型卡和当前 llama.cpp 版本支持的 chat-template 参数，不要照抄旧教程中的 JSON 开关。每次只改模型、context、GPU layers 或 template 中的一项，并保留可工作的启动命令。服务只监听 127.0.0.1；若必须跨设备访问，应在反向代理层增加认证和 TLS。