Hermes Agent

Hermes Agent 是一款运行在终端中的智能体，可在用户授权后读写文件、执行命令并调用工具。

本教程介绍如何使用 Hermes Agent 自带的 Custom Endpoint，无需借助其他配置工具，接入 AGTCloud 的 Chat Completions 接口并完成基础对话验证。文件操作、网页搜索、MCP、Skills 等扩展能力不在本教程的验证范围内。

准备工作

开始前，请确认你已经：

准备好 Hermes Agent 支持的操作系统和终端环境；
注册并登录 AGTCloud；
在 API Keys 页面创建 AGTCloud API Key；
从模型广场复制当前 API Key 可见且支持 Chat Completions 的模型 ID；
准备一个不包含敏感代码和生产凭证的测试目录。

安装 Hermes Agent

选择与你的运行环境对应的官方安装方式。macOS 首版支持 Apple Silicon；Intel Mac、Homebrew 和 PyPI 安装不属于当前官方支持范围。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后，重新打开终端并检查版本与运行环境：

hermes version
hermes doctor

hermes doctor 会检查安装、配置和常见运行环境问题。如果终端提示找不到 hermes，请先重新打开终端，再确认安装目录已经加入 PATH。其他平台限制请查看 Hermes Agent 官方平台支持说明。

配置 AGTCloud

Hermes Agent 提供模型服务商配置向导。请在普通终端中运行以下命令，不要在已经打开的 Hermes 对话内执行：

hermes model

选择 Custom Endpoint

在 Provider 列表中选择 Custom endpoint。不同版本的完整名称可能显示为 Custom endpoint (self-hosted / VLLM / etc.)。

填写 AGTCloud 连接信息

按照当前版本的向导依次填写：

Hermes Agent 字段	填写内容
`Provider Name`（如有）	`AGTCloud`
`API Base URL`	`https://api.agtcloud.cn/v1`
`API Key`	`your-api-key`
`API / Wire Mode`	`Chat Completions` 或 `chat_completions`
`Model`	`MODEL_ID`
`Context Length`	首次配置建议留空，由客户端尝试自动识别

将 your-api-key 替换为 AGTCloud API Key，并将 MODEL_ID 替换为当前 API Key 可见的模型 ID。

保存配置

确认向导摘要后保存。普通设置会写入 ~/.hermes/config.yaml，API Key 等敏感值由 Hermes Agent 保存到 ~/.hermes/.env。

Base URL 必须包含 /v1

请直接使用 https://api.agtcloud.cn/v1。不要只填写 API Origin，也不要填写完整的 /v1/chat/completions 请求地址或再次追加 /v1。

优先使用官方配置向导

Hermes Agent 的配置字段可能随版本演进。使用 hermes model 可以让当前版本自行写入正确的 Provider 和传输模式，不需要手动编辑 YAML，也不要把真实 API Key 写入共享配置示例。

检查配置

完成向导后，可以使用以下命令检查当前设置：

hermes config
hermes config get model
hermes config check

hermes config 打开或显示当前配置入口；
hermes config get model 检查当前模型设置；
hermes config check 检查配置格式和必要字段。

检查输出时不要复制或分享完整 API Key。如果配置仍指向其他 Provider，请重新运行 hermes model 并完成 Custom Endpoint 设置。

启动并验证连接

进入安全测试目录

cd /path/to/safe/test-project

首次连接不要在包含生产凭证、客户资料或未公开源码的目录中进行。

启动 Hermes Agent

hermes

也可以使用 hermes chat 启动交互式会话。

完成基础对话验证

在输入框中发送：

请只回复：AGTCloud 连接成功。不要调用任何工具。

能够正常收到回复，说明 Base URL、API Key、模型和基础 Chat Completions 连接已经建立。本步会产生正常的 API 用量。

可选验证工具调用

如果所选模型支持工具调用，可以在包含 README.md 的测试目录中发送：

请只读取 README.md，并用三点概括项目用途。不要修改文件，也不要执行其他命令。

保持默认人工审批，先检查 Hermes Agent 准备执行的操作，再决定是否允许。

首次使用不要关闭操作审批

不要使用 --yolo，也不要将危险操作审批设置为关闭。Hermes Agent 可以执行命令和访问文件，首次验证应逐项确认工具请求。

切换模型

需要添加新模型、修改 Endpoint 或更换 API Key 时，请退出当前会话并运行：

hermes model

在已经打开的会话中，可以使用 /model 在已经配置的 Provider 和模型之间切换。/model 不负责创建新的 Custom Endpoint；如果目标模型尚未配置，请先使用终端命令 hermes model。

MODEL_ID 只是占位符。请始终使用模型广场中当前 API Key 可见的完整模型 ID，不要依赖可能随版本变化的固定推荐模型。

常见问题

现象	优先检查	处理方式
找不到 `hermes` 命令	安装结果和 `PATH`	重新打开终端，运行 `hermes version`；仍无结果时重新执行对应系统的官方安装命令
`hermes doctor` 报告异常	Python、系统工具和安装目录	按诊断结果修复当前环境，不要混用多个 Hermes Agent 安装来源
返回 `401`	API Key 内容和令牌状态	重新复制有效 API Key，并确认填写内容没有多余空格
返回 `403`	令牌权限、模型权限和账户状态	在控制台检查 API Key 状态及当前账户的模型可用范围
返回 `404`	Base URL、重复 `/v1` 和模型 ID	使用 `https://api.agtcloud.cn/v1`，不要填写完整 Endpoint，并重新复制完整模型 ID
模型不可用	当前 Key 可见模型和协议支持	选择当前 API Key 可见且支持 Chat Completions 的模型
仍使用其他 Provider	`hermes model` 的当前选择和保存结果	重新运行向导，选择 Custom Endpoint，并通过 `hermes config check` 检查配置
对话正常但工具失败	模型工具调用能力和响应格式	换用支持工具调用的模型；先关闭复杂工具，只验证一个只读操作
上下文长度识别失败	模型元数据和手动填写值	重新运行 `hermes model`；只有掌握模型真实限制时才手动填写上下文长度
扩展工具缺少凭证	辅助工具的独立服务配置	这些能力可能需要额外服务和凭证，不属于 AGTCloud 主对话模型 Key 的配置范围

遇到无法定位的问题时，运行 hermes doctor 和 hermes config check，并记录请求时间、API Base URL、模型 ID、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交完整 API Key。

安全建议

不要把 API Key 写入项目文件、Git 仓库、命令记录、截图、日志或共享配置；
首次使用应在安全测试目录中进行，并逐项检查文件、命令和网络访问请求；
不要通过 --yolo 或配置项关闭危险操作确认；
处理不可信代码时，可以使用 Docker 等隔离环境降低风险，但仍需检查挂载目录和凭证；
API Key 疑似泄露时，立即在控制台禁用或删除，然后创建新 Key。