8848AI 工具指南

配置 · 使用 · 排错

命令行Agent · 命名Provider

Hermes Agent 接入 8848API：模型、工具与消息网关

用官方自定义 Provider 接口连接平台，明确密钥引用、协议和模型选择；先跑本地CLI，再按需配置工具审批与消息网关，不让自动化在未知费用和权限下运行。

从这里开始返回文档首页

更新：2026-10-15 · 菜单随客户端版本变化，以实际版本为准。模型权限、协议和价格以当前账户可用服务为准。

1. 先确认模型与权限边界

先登录控制台，在「令牌管理」创建单独用于此工具的令牌。检查有效期、额度、允许模型和访问限制；令牌不是网站登录密码，也不是厂商官方账号。

模型 ID：从当前账户可用列表复制完整名称，不用中文显示名或凭印象填写版本。列表可见不等于该模型支持每一种协议和工具功能。
预算：首次选一个已授权的模型，先进行一轮短对话。Agent 可能一项任务连续调用多轮；工具、附件、长历史和自动重试都会增加用量。
保护密钥：不要粘贴到聊天、截图、工单正文、公开项目或分享链接。日志和配置备份也按敏感文件保管。
已有配置：先用客户端自带导出/备份，或私下保存原配置，再合并新增条目；不要用教程整份覆盖已有服务商、MCP、项目或认证设置。

本教程使用Chat Completions自定义端点。Agent还要求模型能正确进行工具调用，并满足当前Hermes文档的上下文要求（至少64,000 tokens）；不是任何能回一句话的模型都适合。

工具执行在你运行Hermes的本机或已配置后端，不在8848API替你隔离的环境。先用测试目录，初期不接消息平台或无人值守任务。

2. 安装与本地检查

Linux / macOS / WSL2可按官方快速开始使用安装器：

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

脚本会下载并执行安装，请先核官方来源；Windows或桌面安装方式以官方当期说明为准，不复制未经核实的PowerShell脚本地址。安装后重新打开该环境的终端：

hermes --help

安装成功与模型接通是不同步骤。不要同时在Windows和WSL写两套配置却只检查其中一套。

3. 选择向导，或使用下节显式配置

会产生真实调用：以下发消息、检查模型连接或执行 Agent 任务可能计费；先核预算，不反复点击检测、不批量试模型。只查看版本、静态配置和本地状态不等于模型已经可用。

hermes model

按当前版本选择Custom endpoint / 自定义提供商，而非官方账号登录。
Base URL为 https://api.884819.xyz/v1，模型ID复制当前账户可用且支持工具的完整名称。
密钥使用自己的平台令牌；若向导询问协议，选择Chat Completions，与下节配置保持一致。
保存后检查选中的默认Provider与模型；探测/连接检测可能真正发请求，先核费用。

向导与手工方式二选一作为主要维护来源，避免反复互相覆盖。菜单变动时按官方提供商文档核对，不按旧截图硬找按钮。

4. 明确的命名Provider配置

当前官方文档采用 providers命名结构。先备份，再将以下片段合并进 ~/.hermes/config.yaml；不要复制为第二个重复的model或providers根节点：

providers:
  api8848:
    api: https://api.884819.xyz/v1
    key_env: API8848_KEY
    transport: chat_completions

model:
  provider: custom:api8848
  default: REPLACE_WITH_AVAILABLE_MODEL_ID

approvals:
  mode: manual
  cron_mode: deny
  single_query_mode: deny
  unattended_mode: deny

将模型占位符替换成真实授权ID。key_env是变量名；transport明确选择chat_completions。不要沿用旧文档中未经证实的 api_key: ${API8848_KEY}，也不要把新版providers和旧版custom_providers结构混在一起。

在受保护的 ~/.hermes/.env中用本地编辑器写入下面变量（替换占位值），不要把真Key贴进命令或分享配置：

API8848_KEY=REPLACE_WITH_YOUR_PLATFORM_TOKEN

chmod 600 ~/.hermes/.env

权限命令适用于POSIX环境；Windows应使用当前用户专属文件权限。后台服务是否加载了变量，要在其实际运行环境核查，不以另一个终端的变量存在作证明。

5. 工具权限：manual不是沙箱

上述 approvals.mode: manual要求对被识别为危险的命令人工审批，不代表所有命令逐条确认，也不是文件系统或网络沙箱。已有允许规则、YOLO或特定隔离后端会影响审批行为；不要打开YOLO来解决接入报错。

通过官方工具管理入口缩减启用的工具，只保留当前任务必要能力。
无人值守、单次查询或定时任务中的deny设置用于拒绝需要审批的命令，不等于整个任务无法执行或不会调用模型。
外部插件、MCP和定时任务各自可能执行操作；启用前读配置和权限，独立核费用。
需要执行隔离时，按官方说明配置合适的容器等后端。SSH连接到另一台机器不自动构成安全隔离。

6. 先本地对话，再做受控工具任务

hermes

首先发送短请求，明确不要调用工具，核默认Provider、模型和平台记录。
再在测试目录请求一项只读任务，观察工具调用、审批和返回是否一致；不要把完整敏感目录当测试材料。
如需诊断，可运行 hermes doctor查看问题，提交日志前去掉密钥和私人内容。
如果文字正常但工具循环、视觉或长上下文失败，按模型/渠道能力逐项排查，不凭聊天成功认定Agent全功能可用。

模型配置用 hermes model维护；会话内模型切换能力随版本变化，不能拿一个旧slash命令代替完整Provider配置。

7. 消息网关后接，不是CLI必选项

仅在本地接入已确认后，再按需要添加消息平台：

hermes gateway setup

完成平台凭据与允许用户/配对限制后，普通受支持服务环境可按官方说明安装、启动并检查：

hermes gateway install

hermes gateway start

hermes gateway status

WSL等没有相同服务管理环境时，按官方说明使用前台 hermes gateway run；不要同时启动多套网关。服务running只证明进程状态，不证明消息发送、模型调用或每个通道都成功。

消息机器人可能被他人触发连续调用，必须限制允许用户/群组；不要全局放开访问，也不要将网关或终端能力直接暴露公网。

8. 排错、备份与恢复

401 / 变量未加载

核key_env拼写、.env位置、运行用户和后台环境。不要输出完整.env；改Key后按当前服务管理方式重新加载，并先保存原配置。

404或模型不存在

核/v1、chat_completions协议与完整模型ID。Provider名称必须与custom:api8848一致，不混用历史schema。

429 / 超时 / 循环重试

中止自动化新增调用，检查额度、限流和已发生用量；一轮任务可能多次调用，不能因未完成就假定未扣费。

备份能否直接分享？

不能。hermes backup及quick备份都可能包含.env、认证与会话，quick不代表脱敏。加密私下保存；恢复前停止相关网关、保存当前数据，核归档可信，不默认加force覆盖。

官方资料与核验边界

本文整理安装与配置方法，不代表所有客户端版本、模型、工具调用或远程功能均已实测。本次文档更新未发起付费模型请求；文中的模型验证、首次对话和自动化运行可能计费，请确认模型与预算后自行执行。