1. 麒麟 V10 局域网跑 Hermes Agent 到底难在哪麒麟 V10Kylin V10作为国产化服务器/桌面操作系统底层是 Linux 内核Docker 本身能装能跑但真正落地 Hermes Agent 这类需要联网拉镜像、还要在局域网内提供服务的应用时问题会集中爆发在三个地方镜像拉取超时、容器启动参数配错、局域网内其他机器访问不到。我这次的目标很明确——在一台麒麟 V10 机器上用 Docker 把 Hermes Agent 跑起来并且让同一局域网内的其他设备比如同事的 Windows 笔记本、另一台测试机能通过 IP 直接调用这个 Agent 服务。先说清楚 Hermes Agent 是什么、能做什么、适合谁。Hermes Agent 是 NousResearch 推出的一套可本地化运行的智能体框架它把大模型的对话能力、工具调用web 搜索、终端执行、跨会话记忆memory打包成一个可交互的 CLI 与容器化服务。适合的人群很具体需要在国产化内网环境里做 AI 能力验证的运维/开发、想把 Agent 部署在本地数据不出内网的团队、以及像我这样在麒麟系统上折腾落地的人。它不是一个网页版聊天工具而是一个可以挂载配置、持久化记忆、通过终端或 API 调用的服务进程。为什么强调“局域网部署”而不是单机跑一下因为单机跑通只是第一步真正的价值在于让内网其他机器复用这个 Agent。麒麟 V10 常见于政务、金融、能源的内网环境这些环境往往不能随意访问外网Docker Hub 直连基本是超时状态。所以整条链路是先解决镜像加速否则第一步就卡死再解决容器启动的持久化与端口暴露最后解决局域网访问验证。这三步任何一步出问题后面都跑不通。我踩过的坑主要集中在镜像加速器失效和容器端口没映射这两块。很多网上抄来的加速器地址已经挂了写进 daemon.json 后 Docker 重启直接报错起不来另一个坑是容器默认只在容器内监听没做端口映射的话宿主机能进容器但局域网其他机器根本连不上。下面按可复制的顺序一步步来每一步都给完整命令和参数说明。需要提前说明的是本文的模型调用能力通过 TaoToken 这类兼容 OpenAI 接口的服务来提供你只需要一个 Base URL、一个 API Key、一个 Model ID 就能把 Agent 的“大脑”接上。这样做的原因是 Hermes Agent 本身是框架它需要一个后端模型服务来驱动对话和工具调用而 TaoToken 提供了标准的兼容接口配置起来最省事。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 后面配置里会反复用到。2. TaoToken 前置准备拿到 Base URL、Key 和 Model ID在动 Docker 之前先把模型服务的三件套准备好否则容器起来了也没法对话。这三件套是Base URL、API Key、Model ID。很多人卡在“容器跑起来了但一对话就报 401”根因就是 Key 没配对或者 Base URL 写成了网页地址而不是 API 地址。第一步打开 TaoToken 控制台创建 API Key。访问 https://taotoken.net/api-keys 登录后新建一个 Key复制出来保存好。这个 Key 只显示一次丢了就得重建。注意不要把它提交到 Git 仓库或者写进公开的配置文件里内网环境虽然相对安全但好习惯要养成。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这里不要加任何多余路径也不要写成官网首页。很多兼容 OpenAI 的客户端要求 Base URL 以 /v1 结尾具体取决于客户端实现。Hermes Agent 的配置里通常填写到 /api 这一层即可如果它内部会自动拼接 /v1/chat/completions那就填 https://taotoken.net/api 如果报 404再尝试 https://taotoken.net/api/v1 。这一点在后面的 config.yaml 里会具体写。第三步确定 Model ID。你可以在模型对话页面 https://taotoken.net/models 查看当前可用的模型列表选一个适合 Agent 场景的比如带工具调用能力的模型。把 Model ID 原样记下来比如类似 claude-3-5-sonnet 这种格式以控制台实际显示为准。Model ID 写错会直接报 model not found这个错误在容器日志里能看到。把这三样整理成一张对照表后面配置时直接抄配置项值获取位置Base URLhttps://taotoken.net/apiAPI 入口API Keysk-xxxx你自己的API Keys 页面Model ID控制台显示的模型名模型对话页面这里要提醒一个高频错误有人把 Base URL 填成了 https://taotoken.net 官网首页结果请求打到网页上返回 HTML客户端解析 JSON 失败报 “reading choices” 之类的错。记住 API 和官网是两个地址配置里只认 API 地址。如果你后续要做长期编码或 Agent 任务可以考虑 Coding Plan入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用场景。但本文聚焦的是局域网部署跑通先用按量 Key 验证即可。准备好三件套后回到麒麟 V10 机器上开始 Docker 侧的操作。整个流程的顺序是配镜像加速 → 拉镜像 → 写配置 → 启动容器 → 验证局域网访问。下面每一步都尽量给到可直接复制的命令。3. 可复制配置daemon.json 加速与容器启动参数这一节是全文的核心所有配置都给你完整片段路径和原文一致复制即可用。先解决 Docker 镜像加速这是麒麟 V10 内网环境能不能拉下镜像的前提。3.1 配置 Docker 镜像加速 daemon.json麒麟 V10 的 Docker 配置文件路径是 /etc/docker/daemon.json。如果文件不存在就新建存在就先备份。执行sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2/dev/null sudo vi /etc/docker/daemon.json写入以下内容。注意 JSON 格式必须严格多一个逗号都会导致 Docker 起不来{ registry-mirrors: [ https://docker.aityp.com, https://docker.1ms.run, https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.xuanyuan.me, https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com, https://mirror.baidubce.com, https://docker.nju.edu.cn ] }写完后先校验 JSON 合法性再重启 Dockerpython3 -m json.tool /etc/docker/daemon.json sudo systemctl daemon-reload sudo systemctl restart docker sudo systemctl status docker看到 active (running) 才算成功。如果 Docker 起不来八成是 JSON 语法错误用上面那条 python3 命令能直接定位。加速器地址不是越多越好如果某个地址失效Docker 会依次尝试但配置本身不会报错真正会报错的是 JSON 格式。3.2 拉取 Hermes Agent 镜像加速配好后拉取官方镜像docker pull nousresearch/hermes-agent:latest如果这一步还是慢可以先用 docker info 确认加速器已生效docker info | grep -A 10 Registry Mirrors输出的列表里应该能看到你配置的地址。拉取成功后用 docker images 确认镜像存在。3.3 准备持久化目录与配置文件Hermes Agent 需要挂载配置目录保证记忆、日志、配置重启不丢。先建目录mkdir -p ~/.hermes然后创建主配置文件 ~/.hermes/config.yaml。这个文件是 Agent 读取模型服务三件套的地方内容如下把 Key 和 Model ID 换成你自己的model: provider: openai base_url: https://taotoken.net/api api_key: sk-你的实际Key model_id: 你的ModelID max_tokens: 4096 temperature: 0.7 agent: memory_enabled: true tools: web_search: true terminal: true server: host: 0.0.0.0 port: 8080这里有几个关键点。base_url 填 https://taotoken.net/api 如果客户端内部会拼 /v1就保持这样如果报 404改成 https://taotoken.net/api/v1 。server.host 必须是 0.0.0.0不能是 127.0.0.1否则局域网访问不了。port 选 8080后面端口映射要用同一个。3.4 启动容器带端口映射与挂载这是最容易出错的一步。完整启动命令docker run -d \ --name hermes \ --restart unless-stopped \ -p 8080:8080 \ -v ~/.hermes:/app/data \ -e HERMES_API_KEYsk-你的实际Key \ -e HERMES_BASE_URLhttps://taotoken.net/api \ -e HERMES_MODEL_ID你的ModelID \ nousresearch/hermes-agent:latest参数逐个说明--name hermes 是容器名方便管理--restart unless-stopped 保证宿主机重启后容器自动拉起-p 8080:8080 是端口映射左边宿主机、右边容器局域网访问靠它-v ~/.hermes:/app/data 把宿主机配置目录挂进容器持久化生效三个 -e 是环境变量和 config.yaml 里的值保持一致双保险。启动后检查docker ps docker logs -f hermesdocker ps 里看到 hermes 处于 Up 状态日志里没有明显的 error 或 panic就说明容器起来了。如果日志里报 401回去检查 Key报 model not found检查 Model ID报 connection refused检查 Base URL。4. 验证请求局域网访问与成功结果确认容器起来只是第一步真正要验证的是“局域网内其他机器能不能用”。这一节给完整的验证链路。4.1 宿主机本地健康检查先在麒麟 V10 本机确认服务在监听curl -s http://127.0.0.1:8080/health如果返回类似 {status:ok} 就说明服务正常。如果连接被拒绝说明容器内服务没起来或者端口没映射对回去看 docker logs。再确认端口监听状态ss -tlnp | grep 8080应该能看到 0.0.0.0:8080 在 LISTEN。如果是 127.0.0.1:8080说明容器内配置的 host 没改成 0.0.0.0局域网访问不了。4.2 局域网内另一台机器访问先查麒麟 V10 的局域网 IPip addr | grep inet | grep -v 127.0.0.1假设拿到的是 192.168.1.100。然后在同一局域网的另一台机器上执行curl -s http://192.168.1.100:8080/health能返回 ok 就说明局域网通了。如果超时检查麒麟 V10 的防火墙sudo firewall-cmd --list-ports sudo firewall-cmd --add-port8080/tcp --permanent sudo firewall-cmd --reload麒麟 V10 默认可能开着 firewalld8080 没放行的话局域网请求会被拦。这一步很多人忽略导致“本机好好的别人连不上”。4.3 发起一次真实对话请求健康检查通过后用 API 方式发一次对话验证模型服务三件套是否真的通了curl -s http://192.168.1.100:8080/v1/chat/completions \ -H Content-Type: application/json \ -d { model: 你的ModelID, messages: [{role: user, content: 用一句话介绍你自己}] }如果返回的 JSON 里有 choices 字段和正常的 content说明整条链路打通了局域网请求 → 容器 → TaoToken API → 模型返回。如果报 401是 Key 问题报 reading choices 相关错误通常是 Base URL 返回了非 JSON 内容检查是不是写成了官网地址报 model not found检查 Model ID。4.4 终端 CLI 方式验证如果你更习惯用 Hermes 自带的 CLI可以在容器内执行docker exec -it hermes hermes doctor docker exec -it hermes hermes chat -q 介绍一下你自己hermes doctor 会自动诊断环境、权限、配置有问题直接给修复建议这是排查利器。hermes chat -q 是单次查询模式不进入交互界面适合脚本化验证。到这里一个完整的局域网 Hermes Agent 服务就跑通了。局域网内任何机器都可以通过 http://192.168.1.100:8080 调用它数据不出内网模型能力通过 TaoToken 的兼容接口提供。5. 本篇常见错误排查对照部署过程中报错是常态这一节把高频错误和真实报错信息对照起来方便你快速定位。所有错误都来自实际运行不是编造的。5.1 401 Unauthorized报错原文类似{error:{message:Invalid API key,type:invalid_request_error}}。根因是 API Key 不对。检查三处config.yaml 里的 api_key、docker run 的 -e HERMES_API_KEY、以及 Key 本身是否过期或被删。注意 Key 前后不要有空格复制时容易带上换行。如果刚在控制台重建了 Key记得同步更新容器环境变量改完要 docker rm -f hermes 重新 run光重启容器不会刷新环境变量。5.2 local proxy failed / connection refused报错原文类似Post https://taotoken.net/api/v1/chat/completions: dial tcp: connection refused 或 local proxy failed。这类错误通常是网络层问题。先确认麒麟 V10 能访问外网 APIcurl -s -o /dev/null -w %{http_code} https://taotoken.net/api如果返回 000 或超时说明这台机器到 API 的网络不通需要检查内网出口策略。如果返回 200/401/404 之类说明网络通问题在配置。注意不要用任何非正规的网络工具内网环境按规范走出口即可。5.3 reading choices 解析失败报错原文类似json: cannot unmarshal ... 或 error reading choices。根因是 Base URL 返回的不是标准 JSON。最常见的是把 Base URL 写成了 https://taotoken.net 官网首页请求打到网页返回 HTML客户端解析失败。正确写法是 https://taotoken.net/api 。如果客户端要求 /v1就写 https://taotoken.net/api/v1 。改完配置后重启容器。5.4 OAuth / 认证相关报错报错原文类似OAuth token expired 或 authentication failed。如果你用的是需要 OAuth 的客户端比如某些 IDE 插件或 Codex 类工具要确认认证方式选的是 API Key 而不是 OAuth。Hermes Agent 容器场景下统一用 API Key不要混用 OAuth 流程。如果之前配过 OAuth清掉相关缓存再重试。5.5 容器启动即退出docker ps -a 看到 hermes 状态是 Exited。用 docker logs hermes 看最后几行。常见原因config.yaml 的 YAML 缩进错误YAML 对缩进敏感用空格不用 Tab、挂载目录权限不足~/.hermes 属主不对、环境变量缺失导致启动校验失败。修复后 docker rm -f hermes 再重新 run。5.6 局域网访问超时但本机正常本机 curl 127.0.0.1:8080 通局域网 curl 192.168.1.100:8080 超时。两个检查点一是容器内 server.host 是否为 0.0.0.0二是麒麟 V10 防火墙是否放行 8080。前者改 config.yaml 重启容器后者用 firewall-cmd 放行。这两个都排查完基本就通了。5.7 镜像拉取失败报错原文类似net/http: TLS handshake timeout 或 manifest unknown。先确认 daemon.json 里的加速器地址有效用 docker info 看 Registry Mirrors 是否生效。如果所有加速器都失效可以尝试换一组或者确认镜像名是否正确nousresearch/hermes-agent:latest。镜像名写错会报 manifest unknown这个和加速器无关。排查顺序建议先看 docker logs再看 hermes doctor最后对照上面的错误表。大部分问题集中在 Key、Base URL、端口映射、防火墙这四处。6. 继续用起来模型对话、接入文档与 Coding Plan服务跑通之后接下来就是怎么把它用起来。如果你只是想验证模型能力可以直接在模型对话页面测试不同模型的表现入口是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 在这里切换 Model ID找到最适合你 Agent 场景的那个。如果你要把这套服务接入到自己的应用或 IDE 里完整的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各种语言和客户端的配置示例Base URL、Key、Model ID 三件套的填法都写得很清楚。局域网部署的场景下你只需要把文档里的 Base URL 换成麒麟 V10 的局域网 IP 加端口即可。如果你后续要做长期编码任务或者高频 Agent 调用按量 Key 可能不够划算可以看看 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它针对持续调用场景做了优化。对于 Claude Code 这类编码工具接入方式也是同样的三件套文档里有专门章节。最后给一个实用技巧把常用的启动命令写成一个 shell 脚本放在 ~/.hermes/start.sh下次机器重启后直接执行省得重新敲一长串 docker run。脚本里把 Key 用环境变量读取不要硬编码在脚本里。这样既方便又安全。整个部署的核心就是三步——配加速、拉镜像、带映射启动剩下的都是围绕这三步的排障和验证。