auth-json-extend

name	auth-json-extend
category	devops
description	Copy the default agent's auth.json to profile agent space, extending the expiry time to avoid refresh_token conflicts.
version	4

auth-json-extend

适用场景

多 agent 共享同一个 Nous Portal OAuth 账号时，refresh_token 是一次性的。多个 agent 同时尝试 refresh 会导致 "Refresh token reuse detected" 错误。本方案通过复制 auth.json + 延长过期时间 1 年，避免 refresh 冲突。

原理

• auth.json 包含两层 token：OAuth access_token（15分钟）和 agent API key（~24小时）
• 只有 agent key 过期时才会触发 refresh 流程
• 延长 agent_key_expires_at 推迟 refresh 触发时间，一年内无需 refresh
• 主 agent 正常 refresh 后，定时脚本自动把新 token 推到所有 profile
• 同步触发条件：文件缺失/损坏 + token 过期 + token 和主不一致

架构

1 个脚本 + 1 个 systemd timer（以 root system service 为例）：

hermes-auth-sync.timer → auth_sync.py（每 5 分钟）
  1. 检查主 auth.json（存在？JSON合法？结构完整？token非空？未过期？）
     无效 → 报错退出
  2. 自动发现 ~/.hermes/profiles/ 下所有 agent
  3. 逐个检查 profile：
     文件缺失/损坏/token过期 → 需要同步
     agent_key/refresh_token 和主不一样 → 需要同步
  4. 需要同步的 → 复制主 auth.json，过期时间+1年
  5. 无变化时静默，有变化时写日志

文件结构

Skill 目录（自包含，用于部署）：
~/.hermes/skills/auth-json-extend/
├── SKILL.md
├── assets/
│   └── systemd/
│       ├── hermes-auth-sync.service
│       └── hermes-auth-sync.timer
└── scripts/
    └── auth_sync.py

部署后（以 root system service 为例）：
~/.hermes/scripts/auth_sync.py
~/.hermes/logs/auth-sync.log   （自动 rotation，1MB × 3份）
/etc/systemd/system/hermes-auth-sync.{service,timer}

本技能附带的 systemd 文件以 root 用户 system service 为例。 如果需要安装 user service（非 root 部署），请参考下面的说明自行修改路径和安装方式。

修改的字段

字段	说明
providers.nous.expires_at	OAuth token 过期
providers.nous.agent_key_expires_at	Agent key 过期
credential_pool.nous[].expires_at	池中 OAuth 过期
credential_pool.nous[].agent_key_expires_at	池中 Agent key 过期

注意事项

• 主 agent gateway 必须保持运行 — 它是唯一能正常 refresh token 的入口
• 日志自动 rotation（1MB × 3 份），不会无限增长
• 新增 agent 只需在 ~/.hermes/profiles/ 下创建目录，自动发现
• 最坏情况有 5 分钟的 token 不一致窗口（主 refresh 后到下次 timer 触发）