{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Actual Setup

在 Hermes 中配置 Actual Computer (actual.inc) 推理。

Skill 元数据

参考：完整 SKILL.md

Actual Computer 配置 Skill

将 actual.inc（Actual Computer）配置为 Hermes 的推理提供商。Actual 会把用户自己的硬件变成一个私有推理集群，并通过两种方式暴露 OpenAI 兼容的 API：一个托管的端到端加密中继 https://api.actual.inc（使用 ac_ 密钥认证），以及一个本地设备端守护进程 http://127.0.0.1:8080（环回地址无需认证）。本 skill 不会替用户安装 Actual 守护进程——设备授权需要真人在浏览器中完成。

使用时机

• 用户想把 actual.inc 添加为推理提供商（云中继或本地）。
• 用户已有 ac_ 密钥，想让 Hermes 经由自己的 Actual 集群路由。
• 用户想通过 Actual 守护进程实现完全本地、设备端的推理。
• 故障排查：Actual 请求报出含义不明的 400 或空流。

前提条件

• Hermes 对 actual 提供商提供一等支持（provider id 为 actual，别名 actual-computer、actualcomputer、aci）。在当前版本的 Hermes 上，不要把 Actual 配置为 custom_providers / providers.actual.* 条目——内置提供商已占用该名称，并自动处理 base-url 规范化、Responses 传输和本地免认证。
• 中继模式：需要一个 Actual 账户，以及从 https://actual.inc/user/keys 获取的 ac_ 推理密钥。
• 本地模式：用户已安装守护进程（curl -fsSL "https://actual.inc/install" | bash），并通过运行一次 actual、在浏览器中打开打印出的 https://actual.inc/device?code=... URL 完成了设备授权。把该 URL 转发给用户并等待——切勿编造邮箱或代其授权。授权码 5 分钟后过期；重新运行 actual 获取新码。

运行方式

中继 / API 模式

1. 把密钥放进 .env（仅放机密——绝不要放进 config.yaml）： 在 ~/.hermes/.env 末尾追加 ACTUAL_API_KEY=ac_...。
2. 用 terminal 校验密钥并发现模型：

   curl -s https://api.actual.inc/v1/models -H "Authorization: Bearer $ACTUAL_API_KEY"
   

3. 选择提供商 + 模型：

   hermes config set model.provider actual
   hermes config set model.default "MODEL_ID_FROM_DISCOVERY"
   

4. 端到端验证：

   hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL_ID
   

本地模式

1. 真人已安装并授权守护进程（见前提条件）。
2. 下载并加载模型（授权后即可脚本化执行）：

   actual models search "qwen2.5 0.5b instruct gguf" --limit 8 --no-prompt
   # 下载必须显式指定量化（否则会报 409 ambiguous_model_download）：
   actual models download "Qwen/Qwen2.5-0.5B-Instruct-GGUF/Q4_K_M"
   actual models list        # 记下已安装名称（与下载 id 不同）
   actual models load "qwen2.5-0.5b-instruct-q4_k_m"   # 按已安装名称加载
   

3. 让 Hermes 指向守护进程。当 ACTUAL_BASE_URL 的主机为环回地址时，内置提供商会自动切换为本地免认证模式——无需密钥：在 ~/.hermes/.env 末尾追加 ACTUAL_BASE_URL=http://127.0.0.1:8080，然后：

   hermes config set model.provider actual
   hermes config set model.default "INSTALLED_MODEL_NAME"
   

4. 验证（缩减工具集——见下方上下文窗口陷阱）：

   hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m INSTALLED_NAME -t file,web
   

快速参考

常见陷阱

1. reasoning_effort 陷阱（一等提供商已处理）。 Actual 的 SGLang/vLLM 后端只接受 none/low/medium/high/max；xhigh/ultra 过去会报出含义不明的 Expecting value: line 1 column 1 (char 0)（包装后的 HTTP 400）。内置提供商在传输层把 xhigh→high、ultra→max 做了钳制。若在旧版 Hermes 上仍因此出现 400，可按模型设置上限：在 config.yaml 中配置 agent.reasoning_overrides.<model>: high。
2. 小型本地模型的上下文窗口溢出。 Hermes 默认工具集约 26k token 的 schema，外加约 9k token 的系统提示词。一个以 32k 上下文加载的模型在第一轮对话前就会溢出，而 llama.cpp 系服务器只会发出一个裸 data: [DONE]——Hermes 会报 Provider returned an empty stream with no finish_reason。这不是 SSE 的 bug。解决办法：限制工具（-t file,web）、用更大的 n_ctx 加载模型，或为完整工具集选择 ≥64k 上下文的模型。上游跟踪：#51448（勿新建 issue，在该 issue 补充证据）。相关但不同的问题：#65631（带 400 的 HTTP-200 SSE）、#56516（仅推理流）。
3. 下载 id 与已安装名称的区别。 actual models download 接受 repo/QUANT，未显式指定量化会报 409；actual models load 接受 actual models list 中显示的已安装名称。
4. 推理型模型返回空内容。 GLM/Qwen 推理变体把思考过程放在单独的 reasoning 字段里，可能把少量 max_tokens 全部消耗在推理上。在判定失败前，先给足 max_tokens。
5. 不要创建名为 actual 的自定义提供商。 较早的配置指南（一等支持之前）写的是 providers.actual.* 配置块。在当前 Hermes 上，内置提供商占用该名称；过时的自定义块会被忽略或产生冲突。删除它们，改用上面的环境变量 + model.provider 流程。

验证

# 中继：
hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL
# 本地（小模型——缩减工具集）：
hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m MODEL -t file,web
# 提供商状态（本地免认证会显示 key_source=local-offline）：
hermes status

其他 OpenAI 兼容客户端（如 OpenCode）的用法，见 references/opencode.md。