18. 密钥

**密钥(secret)**是智能体或某个 adapter 需要、但你不希望以明文留在配置文件里的凭证。GitHub token、Slack bot token、模型 provider API key、内部 API 凭证 —— 都是密钥。OpenHermit 把它们存在独立存储中,运行时再代入配置。

18.1 什么放在哪儿

凭证谁在用怎么存
Anthropic / OpenAI 等 API key模型调用网关级密钥
Telegram / Discord / Slack bot token通道 adapter按智能体或网关级密钥
MCP 用的 GitHub / Slack 等 tokenMCP 服务按智能体密钥
内部 API key自定义 MCP 服务按智能体密钥

模式是:绝不把凭证粘到智能体的指令或消息里。放进密钥存储,然后引用它。

18.2 hermit config --agent ... secrets 命令

# 列出密钥名(不显示值)。
hermit config --agent main secrets list

# 设一个密钥。
hermit config --agent main secrets set GITHUB_TOKEN <value>

# 设一个要透传到 MCP / 通道 adapter env 的密钥。
hermit config --agent main secrets set GITHUB_TOKEN <value> --pass-through

# 设一个**不**希望暴露给子进程 env 的密钥。
hermit config --agent main secrets set INTERNAL_KEY <value> --no-pass-through

# 删除。
hermit config --agent main secrets remove GITHUB_TOKEN

网关级密钥(跨所有智能体共享)通常以环境变量放在网关宿主机上,不在 hermit config --agent ... secrets 里。这是运维侧的事。

18.3 密钥怎么被代入

配置里用 ${{NAME}} 按名引用密钥:

mcp_servers:
  github:
    env:
      GITHUB_TOKEN: ${{GITHUB_TOKEN}}

启动时,网关把真实值代入。智能体的 prompt 永远见不到原始密钥 —— 它只看到使用这些密钥的工具。

18.4 透传(Pass-Through)

很多密钥要传到子进程(MCP 服务的环境、通道 adapter 的运行时)。--pass-through(默认)代表要;--no-pass-through 代表密钥只留在网关内,只能由配置代入读取。对绝不该泄漏到子进程 env 表的凭证,用严格模式。

18.5 Web 管理界面

Manage → Secrets 显示密钥名(值隐藏),并允许设置 / 删除。底层存储与 CLI 一致。

18.6 角色差异

OwnerUserGuest
读密钥名✓——
读密钥值✓(只通过直接访问网关)——
设置 / 删除✓——

即使是 owner,设置之后也无法在 UI 中再看到密钥值 —— 只能写。要轮换,直接用新值重设。

18.7 How-to 配方

18.7.1 轮换 GitHub token

hermit config --agent main secrets set GITHUB_TOKEN <new-token>
hermit mcp disable mcp_github --agent main
hermit mcp enable  mcp_github --agent main

disable/enable 一轮重启 MCP 服务,让它拿到新值。有些 adapter 支持热更新 —— 看你那个 MCP 服务的具体行为。

验证 —— 让智能体做一个需要新权限的 GitHub 动作。

18.7.2 把指令里的凭证迁到密钥

你发现某个旧的 instructions 分区里有明文 API key。处理:

hermit config --agent main secrets set MY_API_KEY <value>
hermit instructions get tools --agent main         # 复制正文
# 本地编辑 —— 把明文 key 换成 ${{MY_API_KEY}}
hermit instructions set tools --file ./tools.md --agent main

验证 —— hermit instructions get tools 显示占位符,不是真值。

18.7.3 审计一个智能体上有哪些密钥

hermit config --agent main secrets list

如果看到不再对应任何已启用 MCP 或通道的名字,删掉。

18.8 FAQ

密钥实际存在哪里? 网关的数据库里,落盘加密(用网关的 key)。这份数据库的备份属于运维范畴 —— 确保备份也是加密的。

智能体能看到原始密钥值吗? 不能。智能体收到的是代入之后的配置(在相关 env / 工具定义里)。它的 prompt 上下文里永远没有值。

密钥能进版本控制吗? 不能。把密钥值当作易失的。版本控制密钥的名字和引用形式;值只属于密钥存储。

有按用户的密钥吗? 不支持。密钥按智能体划分。要按用户隔离凭证,一人一智能体。

18.9 指引