# 操作系统钥匙串与密钥存储

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

在桌面版中，这意味着：

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

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

***

## 进入操作系统钥匙串的内容

OpenHuman 使用操作系统钥匙串来存放两类本地机密材料：

### 1. 凭据条目

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

例如：

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

这些条目都限定在 OpenHuman 自己的密钥命名空间下，因此不会与无关应用冲突。

### 2. 主加密密钥

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

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

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

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

***

## 磁盘上保持加密的内容

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

这涵盖了如下本地机密：

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

加密格式带有认证，因此 OpenHuman 可以检测篡改，而不是静默接受被修改的密文。

实际上，这种安全模型是：

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

***

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

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

将操作系统钥匙串作为根机密存储可为 OpenHuman 提供更安全的分离方式：

* 配置文件可以被复制而不会暴露原始凭据
* 意外的日志或文件检查不太可能泄露机密
* 解密密钥由平台的凭据系统托管，而不是由应用管理的明文文件托管

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

***

## 托管集成与本地机密

并非每个机密都遵循相同路径。

### 托管集成

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

### 本地自带凭据

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

***

## 从旧版安装迁移

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

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

***

## 平台说明

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

在开发和测试环境中，仓库可能会使用仅供测试的覆盖设置，这样自动化运行就不依赖交互式 OS 钥匙串。这只是开发者便利措施，不是最终用户的桌面安全模型。

***

## 另请参阅

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/privacy-and-security/os-keyring-and-secret-storage.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.