Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions website/docs/getting-started/learning-path.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ First-time users almost always want `hermes setup --portal` — one OAuth covers
|---|---|---|---|
| **Beginner** | Get up and running, have basic conversations, use built-in tools | [Installation](/getting-started/installation) → [Quickstart](/getting-started/quickstart) → [CLI Usage](/user-guide/cli) → [Configuration](/user-guide/configuration) | ~1 hour |
| **Intermediate** | Set up messaging bots, use advanced features like memory, cron jobs, and skills | [Sessions](/user-guide/sessions) → [Messaging](/user-guide/messaging) → [Tools](/user-guide/features/tools) → [Skills](/user-guide/features/skills) → [Memory](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | ~2–3 hours |
| **Advanced** | Build custom tools, create skills, train models with RL, contribute to the project | [Architecture](/developer-guide/architecture) → [Adding Tools](/developer-guide/adding-tools) → [Creating Skills](/developer-guide/creating-skills) → [Contributing](/developer-guide/contributing) | ~4–6 hours |
| **Advanced** | Build custom tools, create skills, export training trajectories, contribute to the project | [Architecture](/developer-guide/architecture) → [Adding Tools](/developer-guide/adding-tools) → [Creating Skills](/developer-guide/creating-skills) → [Trajectory Format](/developer-guide/trajectory-format) → [Contributing](/developer-guide/contributing) | ~4–6 hours |

## By Use Case

Expand Down Expand Up @@ -98,18 +98,18 @@ For most custom tool creation, start with plugins. The [Adding Tools](/developer
page is for built-in Hermes core development, not the usual user/custom-tool path.
:::

### "I want to train models"
### "I want to prepare training data"

Use reinforcement learning to fine-tune model behavior with Hermes Agent's RL training pipeline (powered by [Atropos](https://github.com/NousResearch/atropos)).
Export Hermes Agent conversations as trajectory data for fine-tuning or evaluation.

1. [Quickstart](/getting-started/quickstart)
2. [Configuration](/user-guide/configuration)
3. [Atropos RL Environments](https://github.com/NousResearch/atropos) (external)
3. [Trajectory Format](/developer-guide/trajectory-format)
4. [Provider Routing](/user-guide/features/provider-routing)
5. [Architecture](/developer-guide/architecture)

:::tip
RL training works best when you already understand the basics of how Hermes Agent handles conversations and tool calls. Run through the Beginner path first if you're new.
Trajectory data is most useful when you already understand how Hermes Agent handles conversations and tool calls. Run through the Beginner path first if you're new.
:::

### "I want to use it as a Python library"
Expand Down Expand Up @@ -140,6 +140,7 @@ Not sure what's available? Here's a quick directory of major features:
| **Browser** | Web browsing and scraping | [Browser](/user-guide/features/browser) |
| **Hooks** | Event-driven callbacks and middleware | [Hooks](/user-guide/features/hooks) |
| **Batch Processing** | Process multiple inputs in bulk | [Batch Processing](/user-guide/features/batch-processing) |
| **Trajectory Export** | Generate data for fine-tuning or evaluation | [Trajectory Format](/developer-guide/trajectory-format) |
| **Provider Routing** | Route requests across multiple LLM providers | [Provider Routing](/user-guide/features/provider-routing) |

## What to Read Next
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Generate wiki docs + Mermaid diagrams for any codebase.
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `Documentation`, `Mermaid`, `Architecture`, `Diagrams`, `Wiki`, `Code-Analysis` |
| Related skills | [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection), [`github-repo-management`](/docs/user-guide/skills/bundled/github/github-github-repo-management) |
| Related skills | [`codebase-inspection`](/user-guide/skills/bundled/github/github-codebase-inspection), [`github-repo-management`](/user-guide/skills/bundled/github/github-github-repo-management) |

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please retain the /docs/ prefix here. website/docusaurus.config.ts:11 sets baseUrl: '/docs/', and lines 58-60 explicitly identify /docs/user-guide/skills/bundled/x as the deployed route; /user-guide/... would resolve at the site root.


## Reference: full SKILL.md

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ description: "如何为 Hermes Agent 做贡献 — 开发环境配置、代码
- 构建新的 skill?从 [创建 Skill](./creating-skills.md) 开始
- 构建新的推理提供商?从 [添加提供商](./adding-providers.md) 开始

## 开发环境配置
## 开发环境配置 {#development-setup}

### 前置要求

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,7 @@ required_environment_variables:

旧版 `prerequisites.env_vars` 作为向后兼容的别名仍受支持。

### Config 配置项(config.yaml)
### Config 配置项(config.yaml) {#config-settings-configyaml}

Skill 可声明非密钥配置项,这些配置项存储在 `config.yaml` 的 `skills.config` 命名空间下。与环境变量(存储密钥)不同,config 配置项用于路径、偏好设置及其他非敏感值。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@ mgr.on_session_end([])
mgr.shutdown_all()
```

## 添加 CLI 命令
## 添加 CLI 命令 {#adding-cli-commands}

Memory provider 插件可以注册自己的 CLI 子命令树(例如 `hermes my-provider status`、`hermes my-provider config`)。这套系统基于约定发现,无需修改核心文件。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ description: "在 Linux、macOS、WSL2、原生 Windows 或通过 Termux 在 And
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

### Windows(原生,PowerShell)
### Windows(原生,PowerShell)— 早期 Beta {#windows-native-powershell--early-beta}

原生 Windows 无需 WSL 即可运行 Hermes——CLI、gateway、TUI 和工具均可原生运行。(原生安装与 WSL2 安装可干净共存;唯一仅限 WSL2 的功能见下方功能说明。)遇到 bug 请[提交 issue](https://github.com/NousResearch/hermes-agent/issues)。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务
- **有明确目标?** 跳至[按使用场景](#by-use-case),找到匹配的场景。
- **随便浏览?** 查看[主要功能](#key-features-at-a-glance)表格,快速了解 Hermes Agent 的全部能力。

## 按经验水平
## 按经验水平 {#by-experience-level}

| 水平 | 目标 | 推荐阅读 | 预计时间 |
|---|---|---|---|
| **初级** | 快速上手,进行基本对话,使用内置工具 | [安装](/getting-started/installation) → [快速入门](/getting-started/quickstart) → [CLI 用法](/user-guide/cli) → [配置](/user-guide/configuration) | 约 1 小时 |
| **中级** | 搭建消息机器人,使用记忆、cron 任务、技能等高级功能 | [会话](/user-guide/sessions) → [消息](/user-guide/messaging) → [工具](/user-guide/features/tools) → [技能](/user-guide/features/skills) → [记忆](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | 约 2–3 小时 |
| **高级** | 构建自定义工具、创建技能、使用强化学习训练模型、参与项目贡献 | [架构](/developer-guide/architecture) → [添加工具](/developer-guide/adding-tools) → [创建技能](/developer-guide/creating-skills) → [强化学习训练](/user-guide/features/rl-training) → [贡献指南](/developer-guide/contributing) | 约 4–6 小时 |
| **高级** | 构建自定义工具、创建技能、导出训练轨迹、参与项目贡献 | [架构](/developer-guide/architecture) → [添加工具](/developer-guide/adding-tools) → [创建技能](/developer-guide/creating-skills) → [轨迹格式](/developer-guide/trajectory-format) → [贡献指南](/developer-guide/contributing) | 约 4–6 小时 |

## 按使用场景
## 按使用场景 {#by-use-case}

选择与您目标匹配的场景,每个场景均按推荐顺序链接到相关文档。

Expand Down Expand Up @@ -93,18 +93,18 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
对于大多数自定义工具的创建,建议从插件开始。[添加工具](/developer-guide/adding-tools)页面面向 Hermes 核心内置开发,而非常规用户/自定义工具路径。
:::

### "我想训练模型"
### "我想准备训练数据"

使用强化学习(RL)通过 Hermes Agent 内置的 RL 训练流水线对模型行为进行微调。
将 Hermes Agent 对话导出为轨迹数据,用于微调或评估。

1. [快速入门](/getting-started/quickstart)
2. [配置](/user-guide/configuration)
3. [强化学习训练](/user-guide/features/rl-training)
3. [轨迹格式](/developer-guide/trajectory-format)
4. [Provider 路由](/user-guide/features/provider-routing)
5. [架构](/developer-guide/architecture)

:::tip
强化学习训练在您已了解 Hermes Agent 如何处理对话和工具调用的基础上效果最佳。如果您是新手,请先完成初级路径。
当您已了解 Hermes Agent 如何处理对话和工具调用时,轨迹数据最有用。如果您是新手,请先完成初级路径。
:::

### "我想将其作为 Python 库使用"
Expand All @@ -118,7 +118,7 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
5. [工具](/user-guide/features/tools)
6. [会话](/user-guide/sessions)

## 主要功能一览
## 主要功能一览 {#key-features-at-a-glance}

不确定有哪些功能?以下是主要功能的快速目录:

Expand All @@ -135,7 +135,7 @@ Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检
| **浏览器** | 网页浏览与抓取 | [浏览器](/user-guide/features/browser) |
| **Hooks** | 事件驱动的回调与中间件 | [Hooks](/user-guide/features/hooks) |
| **批处理** | 批量处理多个输入 | [批处理](/user-guide/features/batch-processing) |
| **强化学习训练** | 使用强化学习微调模型 | [强化学习训练](/user-guide/features/rl-training) |
| **轨迹导出** | 生成用于微调或评估的数据 | [轨迹格式](/developer-guide/trajectory-format) |
| **Provider 路由** | 在多个 LLM provider 之间路由请求 | [Provider 路由](/user-guide/features/provider-routing) |

## 下一步阅读
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -331,7 +331,7 @@ Nix 用户最常见自定义需求的快速参考:

---

## 密钥管理
## 密钥管理 {#secrets-management}

:::danger 切勿将 API 密钥放入 `settings` 或 `environment`
Nix 表达式中的值会进入 `/nix/store`,该目录是全局可读的。请始终使用带有密钥管理器的 `environmentFiles`。
Expand Down Expand Up @@ -415,7 +415,7 @@ Agent 身份文件是独立的:Hermes 从 `$HERMES_HOME/SOUL.md` 加载其主

---

## MCP 服务器
## MCP 服务器 {#mcp-servers}

`mcpServers` 选项以声明式方式配置 [MCP(Model Context Protocol,模型上下文协议)](https://modelcontextprotocol.io)服务器。每个服务器使用 **stdio**(本地命令)或 **HTTP**(远程 URL)传输方式。

Expand Down Expand Up @@ -601,7 +601,7 @@ Nix 构建的二进制文件能在 Ubuntu 容器内运行,是因为 `/nix/stor

---

## 插件
## 插件 {#plugins}

NixOS 模块支持声明式插件安装——无需命令式的 `hermes plugins install`。

Expand Down Expand Up @@ -878,7 +878,7 @@ nix build .#checks.x86_64-linux.config-roundtrip # 合并脚本保留用户
└── (Agent 创建的文件)
```

### 容器模式
### 容器模式 {#container-mode}

相同的布局,挂载到容器中:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ Hermes 在 `config.yaml` 中只管理一个 Entra 专属配置项:

Entra 模式下不会将任何密钥写入 `~/.hermes/.env`——`azure-identity` 在进程内缓存令牌(在可用时也会使用操作系统密钥链 / `~/.IdentityService`)。

### 凭据解析顺序
### 凭据解析顺序 {#credential-resolution-order}

`azure-identity` 的 `DefaultAzureCredential` 在每次令牌请求时按以下链路逐一尝试,在第一个返回令牌的凭据处停止:

Expand Down Expand Up @@ -169,7 +169,7 @@ hermes # 使用你的 az login 令牌
**CI 中的服务主体:**
- 在 runner 环境中设置 `AZURE_TENANT_ID`、`AZURE_CLIENT_ID`、`AZURE_CLIENT_SECRET`。

#### 主权云(政府云、中国云)
#### 主权云(政府云、中国云) {#sovereign-clouds-government-china}

导出 `AZURE_AUTHORITY_HOST`(例如 Azure Government 使用 `https://login.microsoftonline.us`,Azure China 使用 `https://login.partner.microsoftonline.cn`)。`azure-identity` 会直接读取该变量。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -375,7 +375,7 @@ with open(_DATA_FILE) as f:
_DATA = yaml.safe_load(f)
```

### 捆绑技能
### 捆绑技能 {#bundle-skills}

插件可以随附技能文件,代理通过 `skill_view("plugin:skill")` 加载。在 `__init__.py` 中注册:

Expand Down Expand Up @@ -418,7 +418,7 @@ skill_view("my-workflow") # → 内置版本(不受影响)
旧的 `shutil.copy2` 模式(将技能复制到 `~/.hermes/skills/`)仍然有效,但存在与内置技能名称冲突的风险。新插件请优先使用 `ctx.register_skill()`。
:::

### 根据环境变量决定是否启用
### 根据环境变量决定是否启用 {#gate-on-environment-variables}

如果你的插件需要 API 密钥:

Expand Down Expand Up @@ -452,7 +452,7 @@ requires_env:

两种格式可在同一列表中混用。已设置的变量会被静默跳过。

### 懒加载可选 Python 依赖
### 懒加载可选 Python 依赖 {#lazy-install-optional-python-dependencies}

如果你的插件封装了一个并非所有用户都会安装的 SDK(供应商 SDK、重型 ML 库、平台特定包),不要在模块顶部 `import` 它。在工具处理器内部使用 `tools.lazy_deps.ensure(...)` 辅助函数——Hermes 会在首次使用时安装该包,并受用户 `security.allow_lazy_installs` 配置的控制。

Expand Down Expand Up @@ -541,7 +541,7 @@ def register(ctx):

所有回调都应接受 `**kwargs` 以保持向前兼容性。如果钩子回调崩溃,会被记录日志并跳过。其他钩子和代理继续正常运行。

### `pre_llm_call` 上下文注入
### `pre_llm_call` 上下文注入 {#pre_llm_call-context-injection}

这是唯一一个返回值有意义的钩子。当 `pre_llm_call` 回调返回包含 `"context"` 键的字典(或纯字符串)时,Hermes 会将该文本注入**当前轮次的用户消息**中。这是记忆插件、RAG 集成、护栏以及任何需要向模型提供额外上下文的插件所使用的机制。

Expand Down Expand Up @@ -676,7 +676,7 @@ def register(ctx):

**活跃提供商限制:** 记忆插件 CLI 命令仅在其提供商是配置中活跃的 `memory.provider` 时才会出现。如果用户尚未设置你的提供商,你的 CLI 命令不会出现在帮助输出中。

### 注册斜杠命令
### 注册斜杠命令 {#register-slash-commands}

插件可以注册会话内斜杠命令——用户在对话中输入的命令(如 `/lcm status` 或 `/ping`)。这些命令在 CLI 和网关(Telegram、Discord 等)中均可使用。

Expand Down Expand Up @@ -1051,7 +1051,7 @@ tts:

**完整指南:** [TTS 自定义命令提供商](/user-guide/features/tts#custom-command-providers) · [STT](/user-guide/features/tts#voice-message-transcription-stt)。

## 通过 pip 分发
## 通过 pip 分发 {#distribute-via-pip}

如需公开分享插件,在你的 Python 包中添加 entry point:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -220,7 +220,7 @@ hermes model

---

## 超时设置
## 超时设置 {#timeouts}

Hermes 会自动检测本地端点(localhost、局域网 IP)并放宽其流式传输超时限制。大多数情况下无需额外配置。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ Hermes 将使用终端工具、文件操作和你的本地模型——无需任
/model gemma2:9b
```

## 第六步:优化速度
## 第六步:优化速度 {#step-6-optimize-for-speed}

### 增大 Ollama 的上下文窗口

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@ TTS 设置从 OpenClaw 配置的**两个**位置读取,优先级如下:
| 频道绑定 | `archive/bindings.json` | 按平台手动配置 |
| 复杂频道配置 | `archive/channels-deep-config.json` | 手动配置各平台 |

## API 密钥解析
## API 密钥解析 {#api-key-resolution}

启用 `--migrate-secrets` 时,API 密钥按以下优先级从**四个来源**收集:

Expand All @@ -196,7 +196,7 @@ TTS 设置从 OpenClaw 配置的**两个**位置读取,优先级如下:

不在此白名单中的密钥一律不会被复制。

## SecretRef 处理
## SecretRef 处理 {#secretref-handling}

OpenClaw 配置中 token 和 API 密钥的值支持三种格式:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,24 @@ hermes auth add spotify --no-browser
# → 浏览器重定向到 127.0.0.1:43827/callback,隧道转发到远程监听器,登录完成。
```

Hermes 会在 `Waiting for callback on ...` 一行打印实际绑定的端口——从那里复制。Spotify 默认端口为 `43827`。
`56121` 是 xAI OAuth 使用的端口。Spotify 请将其替换为 `43827`。Hermes 会在 `Waiting for callback on ...` 这一行打印它实际绑定的端口——从那里复制。

## 仅限浏览器的远程环境(Cloud Shell / Codespaces / EC2 Instance Connect) {#browser-only-remote-cloud-shell--codespaces--ec2-instance-connect}

如果你没有常规的 SSH 客户端——例如你在 GCP Cloud Shell、GitHub Codespaces、AWS EC2 Instance Connect、Gitpod 或其他基于浏览器的控制台中运行 Hermes——上述 SSH 隧道不可用。请改用 `--manual-paste`:

```bash
hermes auth add xai-oauth --manual-paste
# → Hermes 打印一个授权 URL,在笔记本的浏览器中打开它。
# → 在浏览器中批准。重定向到 127.0.0.1:56121/callback 会加载失败
# ——这是预期行为。
# → 从失败页面的地址栏复制完整 URL。
# → 在终端的 "Callback URL:" 提示处粘贴。
```

同样的标志也适用于集成模型选择器的 `hermes model --manual-paste`。如果不想粘贴完整 URL,也可以只接受裸的 `?code=...&state=...` 查询片段。

Hermes 对两种路径使用**相同的 PKCE verifier、state 和 nonce**,因此上游 OAuth 流程在字节层面完全一致——`--manual-paste` 纯粹是回调跳转的传输方式变更,不会降低安全性。

## 哪些提供商需要此操作

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ hermes teams-pipeline maintain-subscriptions
hermes teams-pipeline maintain-subscriptions --dry-run
```

### 自动化订阅续期(生产环境必须配置)
### 自动化订阅续期(生产环境必须配置) {#automating-subscription-renewal-required-for-production}

**Microsoft Graph 订阅最多 72 小时后过期。** 若无任何续期操作,会议通知将在 3 天后静默停止,流水线看起来像是"故障"。这是所有基于 Graph 的集成中最常见的运维故障模式。

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ hermes cron add "Daily AI news summary" "every day at 9am" \

对于多人共用一台机器的团队场景,每个人有自己的 Portal 账号 → 每个 home 目录保存各自的 `~/.hermes/auth.json` → 用户之间不共享 token。这是正确的边界划分。

## 故障排查
## 故障排查 {#troubleshooting}

### 运行 `hermes setup --portal` 后,`hermes portal info` 显示"not logged in"

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ mcp_servers:

对于敏感系统,这通常是最佳默认设置。

## WSL2:将 WSL 中的 Hermes 桥接到 Windows Chrome
## WSL2:将 WSL 中的 Hermes 桥接到 Windows Chrome {#wsl2-bridge-hermes-in-wsl-to-windows-chrome}

以下是适用场景的实际配置:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ tail -f "${HERMES_HOME:-$HOME/.hermes}/logs/gateway.log"

---

## 使用 ngrok 进行本地测试
## 使用 ngrok 进行本地测试 {#local-testing-with-ngrok}

如果 Hermes 在你的笔记本上运行,使用 [ngrok](https://ngrok.com/) 将其暴露到公网:

Expand Down Expand Up @@ -269,7 +269,7 @@ GitLab 的 payload 字段与 GitHub 不同——例如,MR 标题使用 `{objec

---

## 安全说明
## 安全说明 {#security-notes}

- **永远不要在生产环境中使用 `INSECURE_NO_AUTH`**——它会完全禁用签名验证。仅用于本地开发。
- **定期轮换你的 webhook secret**,并在 GitHub(webhook 设置)和你的 `config.yaml` 中同步更新。
Expand Down
Loading