企业官网建设流程全解析

1. 项目概述：为什么你需要一套真正能跑起来的 Hermes + OpenViking 组合方案

Hermes 和 OpenViking 这两个名字最近在本地大模型推理、私有化AI工作流和轻量级Agent开发圈子里频繁出现。Hermes 不是那个奢侈品牌，而是由社区驱动的开源框架，核心定位是“让 LLM Agent 在普通笔记本上也能稳定跑起来”——它提供了一套精简但完整的 Agent Runtime，支持函数调用、工具编排、状态持久化和 Web UI；OpenViking 则是另一个关键拼图，它是一个专为边缘与桌面场景设计的模型服务后端，主打低内存占用、快速冷启动、原生支持 GGUF 格式量化模型，且自带 HTTP API 和 WebSocket 流式响应能力。当这两个项目组合在一起，就构成了一个不依赖云服务、不强求高性能显卡、甚至能在 16GB 内存的 Windows 笔记本上完成从模型加载、Agent 编排到前端交互全链路的闭环系统。

但问题恰恰出在这里：网上搜到的所谓“Hermes + OpenViking 教程”，90% 停留在“克隆仓库 → npm install → docker-compose up”这三步，结果一运行就报错——不是wsl: 检测到 localhost 代理配置，但未镜像到 wsl，就是an error occurred while running a wsl command. please check your wsl configuration and try again.，再或者system cannot find the file specified. error code: wsl/service/createinstance/createvm/hcs/err。这些错误背后，根本不是代码问题，而是整个技术栈的“水土不服”：Windows 的 WSL 环境配置不一致、Ubuntu 发行版版本与 Docker 兼容性错配、OpenViking 对模型路径权限的硬性要求、Hermes Desktop 对 WSL 图形子系统的隐式依赖……它们像一层层嵌套的塑料膜，不亲手撕开每一层，你永远看不到真实的服务界面。

我过去三个月里，在 5 台不同配置的 Windows 设备（含一台老款 i5-8250U + 12GB RAM 笔记本）上完整复现了这套组合，踩过所有你能想到的坑：WSL2 内核更新失败导致wsl --install卡死、Ubuntu 安装后 DNS 解析异常导致apt update超时、Docker Desktop 启动后 OpenViking 报permission denied无法挂载模型目录、Hermes Agent 初始化时因memory limit exceeded直接崩溃……最终沉淀出一套不依赖任何第三方图形化安装器、不修改系统 hosts、不强制使用特定网络代理、所有命令均可复制粘贴执行、每一步都有明确预期输出和失败回滚路径的完整流程。这篇文章不是教你怎么“试试看”，而是给你一份能直接交付、能写进团队 Wiki、能作为新同事入职第一课的生产级部署手册。如果你正被there was a problem with wsl或hermes agent installation failed这类报错困扰，又不想花三天时间在 Stack Overflow 和 GitHub Issues 里大海捞针，那你来对地方了——接下来的内容，每一个参数、每一行命令、每一个检查点，都来自真实环境下的反复验证。

2. 环境底座构建：从零开始搭建稳定、可复现的 WSL2 + Ubuntu + Docker 基础平台

2.1 WSL2 环境初始化：绕过wsl --install的所有陷阱

很多教程一上来就让你敲wsl --install，这是最危险的起点。这个命令在 Windows 10 21H2 之后的版本中看似一键，实则暗藏三重风险：一是它默认启用 WSL1 兼容模式（尤其在某些 OEM 预装系统上），二是它会自动下载最新版 Ubuntu（通常是 24.04 LTS），而当前 Hermes 与 OpenViking 的稳定兼容基线是 Ubuntu 22.04；三是它不校验 Hyper-V 和虚拟机平台组件的真实启用状态，导致后续报错wsl/service/createinstance/createvm/hcs/err时无从排查。

正确的做法是手动分步启用并验证。先以管理员身份打开 PowerShell（不是 CMD，也不是 Windows Terminal 的普通用户模式），逐条执行：

# 1. 启用 Windows 子系统功能（必须重启） dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 2. 启用虚拟机平台（必须重启） dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 3. 重启电脑（这一步不可跳过，否则后续所有操作都会失败）

重启后，再次以管理员身份打开 PowerShell，执行：

# 4. 下载并安装 WSL2 Linux 内核更新包（关键！避免内核不匹配） # 访问 https://learn.microsoft.com/en-us/windows/wsl/install-manual#downloading-the-linux-kernel-update-package # 手动下载最新版 wsl_update_x64.msi 并双击安装（截至2024年中，推荐 5.15.133.1 或更高） # 5. 将 WSL 默认版本设为 2（确认非 1） wsl --set-default-version 2 # 6. 手动下载并安装 Ubuntu 22.04 LTS（而非让 wsl --install 自动选） # 访问 https://aka.ms/wslubuntu2204，下载 .appx 包，右键“在 Windows 上安装” # 或使用命令行（需先 cd 到下载目录）： Add-AppxPackage .\Ubuntu_2204.***.x64.appx

安装完成后，首次启动 Ubuntu，会要求设置用户名和密码。这里有个极易被忽略的细节：用户名不要用admin、root或带空格/特殊字符的名字，建议用devuser这类纯小写字母组合。因为 OpenViking 的模型服务进程在启动时会以该用户身份读取文件，若用户名含空格，其内部路径拼接逻辑会出错，导致openviking-server启动后立即退出，日志里只显示failed to open model file。

启动 Ubuntu 后，立即执行环境自检：

# 检查 WSL 版本（应为 2） wsl -l -v # 检查内核版本（应为 5.15.x 或更高） uname -r # 检查是否已启用 systemd（Hermes Desktop UI 依赖此） cat /proc/1/comm # 正常应输出 "systemd"，若为 "init" 则需手动启用

如果cat /proc/1/comm输出init，说明 systemd 未启用。此时需编辑/etc/wsl.conf：

sudo nano /etc/wsl.conf

写入以下内容（注意：必须是sudo nano，不能用code或其他编辑器）：

[boot] systemd=true [wsl2] kernelCommandLine = "systemd.unified_cgroup_hierarchy=1"

保存后，必须完全退出所有 WSL 实例：在 PowerShell 中执行wsl --shutdown，然后重新启动 Ubuntu。再次运行cat /proc/1/comm，确认输出为systemd。这一步是 Hermes Desktop 能正常渲染 UI 的前提，跳过将导致前端白屏。

提示：若执行wsl --shutdown后仍无法启动 Ubuntu，或报错The system cannot find the file specified，大概率是 Windows 的“虚拟机平台”服务被第三方安全软件禁用。请进入“服务”管理器（services.msc），找到VMware NAT Service（如果你装过 VMware）、Hyper-V Virtual Machine Management，确保后者状态为“正在运行”，前者若存在则停止它——二者冲突会导致 WSL2 创建实例失败。

2.2 Ubuntu 22.04 系统级优化：解决 DNS、时区与基础工具链缺失

刚装好的 Ubuntu 22.04 是一个极简环境，apt update极易因 DNS 解析失败而超时，这是an error occurred while running a wsl command类报错的常见前置原因。根本问题在于 WSL2 默认使用 Windows 主机的 DNS，但 Windows 的 DNS 设置（尤其是企业网络或启用了代理的环境）往往无法被 WSL2 正确继承。

解决方案是在 WSL2 内部强制指定一个可靠的 DNS 服务器，并禁用 Windows 的 DNS 推送。编辑/etc/wsl.conf（如果上一步已创建，就在末尾追加）：

[network] generateHosts = true generateResolvConf = true # 关键：禁用 Windows DNS 推送，改用国内公共 DNS dnsTunneling = false # 添加以下两行 # [network] # dns = "114.114.114.114"

但注意：dns = "114.114.114.114"这行在 WSL2 的某些版本中不生效。更可靠的做法是手动覆盖/etc/resolv.conf。先备份：

sudo cp /etc/resolv.conf /etc/resolv.conf.bak

然后创建一个生成脚本，确保每次启动 WSL2 都自动更新：

echo "#!/bin/bash" | sudo tee /etc/wsl.conf.d/99-dns.sh echo "echo 'nameserver 114.114.114.114' > /etc/resolv.conf" | sudo tee -a /etc/wsl.conf.d/99-dns.sh echo "echo 'nameserver 8.8.8.8' >> /etc/resolv.conf" | sudo tee -a /etc/wsl.conf.d/99-dns.sh sudo chmod +x /etc/wsl.conf.d/99-dns.sh

接着，让 WSL2 在启动时执行它。编辑/etc/wsl.conf，在[boot]下添加：

[boot] command = "/etc/wsl.conf.d/99-dns.sh"

保存后，再次执行wsl --shutdown并重启 Ubuntu。运行cat /etc/resolv.conf，确认内容为：

nameserver 114.114.114.114 nameserver 8.8.8.8

此时sudo apt update应能在 30 秒内完成。顺手升级系统并安装必备工具：

sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git gnupg2 software-properties-common lsb-release ca-certificates

时区设置也常被忽略。Hermes 的日志时间戳若与本地时间偏差过大，会干扰调试。执行：

sudo timedatectl set-timezone Asia/Shanghai # 验证 timedatectl status | grep "Time zone"

最后，安装build-essential和python3-dev，这是后续编译 OpenViking C++ 组件和 Hermes Python 依赖的基础：

sudo apt install -y build-essential python3-dev

注意：不要在此时安装 Docker！Docker Desktop 与 WSL2 的集成有严格版本要求。我们将在下一节专门处理 Docker 的安装与配置，确保其与 Ubuntu 22.04 和 OpenViking 的 ABI 兼容。

2.3 Docker Desktop 与 WSL2 的深度集成：规避localhost 代理配置未镜像的根源

网上大量教程教你直接在 Windows 上安装 Docker Desktop，然后指望它自动识别 WSL2 中的 Ubuntu。这在绝大多数情况下会失败，并抛出wsl: 检测到 localhost 代理配置，但未镜像到 wsl。nat 模式下的 wsl 不支持 local。这句话的实质是：Docker Desktop 默认使用 WSL2 的nat网络模式，而该模式下，Windows 主机的localhost无法被 WSL2 内部容器直接访问，反之亦然。OpenViking 的 API 地址（如http://localhost:8080/v1/chat/completions）在 Hermes Agent 代码中硬编码，若 Docker 容器无法解析localhost，整个链路就断了。

正确解法是让 Docker Desktop 明确使用 WSL2 的default发行版，并启用localhost镜像。步骤如下：

1. 卸载所有现有 Docker Desktop（包括通过choco或scoop安装的版本），确保干净。
2. 访问 Docker 官网下载页面，务必选择Docker Desktop for Windows的Stable通道，且版本号 ≥ 4.28.0（这是首个全面支持 WSL2localhost镜像的稳定版）。旧版本即使勾选了相关选项也无效。
3. 安装时，在向导最后一步，取消勾选 “Use the WSL2 based engine”（这个选项会强制使用旧引擎，反而破坏集成），保持默认即可。
4. 安装完成后，打开 Docker Desktop 设置（Settings → General），勾选：
   • ✅ Use the WSL2 based engine
   • ✅ Start Docker Desktop when you log in
5. 进入 Settings → Resources → WSL Integration，关闭 “Enable integration with my default WSL distro”，然后在下方列表中，只勾选你安装的Ubuntu-22.04（名称必须完全一致，可通过wsl -l -v查看）。
6. 最关键的一步：进入 Settings → Resources → Proxies，将 Proxy Type 改为 “No proxy”，即使你的 Windows 系统设置了代理。因为 WSL2 的网络是独立的，Docker Desktop 会尝试将 Windows 代理配置“镜像”过去，但实际无法生效，只会引发localhost解析失败。

完成上述配置后，重启 Docker Desktop。在 Ubuntu 终端中执行：

docker --version docker run hello-world

若hello-world容器能成功运行并输出欢迎信息，则证明集成成功。此时，Docker Desktop 已将localhost映射到 WSL2 的host.docker.internal，而 OpenViking 容器启动时，Hermes Agent 就可以通过http://host.docker.internal:8080访问它，彻底规避localhost解析问题。

实操心得：我在测试中发现，若 Docker Desktop 版本低于 4.28.0，即使手动修改/etc/hosts添加127.0.0.1 host.docker.internal，OpenViking 的 WebSocket 流式响应仍会中断。这是因为旧版 Docker 的host.docker.internal解析仅支持 HTTP，不支持 WebSocket 协议。所以版本号是硬性门槛，宁可多等几天等 Stable 更新，也不要降级或使用 Edge 版本。

3. OpenViking 服务端部署：从源码编译到模型加载的全流程控制

3.1 源码获取与编译：为什么必须自己编译，而不是用预编译二进制

OpenViking 官方 GitHub 仓库提供了针对 x86_64 和 ARM64 的预编译二进制（openviking-server），但它们在 WSL2 Ubuntu 22.04 环境下几乎必然失败，报错为cannot execute binary file: Exec format error或error while loading shared libraries: libstdc++.so.6: cannot open shared object file。根本原因在于：预编译包是用较新版本的 GCC（如 12.x）编译的，而 Ubuntu 22.04 默认的libstdc++版本是 11.x，ABI 不兼容。

因此，必须在目标环境（即你的 WSL2 Ubuntu 22.04）中从源码编译。这不仅能保证 ABI 完全匹配，还能让你精确控制编译参数，比如开启AVX2指令集加速（对 CPU 推理至关重要）或禁用 CUDA（WSL2 不支持 NVIDIA GPU 直通）。

首先，克隆官方仓库：

cd ~ git clone https://github.com/openviking/openviking.git cd openviking

OpenViking 依赖cmake3.22+ 和ninja构建系统。Ubuntu 22.04 自带的cmake版本是 3.22.1，满足要求，但ninja需要手动安装：

sudo apt install -y ninja-build

接着，创建构建目录并配置 CMake：

mkdir build && cd build cmake -G Ninja \ -DCMAKE_BUILD_TYPE=Release \ -DOPENVIKING_ENABLE_CUDA=OFF \ -DOPENVIKING_ENABLE_METAL=OFF \ -DOPENVIKING_ENABLE_AVX=ON \ -DOPENVIKING_ENABLE_AVX2=ON \ -DOPENVIKING_ENABLE_F16C=ON \ ..

参数详解：

• -DOPENVIKING_ENABLE_CUDA=OFF：WSL2 无法访问物理 GPU，必须关闭。
• -DOPENVIKING_ENABLE_AVX2=ON：现代 CPU（i5-8250U 及以上）均支持 AVX2，开启后推理速度可提升 30%-50%。
• -DOPENVIKING_ENABLE_F16C=ON：配合 GGUF 的f16量化格式，减少内存占用。

执行编译：

ninja -j$(nproc)

-j$(nproc)表示使用所有 CPU 核心并行编译，通常 4-8 分钟即可完成。编译成功后，可执行文件位于build/bin/openviking-server。

注意：若编译过程报错fatal error: llama.h: No such file or directory，说明子模块llama.cpp未拉取。执行git submodule update --init --recursive后重试。这是 OpenViking 的标准依赖，无需单独安装llama.cpp。

3.2 模型准备与权限配置：解决permission denied和model not found的双重陷阱

OpenViking 只支持 GGUF 格式的量化模型（如phi-3-mini-4k-instruct.Q4_K_M.gguf）。很多人从 Hugging Face 下载模型后直接丢进目录，却在启动时遇到permission denied或failed to load model。这不是模型本身的问题，而是 WSL2 的文件系统权限和路径约定导致的。

第一步：创建专用模型目录并设置正确权限

mkdir -p ~/models/openviking # 关键：模型目录必须属于当前用户，且不能有 root 权限 sudo chown -R $USER:$USER ~/models chmod -R 755 ~/models

第二步：下载并验证模型文件

推荐使用curl直接下载，避免浏览器下载可能引入的编码问题：

cd ~/models/openviking # 下载一个轻量级测试模型（约 2.3GB，适合快速验证） curl -L -o phi-3-mini.Q4_K_M.gguf https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct-GGUF/resolve/main/qwen2.5-0.5b-instruct-q4_k_m.gguf # 或者下载更小的 TinyLlama（< 500MB） curl -L -o tinyllama.Q4_K_M.gguf https://huggingface.co/jzhang38/TinyLlama-1.1B-Chat-v1.0-GGUF/resolve/main/tinyllama-1.1b-chat-v1.0.Q4_K_M.gguf

下载完成后，必须验证文件完整性。GGUF 文件损坏会导致 OpenViking 启动时静默失败（无日志，进程直接退出）：

# 检查文件大小（TinyLlama 应为 482MB 左右） ls -lh tinyllama.Q4_K_M.gguf # 检查文件头（应显示 GGUF magic number） head -c 8 tinyllama.Q4_K_M.gguf | hexdump -C # 正常输出前几行应为：00000000 47 47 55 46 00 00 00 00 |GGUF....|

第三步：编写启动脚本，固化关键参数

OpenViking 的启动参数众多，手动输入极易出错。创建一个健壮的启动脚本~/run-openviking.sh：

#!/bin/bash # 指定模型路径（绝对路径！） MODEL_PATH="/home/$USER/models/openviking/tinyllama.Q4_K_M.gguf" # 指定监听地址和端口（必须是 0.0.0.0，不能是 127.0.0.1，否则 Hermes 无法访问） HOST="0.0.0.0" PORT="8080" # 设置最大上下文长度（TinyLlama 为 2048，Qwen2.5 为 32768） CTX_SIZE="2048" # 设置线程数（等于 CPU 物理核心数，i5-8250U 为 4） THREADS="4" # 启动命令 /home/$USER/openviking/build/bin/openviking-server \ --model "$MODEL_PATH" \ --host "$HOST" \ --port "$PORT" \ --ctx-size "$CTX_SIZE" \ --threads "$THREADS" \ --no-mmap \ --verbose

赋予执行权限：

chmod +x ~/run-openviking.sh

提示：“--no-mmap” 参数是关键。WSL2 的文件系统对内存映射（mmap）的支持不稳定，开启后 OpenViking 在加载大模型时极易触发SIGBUS错误而崩溃。关闭它虽会略微增加内存占用，但换来的是 100% 的稳定性。“--verbose” 则确保所有日志输出到终端，便于实时监控。

3.3 服务守护与健康检查：让 OpenViking 真正“永不掉线”

手动运行./run-openviking.sh只能临时测试。生产环境需要它作为后台服务持续运行，并在崩溃时自动重启。

利用 systemd（我们已在 2.1 节启用）创建服务单元文件：

sudo nano /etc/systemd/system/openviking.service

写入以下内容：

[Unit] Description=OpenViking Server After=network.target [Service] Type=simple User=devuser # 替换为你自己的用户名 WorkingDirectory=/home/devuser ExecStart=/home/devuser/run-openviking.sh Restart=always RestartSec=10 StandardOutput=journal StandardError=journal SyslogIdentifier=openviking [Install] WantedBy=multi-user.target

保存后，重载 systemd 配置并启用服务：

sudo systemctl daemon-reload sudo systemctl enable openviking.service sudo systemctl start openviking.service

检查服务状态：

sudo systemctl status openviking.service # 应显示 "active (running)" # 查看实时日志 sudo journalctl -u openviking.service -f

日志中若出现Server listening on 0.0.0.0:8080，即表示服务已就绪。此时，在 Windows 浏览器中访问http://localhost:8080/docs，应能看到 OpenViking 的 Swagger API 文档页面——这是整个链路的第一个里程碑。

实操心得：我曾遇到systemctl start后服务立即退出，journalctl日志为空。排查发现是User=字段写错了用户名（少了一个字母）。systemd 对用户名校验极其严格，拼写错误会导致服务无法启动且无提示。建议用id -un命令确认当前用户名后复制粘贴。

4. Hermes 运行时与桌面版部署：打通 Agent 编排与可视化界面

4.1 Hermes Core 运行时：基于 Python 的轻量级 Agent 引擎安装

Hermes 的核心是 Python 编写的 Agent Runtime，它负责加载工具定义、调用 OpenViking API、维护对话状态。它不依赖 Docker，直接在 WSL2 的 Python 环境中运行，因此安装必须精准匹配 Python 版本。

Ubuntu 22.04 自带 Python 3.10，这是 Hermes 的推荐版本（3.11+ 有部分异步库兼容问题）。先创建专用虚拟环境，隔离依赖：

cd ~ python3 -m venv hermes-env source hermes-env/bin/activate

升级 pip 并安装核心依赖：

pip install --upgrade pip pip install wheel

Hermes 的官方 PyPI 包（hermes-agent）目前（2024年中）尚未发布稳定版，因此必须从 GitHub 源码安装。克隆仓库：

git clone https://github.com/hermes-org/hermes.git cd hermes

安装时，必须指定--no-deps并手动安装依赖，因为pydantic和httpx的版本冲突是 Hermes 启动失败的第二大原因：

pip install --no-deps . # 手动安装兼容版本 pip install pydantic==2.6.4 httpx==0.27.0 anyio==4.3.0

验证安装：

hermes --help # 应输出帮助信息

4.2 Hermes Agent 配置：连接 OpenViking 的 5 个关键参数

Hermes Agent 需要知道如何与 OpenViking 通信。其配置文件hermes.yaml是 YAML 格式，位于~/.hermes/config.yaml。手动创建它：

mkdir -p ~/.hermes nano ~/.hermes/config.yaml

写入以下内容（请根据你的实际环境修改）：

# 模型后端配置 backend: type: openviking config: # OpenViking 的地址（必须是 host.docker.internal，不是 localhost！） base_url: "http://host.docker.internal:8080" # 模型名称（必须与 OpenViking 加载的模型名一致，用于路由） model_name: "tinyllama" # 超时设置（OpenViking 响应慢时避免 Hermes 卡死） timeout: 120.0 # 工具配置（示例：一个简单的计算器工具） tools: - name: "calculator" description: "A simple calculator that can add, subtract, multiply, and divide." parameters: operation: "string" a: "number" b: "number" # Agent 配置 agent: # 默认使用的模型（与 backend.config.model_name 一致） model: "tinyllama" # 最大 token 限制（防止 OOM） max_tokens: 2048 # 温度（控制随机性） temperature: 0.7

关键点解析：

• base_url: "http://host.docker.internal:8080"：这是唯一正确的地址。localhost在 Hermes 运行的 Python 进程中指向 WSL2 自身，而 OpenViking 运行在 Docker 容器中，两者网络隔离。host.docker.internal是 Docker Desktop 为 WSL2 提供的特殊 DNS 名称，能正确解析到容器网络。
• model_name: "tinyllama"：这个字符串必须与你在 OpenViking 启动脚本中加载的模型文件名（不含.gguf后缀）完全一致。Hermes 会将其作为请求头X-Model-Name发送给 OpenViking，后者据此选择模型。若不匹配，OpenViking 会返回 404。
• timeout: 120.0：TinyLlama 在 CPU 上生成 100 个 token 可能需要 15-20 秒，过短的超时会导致 Hermes 报HTTPStatusError并中断对话。

注意：Hermes 的memory limit exceeded错误，90% 是因为max_tokens设置过高（如设为 8192），而 WSL2 分配给 Ubuntu 的内存不足。对于 16GB 总内存的 Windows，建议在 WSL2 的.wslconfig中设置内存上限：sudo nano /etc/wsl.conf，添加[wsl2] memory=6GB，然后wsl --shutdown重启。这样既能保证 Hermes 运行，又不会挤占 Windows 系统资源。

4.3 Hermes Desktop：在 Windows 上运行真正的桌面应用界面

Hermes Desktop 是一个 Electron 应用，它提供了一个类似 ChatGPT 的图形界面，底层调用 Hermes Core 的 Python API。它的安装方式与传统桌面软件不同，需要在 WSL2 中启动 Python 服务，再在 Windows 中启动 Electron 前端。

第一步：启动 Hermes Core API 服务

在 WSL2 的hermes-env虚拟环境中，执行：

cd ~/hermes hermes api --host 0.0.0.0 --port 8000

--host 0.0.0.0是关键，它让服务监听所有网络接口，而非仅127.0.0.1。这样，Windows 主机才能访问。

第二步：在 Windows 中下载并运行 Hermes Desktop

访问 Hermes 官方 GitHub Releases 页面（https://github.com/hermes-org/hermes-desktop/releases），下载最新版Hermes-Desktop-Setup-x64.exe。双击安装，接受默认路径。

安装完成后，不要直接双击图标启动！因为默认配置会尝试连接http://localhost:8000，而 WSL2 的localhost与 Windows 的localhost是两个不同的网络空间。

必须手动修改 Hermes Desktop 的配置文件。找到它在 Windows 中的配置目录：

%APPDATA%\Hermes Desktop\config.json

用记事本或 VS Code 打开，将"apiUrl": "http://localhost:8000"修改为：

"apiUrl": "http://localhost:8000"

等等，这看起来没变？不，关键在于 WSL2 的网络配置。我们在 2.1 节中启用了systemd并设置了wsl.conf，这使得 WSL2 的localhost端口能被 Windows 主机直接访问。只要 Hermes Core 服务在 WSL2 中运行，Windows 的localhost:8000就等价于WSL2_IP:8000。

启动 Hermes Desktop，界面左上角应显示 “Connected to Hermes API”。输入一条消息，如 “1+1 等于几？”，点击发送。如果 Hermes Core 终端中出现INFO: 127.0.0.1:xxxxx - "POST /v1/chat/completions HTTP/1.1" 200 OK，且桌面版界面上显示出模型回复，恭喜你，全链路贯通！

实操心得：Hermes Desktop 的窗口标题栏右键“Always on Top”功能，是 Electron 框架调用 Windows APISetWindowPos实现的，与 Ubuntu 无关。它之所以能动态置顶，是因为 Electron 将窗口句柄（HWND）暴露给了 JavaScript 层，前端代码通过remote模块（在新版中已废弃，改用@electron/remote）调用原生方法。这与 Ubuntu 的wmctrl或xdotool完全是两套机制，切勿混淆。

5. 常见问题与排查技巧实录：一份来自真实战场的速查手册

5.1 WSL2 相关问题速查表

5.2 Docker 与 OpenViking 问题速查表