OpenHuman 部署记录：安装配置与自定义模型接入

记录 OpenHuman 与 Hermes、Halo 的接入方式，包括安装、Webhook 队列、PAT 权限和自定义模型配置。

这篇记录解决什么问题

  • OpenHuman 本体可以运行，不代表外部系统发来的沟通消息会自动被当前 Codex 会话看到。
  • Hermes 侧收到 202 queued 只说明 relay 已验签并把消息放入本地队列；真正的回复需要队列消费者把消息取出，再通过 openhuman-report 回传。
  • Halo 这边则需要一枚有效的 Personal Access Token，并且最好只给文章、快照、分类、标签、附件等内容维护权限。

推荐部署结构

  • OpenHuman core：作为核心服务运行，建议放在容器里并开启健康检查。
  • Hermes relay：只负责验签、识别 action、落队列、返回 202，不承担长任务。
  • Queue consumer：周期性读取本地队列，生成沟通类回执，并调用 Hermes 的 openhuman-report。
  • Halo API client：通过 Halo Console API 创建草稿、更新正文、发布 snapshot，避免直接写数据库。

安装与基础配置

  • 准备 Docker 或同等容器环境，先让 OpenHuman core 独立跑通健康检查。
  • 把 Hermes webhook URL 和签名 token 写入服务端 .env；只保存变量名和值，不在日志中输出真实密钥。
  • 为 relay 配置 systemd service，让它监听本机端口；公网入口交给反向代理转发。
  • 为 queue consumer 配置 systemd timer，例如每 15 秒消费一次队列，避免 relay 阻塞请求。

Halo 维护权限

  • 在 Halo 后台创建 PAT 后，优先选择内容维护所需权限：文章、快照、分类、标签、附件的查看和管理。
  • 不要把用户、角色、插件、系统设置、迁移备份这类管理权限放进长期维护 PAT。临时需要时单独创建短期 token，用完撤销。
  • 401 通常不是“权限不够”那么简单，也可能是 token 复制不完整、签名不匹配或 issuer/公钥状态不一致。

自定义模型配置

  • 把模型配置拆成 provider、base_url、api_key、model、timeout、context_window、fallback_model 等字段，不要把它们硬编码进业务脚本。
  • 对外暴露稳定别名，例如 openhuman-default；底层模型替换时只改配置，不改调用方。
  • 加一个最小化 model_check：请求一次轻量任务，记录响应状态、延迟和错误摘要，再通过 Hermes 报告。
  • 模型不可用时要明确降级：可以排队等待、切到 fallback，或者只返回“已收到，待人工处理”，不要静默丢消息。

排障笔记

  • relay 返回 202 queued 但 Hermes 没收到 openhuman-report：重点查 queue consumer 是否运行、state 文件是否已标记 processed、webhook 出口是否可达。
  • 报告总是显示“服务器简报”：说明 Hermes 的 openhuman-report 渲染器按默认 server_report 模板展示，需要在 payload 中标明 type=dialogue 和 channel=openhuman-dialogue，并让 Hermes 侧识别这个分支。
  • Halo API 创建失败：先用 Console API 读取现有文章结构，再按 post + content 的 PostRequest 结构提交；发布时使用当前 headSnapshot。

Hermes/OpenHuman .env 示例

HERMES_WEBHOOK_URL=https://example.com/webhooks/openhuman-report
HERMES_WEBHOOK_TOKEN=change-me
OPENHUMAN_RELAY_TOKEN=change-me
OPENHUMAN_MODEL_PROVIDER=openai-compatible
OPENHUMAN_MODEL_BASE_URL=https://api.example.com/v1
OPENHUMAN_MODEL_NAME=openhuman-default

systemd timer 思路

[Timer]
OnBootSec=30s
OnUnitActiveSec=15s
Unit=hermes-openhuman-queue-consumer.service

维护结论

入口打通只是第一步；要做到“有人回复”，必须把 relay、队列消费者、报告路由和 Halo 发布权限都纳入日常检查。长期维护时，最重要的是权限最小化、密钥不落日志、失败可观测、重复执行可幂等。