---
title: 秘钥库与 SSH 主机：让 AI 按引用使用凭据
description: 在 Onevium 集中保存服务器、数据库、API 与云账号凭据，让 AI 按引用使用秘钥、在 SSH 服务器上执行命令，并用授权卡控制每次使用。
canonical_url: 'https://onevium.com/zh/docs/secrets-and-ssh'
language: zh-CN
updated_at: '2026-11-10'
publisher: Onevium
minimum_version: 1.3.3
---
> 内容来源：Onevium 官方文档
> 文章: 秘钥库与 SSH 主机：让 AI 按引用使用凭据
> 原文: https://onevium.com/zh/docs/secrets-and-ssh
> 语言：简体中文
> 更新于: 2026-11-10
> 适用版本: 1.3.3+

---

# 秘钥库与 SSH 主机：让 AI 按引用使用凭据

在 Onevium 集中保存服务器、数据库、API 与云账号凭据，让 AI 按引用使用秘钥、在 SSH 服务器上执行命令，并用授权卡控制每次使用。

## 秘钥库能做什么

秘钥库把服务器、数据库、API、云账号等凭据加密保存在本机（使用系统钥匙串加密），按分类和标签整理。AI 只拿到引用写法，例如 `{{secret:shop-db-staging.password}}`；真正执行命令时，由 Onevium 在本机填入秘钥，并把输出里出现的已知秘钥替换成 `[secret:名称.字段]`。

配合 SSH 主机条目，AI 可以在你授权后到服务器上执行命令、读取或写入文件。每次使用都会先弹出授权卡，由你决定允许多久。

秘钥库只能在 Onevium 桌面版中使用；网页模式打开该页面只会看到提示。

## 1. 打开秘钥与主机并启用 AI 使用

1. 打开 **设置**，在 **AI 与连接** 分组中点击 **秘钥与主机**（图 1 中的 ①）。页面有 **条目**、**授权**、**分类**、**标签** 四个标签页。
2. 页面顶部显示 **AI 使用已关闭** 时，点击 **启用**（图 1 中的 ②）。AI 使用默认关闭；启用后每个会话会多带 3 个工具（约 916 token），关闭时会话完全不带。
3. 点击 **新建**（图 1 中的 ③）开始添加条目，或点击旁边的 **导入** 读取本机已有配置。

![设置中的秘钥与主机页面：左侧导航选中秘钥与主机，右侧显示 AI 使用已关闭及启用按钮，下方条目列表包含 SSH 主机、SSH 身份、数据库、API 凭据和网站](https://onevium.com/assets/docs/secrets-ssh/zh/secrets-ssh-01-settings.png "图 1：① 进入秘钥与主机，② 启用 AI 使用，③ 新建条目。1.3.2 真实组件的隔离演示，条目、主机和时间均为模拟数据，未连接任何服务器。")

AI 使用关闭时，已保存的条目、分类和标签仍可以在这里管理。不再需要时，点页面底部的 **关闭 AI 使用**：所有授权立即撤销，SSH 连接随之断开，条目继续加密保存在本机。同一个开关也在 **设置 → 工具** 中。

## 2. 添加 SSH 身份与 SSH 主机

以一个跨境电商团队为例：预发环境的 API 服务器是 `api.staging.example.com`，用 `deploy` 用户和私钥登录。

**先添加 SSH 身份（登录凭据）：**

1. 点击 **新建**，在 **服务器与网络** 分组中选择 **SSH 身份**。
2. **名称** 填 `deploy-key`。名称只能用小写字母、数字和连字符，它也是 AI 引用这个条目时的写法。
3. **用户名** 填 `deploy`，**登录方式** 选择 **私钥**（默认）。其他选项有 **SSH agent 代理**、**带口令的私钥**、**密码** 和 **本机私钥文件**。
4. 在 **私钥** 中粘贴 OpenSSH、PEM 或 PKCS#8 格式的私钥；EC2 或阿里云下载的 `.pem` 内容可直接粘贴。要直接使用本机上的私钥文件，把登录方式改为 **本机私钥文件**。点击 **添加**。

**再添加 SSH 主机：**

1. 点击 **新建**，选择 **SSH 主机**。
2. 按图 2 填写：**名称** `staging-api`，**标签** 选 `env: staging`，**主机** `api.staging.example.com`，**端口** `22`，**用户** `deploy`，**SSH 身份** 选 `deploy-key`，**默认目录** `/srv/shop`。
3. **授权方式** 保留 **限时授权（默认）**；希望每条命令都单独确认时选 **每次都确认**。需要跳板机时，先把跳板机也存为 SSH 主机，再在 **跳板机** 中选择它。
4. 点击 **添加**。

![新建 SSH 主机表单：名称 staging-api，标签 staging，主机 api.staging.example.com，端口 22，用户 deploy，SSH 身份 deploy-key，默认目录 /srv/shop，授权方式为限时授权](https://onevium.com/assets/docs/secrets-ssh/zh/secrets-ssh-02-ssh-host.png "图 2：新建 SSH 主机的必要字段。1.3.2 真实组件演示，主机和身份均为虚构，本图未保存条目，也未连接服务器。")

**高级** 中可以填写 **代理命令**、**\~/.ssh/config 中的别名**、**连接方式**（**自动** 或 **系统 OpenSSH**）和 **两步验证码**。这些会让本机运行命令或读取本地文件的字段只能在设置页修改，AI 无法写入。

**允许 AI 读取明文** 默认关闭，AI 只使用引用。开启后 AI 可以申请读取明文，每次读取都要你单独允许，明文随后会发送给模型服务商。

保存后，把鼠标移到条目上，可以 **复制引用写法** 或 **测试连接**。第一次连接某台服务器时会弹出 **首次连接 …** 卡片，显示主机指纹：先和管理员或云控制台核对，再点击 **信任并连接**。

**标签用来区分环境。** 给生产服务器打上 `env: prod` 后，它会被当作生产条目：授权最长 15 分钟、不会在无人响应时自动允许，也不能在渠道聊天里批准。

## 3. 从本机配置导入

已经在用 `~/.ssh/config` 或云厂商 CLI 时，不必逐个手填：

1. 在 **条目** 标签页点击 **导入**，打开 **导入本机配置**。
2. 在 **本地配置** 中勾选要导入的项目。可读取的来源包括 SSH 配置（`~/.ssh/config`）、阿里云、AWS、腾讯云、Kubernetes、GitHub CLI 和 Docker。
3. 点击 **导入 N 项**。已经在库中的项目会显示 **已在库中：名称**。

导入后原文件不变，可以自己删掉里面的明文。通过浏览器登录或单点登录（SSO）的账号没有固定秘钥，会显示原因且不能导入。

AI 也可能主动处理凭据：

- AI 想读取凭据文件时，会弹出 **AI 想读取凭据文件** 卡片，文件内容会进入 AI 的上下文。这类卡片只能在电脑上处理，可以点 **改为导入到秘钥库**，改由秘钥库保存。
- AI 不会让你把秘钥粘贴到对话里。它新建或修改条目时，会弹出卡片让你直接输入秘钥；如果它指明了包含秘钥的文件，卡片会显示「已从 … 读出 N 个值，确认后保存」，核对后再允许。

## 4. 让 AI 在服务器上执行命令

在会话中写明主机名称和要做的事，例如：

```text
用 staging-api 查看 shop-api 服务的状态和最近 50 行错误日志。
只读排查，不要修改文件或重启服务。
```

AI 发起 SSH 请求后，输入区位置会显示授权卡（图 3）：

1. 核对标题 **AI 想在 staging-api 上执行命令**、登录地址和完整命令。命令太长时点右侧箭头展开。
2. 点击左下角的时长（图 3 中的 ①）选择授权多久：**仅这一次**、**5 分钟**、**15 分钟**、**1 小时** 或 **本会话**。选择限时授权后，还可以勾选 **也用于全部会话** 或 **也用于全部秘钥（不含生产）**；**本会话不再询问** 会在允许这次后，为当前会话开启一段免授权时间。
3. 点击 **允许**（图 3 中的 ②），或点击 **拒绝**。

![授权卡显示 AI 想在 staging-api 上执行命令、登录地址和命令，左下角时长菜单已展开，列出仅这一次、5 分钟、15 分钟、1 小时、本会话及扩大范围选项](https://onevium.com/assets/docs/secrets-ssh/zh/secrets-ssh-03-authorize.png "图 3：① 选择授权时长，② 允许。1.3.2 真实授权卡的隔离演示，主机和命令为虚构，未执行命令；因已点开菜单，右上角显示倒计时已暂停。")

普通请求无人响应时，卡片会在 2 分钟后自动允许这一次；只要在卡片上点过任何地方，倒计时就会暂停，改为 10 分钟后自动拒绝。

**预期结果：** 允许后，AI 在服务器上执行命令并返回输出，输出中的已知秘钥显示为 `[secret:名称.字段]`。在授权有效期内，同一会话再次使用这台主机不会重复询问。

除了 SSH，AI 还可以在本机执行命令，把秘钥作为该进程的环境变量注入（例如 `MYSQL_PWD`），授权卡上会显示「注入 MYSQL\_PWD」。命令会把秘钥写进 CLI 配置文件、关闭证书校验，或把秘钥放进进程参数时，卡片会用黄色提示标出；前两类命令每次只能允许一次，用在生产条目上会直接被拒绝。

## 5. 管理授权与免授权

打开 **设置 → 秘钥与主机 → 授权**（图 4）：

- **免授权**：选择 **时长**（**15 分钟**、**1 小时** 或 **直到退出 Onevium**），点击 **开启免授权**。在这段时间内，AI 可以直接使用、修改、删除秘钥条目，连接未登记的主机和地址，并读取凭据文件；查看明文、需要你输入的值、把秘钥写进 CLI 配置文件的命令仍会询问，主机指纹变化的服务器仍会被拒绝。**包括生产条目** 默认勾选，不想放开生产环境时取消勾选。
- **生效中的授权**：列出每条授权、所属会话和剩余时间，可单独 **撤销** 或 **全部撤销**。锁屏或退出 Onevium 会撤销全部授权并结束免授权。
- **无人响应时**：默认 **自动允许一次**，可改为 **自动拒绝**。主机指纹、两步验证码、需要你输入的值、删除和读取明文、生产环境秘钥与凭据文件、来自渠道或其他会话的请求，总是在 10 分钟后拒绝。
- **授权卡默认时长**：新卡片默认选中的时长。在卡片上改选时长并允许后，这里会跟着更新；生产条目的卡片最长 15 分钟。

![秘钥与主机的授权标签页：免授权时长与包括生产条目选项，生效中的授权列表，无人响应时与授权卡默认时长设置](https://onevium.com/assets/docs/secrets-ssh/zh/secrets-ssh-04-access.png "图 4：授权标签页。1.3.2 真实组件演示，两条授权和会话标题为模拟数据，未开启免授权。")

**渠道与定时任务：** 通过渠道机器人发来的请求，授权卡会注明「来自渠道聊天」。普通的查看与使用请求可以直接在聊天里批准，最长 15 分钟；生产环境秘钥、凭据文件、带警告的请求，以及需要输入内容的请求只能在电脑上确认。定时任务没有人在场确认，默认不能使用秘钥库；只有开启免授权并勾选 **也包括渠道会话与定时任务** 时才会放行。勾选前注意：届时能给你的机器人发消息的人都能用到这些秘钥。

## 6. 两步验证码

网站、SSH 主机、SSH 身份、云账号等条目可以保存 **两步验证码**：

1. 在条目的 **两步验证码** 字段粘贴设置链接（`otpauth://…`）、设置密钥，或点击 **识别二维码图片** 读取二维码截图。
2. 保存后再打开条目，该字段显示当前验证码和刷新倒计时，可点击 **复制验证码**。
3. 要批量迁移，在 **导入** 中切换到 **两步验证码**，粘贴 Google 身份验证器的导出二维码截图或 `otpauth://` 链接。

使用方式：

- **SSH 登录**：服务器要求验证码时，如果主机或 SSH 身份中保存了两步验证码，Onevium 会自动填入；没有保存时会弹出 **… 要求验证身份** 卡片，让你输入这一次的验证码，不会保存。
- **内置浏览器**：登录页要求验证码时，网址匹配的网站条目会在已保存账号建议中显示 **填入验证码**，可能需要先通过 Touch ID 等系统验证。
- **菜单栏**：从 1.3.2 起，可以在菜单栏快捷中心搜索并复制验证码和密码，见 [菜单栏快捷中心](https://onevium.com/zh/docs/menu-bar-hub)。

AI 拿到的永远是当前验证码的引用 `{{secret:名称.totp}}`，不会拿到验证码种子。

## 常见问题

| 现象                     | 怎么做                                                    |
| ---------------------- | ------------------------------------------------------ |
| 页面显示「系统钥匙串不可用」         | 解锁系统钥匙串或重新登录桌面会话，再点 **重试**                             |
| AI 说找不到秘钥工具            | 确认页面顶部没有显示 **AI 使用已关闭**；启用后在新消息中重试                     |
| 授权卡没有出现就被拒绝            | 检查该请求是否来自定时任务；或在 **授权 → 无人响应时** 查看是否设为 **自动拒绝**        |
| 想授权更久但选项里没有            | 条目带 `env: prod` 时最长 15 分钟；删除和读取明文只能允许一次；渠道里的请求最长 15 分钟 |
| 连接被拒绝并提示主机指纹变化         | 先向管理员确认服务器是否重装过。确认无误后，在条目中点击 **忘记主机指纹**，下次连接时重新核对指纹    |
| 输出中出现 `[secret:名称.字段]` | 这是被遮蔽的秘钥，属于正常结果，不是错误                                   |
| 机器人里批准不了某个请求           | 生产环境秘钥、凭据文件、带警告或需要输入内容的请求只能在电脑上处理                      |

### 添加与导入验证码

在快捷中心打开验证码操作，可填写设置密钥、读取二维码图片，或检查受支持的批量导入内容，包括 Google 身份验证器导出。确认前逐项检查账号名称和目标秘钥条目，保留未选中的条目及原有登录字段。保存后打开详情核对发行方和账号，再使用验证码；不要把设置密钥贴到公开会话或截图中。

## 下一步

- 了解会话的工作模式与工具权限：[工作模式与权限](https://onevium.com/zh/docs/permissions)
- 让 AI 在内置浏览器中登录和检查网页：[浏览器自动化](https://onevium.com/zh/docs/browser-automation)
- 通过机器人在聊天里继续工作：[渠道概览](https://onevium.com/zh/docs/team-channels)
- 不打开主窗口取用验证码和密码：[菜单栏快捷中心](https://onevium.com/zh/docs/menu-bar-hub)
