> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openkova.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 安全与密钥

> API Key 加密存储、工具输出脱敏、MCP 密钥注入边界——本地优先具体怎么保护你的凭据，以及保护到哪里为止。

本地优先意味着凭据和会话都留在你自己的机器上。这一页说明它们**具体怎么被保护**，
以及**保护到哪里为止**——哪些是硬边界，哪些只是兜底。

## 密钥怎么存

模型 API Key、MCP 凭据、远程访问 token、备份配置这些敏感项，加密后才落在本机
SQLite 里，**不写明文**：

* 算法是 **AES-256-GCM**，主密钥为 32 字节随机数；
* 主密钥优先由 **Electron safeStorage** 包裹后保存（macOS 上即系统钥匙串）；
  safeStorage 不可用时退化为 0600 权限的本地密钥文件，并在密钥页明示当前后端
  （系统钥匙串 / 本地密钥文件 / 不可用）；
* 主密钥文件**不进**会话库、**不进**备份包；
* 旧版本的明文行会在启动时原地加密迁移。

备份与恢复时，密文随库一起走：同机恢复即可用；换机后主密钥不同，
密钥会显示"无法解密，需重填"——密文换把钥匙就打不开，这是有意的。

## 工具输出脱敏

注入到 bash 的密钥会在线程内登记（24 小时 TTL）。此后工具结果（`read`、
浏览器、HTTP、子任务输出等）在进入模型上下文之前先做**递归脱敏**：
命中已注入密钥的原值与 base64 变体，一律改写成 `[REDACTED:NAME]`；
图片数据字段保持原样不被改写。短于 8 字符的串不参与脱敏，避免误伤普通文本。

> [!WARNING]
>
> 脱敏只覆盖原值与 base64。模型仍可能通过反转、十六进制、主动发网络请求等方式
> 把值带出去——**这是输出兜底，不是硬隔离**。真正需要隔离时请用沙箱或容器。

## MCP 密钥注入

给 MCP 服务器（如 GitHub）注入 token 时，遵循几条硬边界：

* **绑定只存本机**。`.mcp.json` / 工作区覆盖层 / 插件清单里**不能**声明自己要哪些密钥
  ——工作区文件跟着仓库走，不能自我授权。绑定关系只存在本机 kv。
* **绑定按服务器名 + 启动配置哈希生效**。工作区覆盖或改启动命令都会让哈希变化，
  旧绑定立即失效——不会出现"同名服务器换了命令却继续拿到原来那批密钥"。
* **只允许全局作用域的密钥**。MCP 连接池按服务器名跨会话共享，
  工作区作用域的值塞进全局子进程会有歧义。
* **配置里只有绑定关系，没有值**。保存的是"环境变量名 → 密钥名"的映射；
  密钥值既不写进 `mcp.json`，也不回传界面。
* **明文不跨进程**。stdio MCP 子进程由 sidecar 拉起，宿主无法直接改它的环境变量，
  于是 sidecar 把映射交给宿主，宿主解密后只回环境变量映射，sidecar 再交给子进程。
* 值只在 sidecar 内存里活到连接断开；连接断开、配置变更、密钥值变更都会丢弃。

MCP 工具的返回结果同样先走输出脱敏再进模型上下文。

已知限制：HTTP 形态的 MCP 尚未接密钥注入（仍用配置里的字面量 headers）。

## 审批是确定性代码

除了密钥，另一道边界是**工具执行要问你**。挂起、批准、拒绝、回滚都发生在
确定性代码里，模型说"我做完了"不算数。会话模式管"能不能改"、权限档位管"要不要问"、
沙箱档管"能写到哪"——三套机制彼此独立，详见[模式总览](https://docs.openkova.site/features/modes.md)
与[沙箱](https://docs.openkova.site/features/sandbox.md)。

## 一句话总结

密钥加密落盘、输出尽力脱敏、MCP 注入最小授权、执行前问你——
每一层都明确了它管什么、不管什么。剩下的判断（尤其"要不要把值带出机器"）
依赖你对通道与插件可信度的评估，这一层没有银弹。

> [card] [下一步](https://docs.openkova.site/features/modes.md)
>
> 看看工具执行的审批边界是怎么落地的。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.