需在 Agent Space 中更换失效或即将过期的 API Key，确保新 Key 经服务商验证、权限匹配且本地凭证池重载；通过 hermes auth list 查状态，保留旧 Key 记录，新建同 Provider 的 Key 并严格校验格式，用 hermes auth add 添加后执行 hermes reload auth 切换生效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要在 Agent Space 中更换已失效或即将过期的 API Key，避免因密钥失效导致 AI Agent 调用中断、Skills 加载失败或 MCP 服务断连——这不同于普通重置，必须确保新 Key 已通过服务商验证、权限配置匹配且本地凭证池已重新加载。
确认当前 Key 状态并准备新 Key
打开终端，执行 hermes auth list 查看所有已注册凭证。重点关注 status 字段：若某 Key 显示 exhausted，说明它已被自动标记为配额耗尽；若显示 invalid，则大概率是 Key 过期或权限变更导致 401 错误。此时不要删除旧 Key，先保留记录用于比对。
登录对应服务商控制台（如 DeepSeek 官方、硅基流动或智谱 AI），在「API Keys」页面新建一个 Key。注意：新 Key 必须与旧 Key 属于同一 Provider（例如都是 deepseek），否则 Hermes 凭证池无法识别为同源轮换项。
复制新 Key 全字符串，【务必检查末尾无换行、开头无空格，粘贴时禁用富文本编辑器】。若使用中转服务（如硅基流动），还需确认 Base URL 是否与当前 Agent Space 配置一致。
添加新 Key 到凭证池
在终端中运行：hermes authadd 启动交互式向导。
第一步：输入 Provider 名称，例如 deepseek（大小写敏感，必须与 hermes auth list 中显示的 provider 字段完全一致）。
第二步：为该 Key 设置唯一标签，例如 deepseek-prod-202609。【标签不能和已有 Key 重复，否则 hermes auth list 将无法区分】。
第三步：粘贴刚复制的新 API Key，回车确认。成功后终端会提示 “Credential added successfully”。可重复执行此命令添加多个备用 Key。
停用旧 Key 并强制重载配置
编辑 ~/.hermes/config.yaml，确认 credential_pool_enabled: true 已启用。若为 false，需手动改为 true 并保存。
执行 hermes reload auth 强制刷新凭证池。这一步会清空内存缓存并重新读取 ~/.hermes/auth.json 中全部凭证，【旧 Key 不会自动删除，但只要不设为 active，就不会被轮询调用】。
发送测试请求：hermes chat "test key switch"。观察日志输出中的 using credential [label] 字样——若显示的是你刚添加的新标签名，说明切换已完成。
