install-hermes

Hermes Agent 一键安装与配置

操作系统: Linux / macOS / WSL2 / Android(Termux)。不支持原生 Windows。

意图识别与行动映射

当用户表达以下意图时，按对应工作流执行：

---

工作流 1: 全新安装

前提检查

git --version   # 必须可用

执行安装

bash ./scripts/install.sh
source ~/.bashrc   # 或 source ~/.zshrc
hermes doctor      # 验证

安装过程说明：

• 脚本默认最小安装（跳过 daytona/playwright/WhatsApp 等重型组件），安装速度快
• 需要完整功能（浏览器工具、WhatsApp 等）时加 --full 参数
• 脚本默认跳过交互式配置向导，安装完后运行 hermes setup 再配置
• 如需安装时直接配置，加 --with-setup 参数
• CI/自动化场景直接运行即可，不会出现任何交互阻塞
• 安装完成后会自动安装 tokenless 插件（token 用量追踪和响应压缩），无需额外操作

安装参数说明：

首次配置

hermes model       # 选择 Provider 和模型
hermes             # 启动首次对话验证

---

工作流 2: 添加 Provider

用户意图："我要安装 OpenRouter"、"接入 DeepSeek"、"用 Claude"、"配置 Kimi" 等。

Step 1: 确定 Provider 类型

从以下速查表识别用户指定的 Provider：

Step 2: 收集必要信息

向用户询问 Provider 所需的凭证：

• API Key 类型: 绝大多数 Provider 只需要一个 API Key
• OAuth 类型（Nous Portal / Codex / GitHub Copilot / Anthropic / Google Gemini）: 终端会显示扫码或浏览器链接，用户按提示完成授权
• 本地模型（Ollama）: 确认 Ollama 已运行且模型已加载

Step 3: 一键配置

推荐方式 — 交互式向导：

hermes model
# 按提示选择 Provider → 粘贴 API Key / 扫码授权 → 选择模型

脚本方式 — 已知 API Key 时：

hermes config set <ENV_VAR_NAME> <api-key-value>
hermes config set model <provider>/<model-id>

例如配置 DeepSeek：

hermes config set DEEPSEEK_API_KEY sk-xxx
hermes config set model deepseek/deepseek-chat

Step 4: 验证

hermes doctor
hermes          # 启动对话，确认 banner 显示正确模型

模型最低要求: 64K token 上下文窗口。不足 64K 的模型会在启动时被拒绝。 辅助模型: 即使主模型已配置，部分工具（视觉、网页摘要）默认使用 OpenRouter 上的 Gemini Flash。建议同时配置 OPENROUTER_API_KEY 以解锁完整工具能力。

---

工作流 3: 添加消息平台

用户意图："接入钉钉"、"配置飞书 Bot"、"微信机器人"、"Telegram Bot" 等。

Step 1: 确定平台

Step 2: 收集凭证

中国平台凭证收集清单：

Step 3: 一键配置

交互式配置（推荐）：

hermes gateway setup
# 选择平台 → 按提示输入凭证 / 扫码 → 完成

对于中国平台，交互式向导支持扫码自动创建应用（飞书、企微）或扫码授权（钉钉）。

手动配置（已知凭证时）：

编辑 ~/.hermes/.env，写入对应环境变量：

# 钉钉
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret
DINGTALK_ALLOWED_USERS=user-id-1

# 飞书
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_CONNECTION_MODE=websocket
FEISHU_ALLOWED_USERS=ou_xxx

# 企微
WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

Step 4: 启动与验证

hermes gateway          # 启动网关
hermes gateway status   # 检查各平台状态

向 Bot 发送一条测试消息验证连通性。

---

工作流 4: 安装 Hermes Workspace (Web UI)

用户意图："安装可视化界面"、"Web UI"、"Workspace"、"Web 控制台"。

Hermes Workspace 是一个基于 Web 的可视化管理界面，支持聊天、记忆浏览、技能管理、终端操作。

前提

• Node.js 22+（node --version）
• Hermes Agent 已安装且 gateway 可访问

一键安装

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
pnpm install
cp .env.example .env

连接到现有 Hermes

# 编辑 .env
echo 'HERMES_API_URL=http://127.0.0.1:8642' >> .env
echo 'HERMES_DASHBOARD_URL=http://127.0.0.1:9119' >> .env

# 启动
pnpm dev    # http://localhost:3000

Docker 一键启动（含 Agent + Workspace）

git clone https://github.com/outsourc-e/hermes-workspace.git
cd hermes-workspace
cp .env.example .env
# 编辑 .env，至少添加一个 Provider API Key
docker compose up
# 打开 http://localhost:3000

验证

curl http://127.0.0.1:8642/health         # gateway 健康
curl http://127.0.0.1:9119/api/status     # dashboard 状态

---

工作流 5: 从 OpenClaw 迁移

用户意图："从 OpenClaw 迁移"、"导入 OpenClaw 数据"。

自动检测

首次运行 hermes setup 时，若检测到 ~/.openclaw 会自动提示迁移。

手动迁移

hermes claw migrate --dry-run    # 预览
hermes claw migrate              # 执行迁移

迁移内容

SOUL.md、记忆、技能、命令白名单、平台配置、API 密钥、TTS 资源、AGENTS.md。

---

工作流 6: 诊断与修复

当用户说"出问题了"、"不能用"、"报错"时，按此顺序执行：

hermes doctor          # 1. 诊断环境和配置
hermes model           # 2. 重选/修复 Provider
hermes setup           # 3. 完整设置向导
hermes sessions list   # 4. 检查会话
hermes --continue      # 5. 恢复会话
hermes gateway status  # 6. 检查网关

常见问题速查

---

安装踩坑速查

坑 1：Python 依赖安装超时（pip 回溯卡死）

内置脚本：

• 默认改用 uv pip install
• 默认最小安装（不含重型 extras），需要完整功能时加 --full：

  bash install.sh --full
  

坑 2：Python venv 重复安装（已内置优化）

脚本已内置检查：若 venv 存在且 pip check 通过，自动跳过重建和依赖安装，无需手动处理。

npm 默认源超时（已内置优化）

默认最小安装会完全跳过 Node.js 依赖，npm 超时问题在默认模式下不存在。

若使用 --full 安装浏览器工具时遇到 npm 超时：脚本已自动设置 npmmirror 镜像，所有 npm install 均使用 --registry=https://registry.npmmirror.com。

若遇到 ENOTEMPTY 报错（上次安装中断留有残留），清理后重试：

rm -rf ~/.hermes/hermes-agent/node_modules
npm install --registry=https://registry.npmmirror.com --prefix ~/.hermes/hermes-agent

坑 4：Playwright 下载超时（已内置优化）

脚本已设置 PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright，并统一改为 npx --yes playwright install chromium 跳过交互确认。

手动重试：

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
cd ~/.hermes/hermes-agent && npx --yes playwright install chromium

坑 5：WhatsApp Bridge GitHub 依赖卡死（已内置 timeout）

部分依赖直接从 GitHub 拉取，脚本已加 timeout 120。

需要 WhatsApp 时，等 GitHub 可访问后手动安装：

cd ~/.hermes/hermes-agent/scripts/whatsapp-bridge && npm install

坑 6：安装结束弹出交互向导（已默认跳过）

脚本默认 RUN_SETUP=false，全程无交互阻塞。需要向导时显式开启：

bash install.sh --with-setup

坑 7：terminal.backend 报错

config.yaml 默认值 auto 会触发报错 Unknown TERMINAL_ENV 'auto'。

修复（安装后必做）：

hermes config set terminal.backend local

坑 8：通义千问（Alibaba/DashScope）完整配置步骤

Hermes 默认调用国际版端点 dashscope-intl.aliyuncs.com，中国区 Key 会出现 401。且 provider 必须显式设为 alibaba（不能用 custom），API Key 必须写入 .env 而非 config.yaml。

Step 1：在 ~/.hermes/.env 中添加：

DASHSCOPE_API_KEY=sk-xxxxxxxxxxxx
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

Step 2：在 ~/.hermes/config.yaml 中设置：

model:
  provider: "alibaba"
  default: "qwen-plus"  # qwen-max 只有 32K 上下文，不满足 Hermes 64K 最低要求！
                        # qwen-plus / qwen-turbo / qwen-long 均有 131K+ 上下文，可正常使用

Step 3：验证：

hermes doctor   # 应显示 ✓ Alibaba/DashScope
hermes          # 启动对话验证

常见错误：

• 使用 provider: custom 会报 "not a recognised provider"（虽然 doctor 不报错，但行为异常）
• 把 api_key 写在 config.yaml 的 model: 块下无效，必须通过 DASHSCOPE_API_KEY 环境变量
• qwen-max 不可用：上下文窗口仅 32K，低于 Hermes 64K 最低要求，启动时报错
• 推荐使用 qwen-plus（131K）、qwen-turbo（131K）或 qwen-long（10M）

坑 9：钉钉 ALLOWED_USERS 填工号无效

DINGTALK_ALLOWED_USERS 需要的是钉钉系统内的 User ID（格式如 $:LWCP_v1:$xxxx），与员工工号不同。

获取方法：

1. 暂不设置 DINGTALK_ALLOWED_USERS，启动网关
2. 从钉钉给 Bot 发一条消息
3. 在日志中找到：

   WARNING gateway.run: Unauthorized user: $:LWCP_v1:$MJqzUSC2... (姓名) on dingtalk
   

4. 把这个 ID 填入 ~/.hermes/.env：

   DINGTALK_ALLOWED_USERS=$:LWCP_v1:$MJqzUSC2TvsmFU4Pp/Q2osUNJaBYAh1P
   

5. 重启网关：hermes gateway stop && hermes gateway run &

---

配置文件速查

常用 CLI 命令

---

参考文档

• Provider 详细配置（含国产模型 z.ai/GLM、Kimi、DeepSeek、Alibaba Qwen、MiniMax 及国际 Provider）: references/model.md
• 中国消息平台接入（钉钉 Stream Mode、飞书 WebSocket/Webhook、微信 iLink Bot、企微 AI Bot）: references/cn-messaging-platforms.md
• 通用配置参考（终端后端、MCP、技能、语音等）: references/quickstart-reference.md
• 官方文档: https://hermes-agent.nousresearch.com/docs
• GitHub: https://github.com/NousResearch/hermes-agent