Hermes Agent 安装与配置全流程（2026年6月最新版）：Docker 与 Linux 双环境实操

1. 为什么要在 Docker 与 Linux 双环境下部署 Hermes AgentHermes Agent 是一个能自我进化的开源智能体框架它通过 FTS5 全文检索实现跨会话持久记忆能自动学习你的操作习惯并生成可复用的程序化技能。简单说你用得越久它越懂你。它支持 Telegram、Discord、Slack、微信等消息平台作为交互入口也兼容 Kimi、OpenAI、Anthropic 等主流大模型提供商。适合谁适合想在本地跑一个长期陪伴型 Agent 的开发者、想研究智能体记忆机制的技术爱好者以及需要把 Agent 部署到服务器上做自动化任务的运维同学。我这次把 Hermes Agent 在 Docker 和 Linux 两种环境下的安装配置全流程都跑了一遍踩了几个坑也总结了一套能一次跑通的步骤。Docker 方案适合生产环境环境隔离干净不会污染宿主机Linux 原生方案适合调试和开发启动快、日志直观。两种方式我都会给出可复制的配置片段包括 Docker Compose 文件、依赖安装命令、启动自检和日志排查动作。你跟着做基本能在半小时内看到 Hermes Agent 跑起来并响应你的第一条消息。需要提前说明的是Hermes Agent 不支持原生 WindowsWindows 用户请走 WSL2。硬件最低 2 核 2G 就能跑但推荐 4 核 8G 以获得更流畅的交互体验。存储占用很小100MB 左右网络需要稳定联网。前置依赖只有 Git 2.0安装脚本会自动处理 Python 3.11 和 Node.js v22你不用手动装。2. TaoToken 前置准备模型接入与 API Key 获取Hermes Agent 本身不绑定任何模型它需要你提供一个 LLM 服务商。国内用户如果直接调海外模型网络延迟和稳定性都是问题。我实测下来用 TaoToken 做模型接入层比较省心它兼容 OpenAI 和 Anthropic 的接口格式Hermes Agent 配置起来很直接。你需要先拿到两样东西Base URL 和 API Key。Base URL 是https://taotoken.net/apiAPI Key 在控制台创建。具体操作打开 https://taotoken.net/api-keys 登录后创建一个新的 Key复制保存。这个 Key 后面要填到 Hermes Agent 的配置里。模型 ID 方面如果你用 Kimi 系列模型 ID 填kimi-k2或moonshot-v1-128k如果用 Claude 系列填claude-sonnet-4-20250514这类完整 ID。TaoToken 的模型列表在文档里有你可以按需选。我建议先用 Kimi 跑通中文理解好长文本处理强免费额度也够调试用。这里要提醒一句Hermes Agent 的hermes setup向导里会让你选模型提供商。如果你选 OpenAI 兼容模式就填 TaoToken 的 Base URL 和 Key如果选 Anthropic 模式同样填 TaoToken 的地址因为 TaoToken 兼容 Anthropic 的/v1/messages接口。两种模式我都试过都能正常返回。配置前先确认你的环境能访问https://taotoken.net/api。在 Linux 终端执行curl -s -o /dev/null -w %{http_code} https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-your-key-here返回 200 就说明网络和 Key 都没问题。如果返回 401检查 Key 是否复制完整如果超时检查 DNS 和防火墙。这一步做完后面 Hermes Agent 的模型配置就不会卡在连接失败上。另外TaoToken 的 Coding Plan 适合长期编码和 Agent 场景如果你打算让 Hermes Agent 持续跑自动化任务可以了解一下 https://taotoken.net/coding-plan 。模型对话调试可以用 https://taotoken.net/chat 接入文档在 https://taotoken.net/doc 。3. Docker Compose 与 Linux 依赖安装可复制配置这一节是核心我直接给可复制的配置片段。Docker 方案用 Compose 管理Linux 方案用 apt 装依赖。两种方式都经过实测你按顺序执行即可。3.1 Docker Compose 部署 Hermes Agent先装 Docker 和 Compose。Ubuntu/Debian 下sudo apt update sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable --now docker docker --version docker compose version然后创建项目目录和 Compose 文件mkdir -p ~/hermes-docker cd ~/hermes-docker mkdir -p config data新建docker-compose.yml内容如下services: hermes-agent: image: nousresearch/hermes-agent:latest container_name: hermes-agent restart: unless-stopped ports: - 8080:8080 volumes: - ./config:/root/.hermes - ./data:/root/.hermes/data environment: - HERMES_MODEL_PROVIDERopenai - HERMES_BASE_URLhttps://taotoken.net/api - HERMES_API_KEYsk-your-key-here - HERMES_MODEL_IDkimi-k2 - HERMES_LOG_LEVELinfo healthcheck: test: [CMD, curl, -f, http://localhost:8080/health] interval: 30s timeout: 10s retries: 3注意把sk-your-key-here换成你在 TaoToken 控制台创建的真实 Key。HERMES_MODEL_ID按你选的模型填Kimi 填kimi-k2Claude 填claude-sonnet-4-20250514。启动容器docker compose up -d docker compose ps看到hermes-agent状态是Up (healthy)就说明启动成功。如果状态是Restarting用docker compose logs --tail100 hermes-agent看日志。3.2 Linux 原生安装与依赖配置Linux 原生方案适合调试。先装 Git 和基础工具sudo apt update sudo apt install -y git curl build-essential python3.11 python3.11-venv git --version配置国内镜像加速避免拉取依赖超时git config --global url.https://mirror.ghproxy.com/https://github.com.insteadOf https://github.com pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ pip config set install.trusted-host mirrors.aliyun.com npm config set registry https://mirrors.cloud.tencent.com/npm/ --global然后执行一键安装脚本curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash source ~/.bashrc安装完成后验证hermes --version which hermes如果hermes --version报 command not found执行source ~/.bashrc或重开终端。安装脚本会把hermes放到~/.local/bin确保这个路径在$PATH里。3.3 配置模型接入 TaoToken无论 Docker 还是 Linux 方案模型配置都可以用hermes setup向导也可以直接写配置文件。我推荐直接写配置更可控。Linux 原生方案下配置文件在~/.hermes/config.toml。创建或编辑[model] provider openai base_url https://taotoken.net/api api_key sk-your-key-here model_id kimi-k2 max_tokens 8192 temperature 0.7 [memory] backend sqlite path ~/.hermes/data/memory.db [tools] enabled [web, terminal, file]Docker 方案下这个文件对应~/hermes-docker/config/config.toml因为 Compose 把./config挂载到了/root/.hermes。你可以直接在宿主机编辑容器内会同步。配置写完后Linux 方案执行hermes config check验证格式Docker 方案执行docker compose restart hermes-agent让配置生效。4. 启动自检、日志排查与版本确认配置写完不代表能跑通这一节给验证动作。我按 Docker 和 Linux 分开说你对照自己的环境操作。4.1 Docker 环境验证启动后先看容器状态docker compose ps期望输出里STATUS是Up (healthy)。如果显示Up (health: starting)等 30 秒再查。如果显示Restarting直接看日志docker compose logs --tail200 hermes-agent常见日志关键词和含义日志关键词含义处理local proxy failed容器内无法访问外部 API检查宿主机 DNS加dns: 8.8.8.8到 compose401 UnauthorizedAPI Key 错误重新复制 TaoToken Keyreading choices模型返回格式异常检查 model_id 是否正确connection refused端口冲突改ports映射如8081:8080健康检查通过后发一条测试请求curl -s http://localhost:8080/health curl -s http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model:kimi-k2,messages:[{role:user,content:你好}]}第二条命令如果返回包含choices的 JSON说明模型接入成功。如果返回{error:...}按错误信息排查。4.2 Linux 原生环境验证Linux 方案下先确认版本hermes --version然后前台启动看输出hermes start正常启动会打印类似Hermes Agent v0.8.0 started Model: kimi-k2 via https://taotoken.net/api Memory backend: sqlite Tools: web, terminal, file What can I do for you today? 看到提示符就说明启动成功。输入你好测试能收到回复就通了。按CtrlC退出前台改用后台启动nohup hermes start ~/.hermes/hermes.log 21 tail -f ~/.hermes/hermes.log日志里如果出现OAuth token expired说明你用了需要 OAuth 的模型提供商换成 TaoToken 的 API Key 模式即可。如果出现reading choices错误检查config.toml里model_id是否和 TaoToken 文档一致。4.3 版本确认与更新确认当前版本hermes --versionDocker 方案确认镜像版本docker inspect nousresearch/hermes-agent:latest | grep -i version更新到最新版hermes updateDocker 方案更新docker compose pull docker compose up -d更新后重新执行hermes config check和健康检查确保配置没被覆盖。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节把我遇到的报错和解决方案列出来你对照日志排查。5.1 401 Unauthorized报错原文Error: 401 Unauthorized - invalid api key根因API Key 错误或未生效。检查三处config.toml里的api_key、环境变量HERMES_API_KEY、TaoToken 控制台里 Key 的状态。注意 Key 前后不要有空格复制时容易带上换行。Docker 方案下改完docker-compose.yml要docker compose up -d重建容器光restart不会重新读环境变量。5.2 local proxy failed报错原文Error: local proxy failed: dial tcp: lookup taotoken.net: no such host根因容器内 DNS 解析失败。Docker 默认用宿主机 DNS但某些环境会继承错误的resolv.conf。解决方案是在docker-compose.yml里加 DNSservices: hermes-agent: dns: - 8.8.8.8 - 1.1.1.1然后docker compose up -d重建。Linux 原生方案下检查/etc/resolv.conf确保有可用的 nameserver。5.3 reading choices 错误报错原文Error: reading choices: unexpected end of JSON input根因模型返回的 JSON 不完整或格式不对。常见原因是model_id填错或者max_tokens设得太大导致截断。检查config.toml里model_id是否和 TaoToken 文档一致把max_tokens降到 4096 试试。如果用的是 Claude 模型确认 provider 设成anthropic而不是openai。5.4 OAuth token expired报错原文Error: OAuth token expired, please re-authenticate根因你选了需要 OAuth 的模型提供商但没走完认证流程。解决方案是改用 API Key 模式。在config.toml里把provider改成openaibase_url填https://taotoken.net/apiapi_key填 TaoToken 的 Key。这样就不依赖 OAuth 了。5.5 命令未找到报错原文hermes: command not found根因~/.local/bin不在$PATH。执行echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrcDocker 方案不会遇到这个问题因为容器内路径已经配好。5.6 端口冲突报错原文Error: listen tcp :8080: bind: address already in use根因8080 被占用。改docker-compose.yml的端口映射ports: - 8081:8080然后docker compose up -d。Linux 原生方案下hermes start --port 8081指定其他端口。6. 接入文档与模型调试入口跑通之后你可能想深入配置记忆后端、工具权限、消息平台接入。这些在官方文档里都有但国内访问可能慢。我建议先把模型接入层稳定下来再逐步加功能。TaoToken 的接入文档在 https://taotoken.net/doc 里面有 OpenAI 兼容接口和 Anthropic 兼容接口的详细说明包括请求格式、参数、错误码。如果你要调模型参数比如 temperature、top_p、max_tokens文档里有对照表。模型对话调试可以用 https://taotoken.net/chat 直接在网页里试模型效果确认模型 ID 和返回格式。这样在配 Hermes Agent 之前就能验证 Key 和模型是否可用。API Key 管理在 https://taotoken.net/api-keys 你可以创建多个 Key 分别给不同环境用方便排查问题时隔离变量。如果你打算让 Hermes Agent 长期跑编码或自动化任务Coding Plan 在 https://taotoken.net/coding-plan 适合高频调用场景。最后给一个实用技巧Hermes Agent 的配置文件支持环境变量覆盖。你可以在config.toml里写api_key ${HERMES_API_KEY}然后通过环境变量注入 Key。这样 Docker 和 Linux 方案可以共用一份配置文件切换环境时只改环境变量不用改文件。Docker Compose 里已经用了这个方式Linux 方案下执行export HERMES_API_KEYsk-your-key-here再启动hermes start即可。跑通之后建议先跑hermes setup把工具权限配好新手先开web、terminal、file三个基础工具browser按需开。然后输入/skill list看看内置技能用/skill run skill-name试跑一个。记忆数据存在~/.hermes/data/memory.db定期备份这个文件就行。