> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/privacy-and-security/os-keyring-and-secret-storage.md).

# OS 钥匙串与机密存储

OpenHuman 使用 **操作系统的安全凭据存储** 来保护必须保留在你设备上的机密。

在桌面版中，这意味着：

* **macOS：** 钥匙串
* **Windows：** 凭据管理器
* **Linux：** Secret Service / libsecret

这是本地机密材料的信任根。OpenHuman 不依赖明文 `.env` 文件或用于用户凭据的明文本地配置文件。

***

## 什么内容会进入操作系统钥匙串

OpenHuman 将操作系统钥匙串用于两类本地机密材料：

### 1. 凭据条目

当某个功能需要本地凭据槽时，OpenHuman 会将其存储在平台钥匙串中，而不是把原始机密写入普通配置文件。

例如包括：

* 本地存储的提供方 API 密钥
* 必须保留在设备上的会话令牌和持有者令牌
* 在适用情况下的钱包机密材料

这些条目位于 OpenHuman 自己的键命名空间下，因此不会与无关应用冲突。

### 2. 主加密密钥

某些敏感值仍然需要保留 **在本地文件中** 因为应用配置本身就是基于文件的。

OpenHuman 通过将存储分成两部分来处理：

* 的 **磁盘上的机密值** 以加密密文形式存储
* 的 **用于解密它的主密钥** 存放在操作系统钥匙串中

这意味着你的本地配置和状态文件可以包含加密值，而解密密钥不会以明文形式紧挨着它们存放。

***

## 什么内容会在磁盘上保持加密

当 OpenHuman 需要在本地持久化敏感应用设置时，它会将 **密文** 写入磁盘，并将密钥保存在操作系统钥匙串中。

这包括诸如以下的本地机密：

* 支持的提供方的自带 API 密钥
* 存储在本地配置中的通道和 Webhook 机密
* 桌面功能所需的其他本地持久化机密设置

加密格式经过认证，因此 OpenHuman 可以检测篡改，而不会默默接受被修改的密文。

实际上，安全模型是：

* **密钥在钥匙串中**
* **密文在文件中**
* **仅在需要时以明文存在于内存中**

***

## 为什么这比明文配置更好

如果你的机器上有本地工作区备份、同步文件夹或支持包，配置文件中的明文机密就是一种风险。

将操作系统钥匙串用作根机密存储，使 OpenHuman 拥有更安全的分离：

* 复制配置文件时不会暴露原始凭据
* 误查看日志或文件更不容易泄露机密
* 解密密钥委托给平台的凭据系统，而不是由应用管理的明文文件

这并不能替代全盘加密或操作系统账户安全。它是一种更窄范围、更强的应用机密处理方式。

***

## 托管集成与本地机密

并非所有机密都走同一条路径。

### 托管集成

对于默认的托管集成流程，第三方 OAuth 令牌由 OpenHuman 后端处理。你的本地应用不 **不** 需要在你的机器上以明文持久化这些提供方令牌。

### 本地自带凭据

当你选择自带密钥或直连模式路径时，OpenHuman 会将这些凭据视为 **本地机密** 并在需要时使用操作系统钥匙串以及静态加密的本地存储来保护它们。

***

## 从旧版本安装迁移

较早版本可能会以基于文件的形式保存本地加密材料。

当前桌面版会将这些材料迁移到操作系统钥匙串中，并将加密载荷保留在磁盘上。目标是把根机密从普通文件中移到平台凭据存储中，而无需用户手动重新输入每个机密。

***

## 当钥匙串不可用时的同意流程

有时操作系统钥匙串无法访问，例如在没有 Secret Service 守护进程的 Linux 上，或者在 macOS 上钥匙串访问被拒绝时。发生这种情况时，OpenHuman **会停止并询问** 之后才回退到本地加密存储。

### 工作原理

1. **检测。** 启动时，核心会探测操作系统钥匙串。如果探测失败，它会对原因（无守护进程、已锁定、被拒绝）进行分类，并报告一个结构化的 `KeyringStatus` 通过 `openhuman.keyring_consent_status` RPC 以及应用快照。
2. **同意提示。** 当某个机密首次需要读取或写入且尚未记录同意时，一个模态覆盖层会说明发生了什么、“本地存储”意味着什么以及风险是什么。用户可以：
   * **使用本地加密存储**：同意使用 ChaCha20-Poly1305 加密文件（主密钥也保存在磁盘上）。
   * **重试操作系统钥匙串**：重新探测（在授予操作系统权限后有用）。
   * **跳过**：拒绝本地存储；需要机密的功能将不可用。
3. **已持久化的偏好。** 该选择记录在 `app-state.json` (`keyringConsent` 字段中）并缓存在进程内。应用在每次启动时都会重新探测，如果在仅本地会话之后钥匙串变得可用，则会再次提示。
4. **设置可见性。** **设置 → 安全** 显示当前存储模式、钥匙串可用性、失败原因，以及用于重试或更改同意的按钮。

### 统一回退策略

身份验证配置文件、配置机密、钱包助记词，以及 `secrets.enc` 后端都调用 `keyring_consent::policy::check_secret_access()` 而不是直接调用原始的 `is_available()`。这确保没有任何代码路径会悄悄切换存储模式。

| 策略决策   | 含义                   |
| ------ | -------------------- |
| `继续`   | 操作系统钥匙串可用，或用户已同意本地加密 |
| `需要同意` | 钥匙串不可用，尚未获得同意；阻止并提示  |
| `已拒绝`  | 用户拒绝本地存储；跳过该机密操作     |

***

## 平台说明

本页描述 **桌面版** OpenHuman：运行于 macOS、Windows 和 Linux 的 Tauri 应用。

在开发和测试环境中，仓库可能会使用仅测试的覆盖配置，这样自动化运行就不依赖交互式操作系统钥匙串。这是开发者便利功能，不是终端用户桌面安全模型。

***

## 另请参阅

* [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)
* [第三方集成](/openhuman/zh/gong-neng/integrations.md)
* [本地 AI（可选）](/openhuman/zh/gong-neng/model-routing/local-ai.md)