| 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 触发）
