> 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/approval-gate.md).

# 审批闸门

审批闸门是代理与外部世界之间的检查点。每当代理想要运行会产生现实世界影响的工具时（发送到 Slack、发送电子邮件、创建日历事件、运行 shell 命令、安装软件包），闸门都会拦截该调用，向你准确展示即将发生的事情，并在任何操作运行之前等待你的决定。

它默认开启。在交互式聊天中，任何会产生外部影响的操作都不会在未经你同意的情况下离开你的机器。

***

## 什么会触发提示

每个执行型工具调用都会被归类为一个 **命令类别**，而你的 **自主层级** 决定该类别是静默运行、弹出提示，还是被阻止。

| 命令类别 | 涵盖内容                      |
| ---- | ------------------------- |
| 读取   | 可证明为只读 / 仅观察性（精选允许列表）     |
| 写入   | 会改变状态；任何无法识别内容的默认故障关闭分类   |
| 网络   | 访问网络（curl、wget、ssh、scp、…） |
| 安装   | 安装操作系统或全局语言软件包            |
| 破坏性  | 灾难性 / 不可逆 / 权限提升          |

该层级来自 **设置 → 代理访问** (`[autonomy].level`):

| 层级         | 读取 | 写入 | 网络 / 安装 / 破坏性 |
| ---------- | -- | -- | ------------- |
| 只读         | 允许 | 阻止 | 阻止            |
| 受监督 *（默认）* | 允许 | 提示 | 提示            |
| 完全         | 允许 | 允许 | 提示            |

任何落在 **提示** 的内容都会停放在闸门处。 `阻止` 会被直接拒绝：同层级内的任何批准都无法授权它。分类采用故障关闭原则。无法被证明为只读的命令，至少会被视为 `写入`，而在管道命令中，以最高等级的类别为准（因此 `ls | curl …` 是 `网络`).

***

## 流程

```
代理想要执行操作
        │
        ▼
 对命令分类 ──► 阻止 ──► 拒绝
        │
     提示
        │
        ▼
 在“始终允许”列表中？ ──► 是 ──► 立即运行
        │ 否
        ▼
 停放调用 · 持久化待处理行 · 发出 approval_request
        │
        ▼
 ┌──────────────┬───────────────┬────────────┐
 ▼              ▼               ▼            ▼
批准     始终允许      拒绝      10 分钟 TTL
（一次）    （+ 允许列表）                     │
 │             │               │            ▼
 ▼             ▼               ▼          拒绝
 运行           运行           拒绝   （故障关闭）
```

当一个调用被停放时，一个 **审批请求卡片** 会出现在聊天输入框上方。它会显示工具名称、该操作的一行安全摘要，以及（已脱敏的）命令。共有三种选择：

* **批准**：运行这一次调用。
* **始终允许**：运行它，并将该工具添加到你的 `auto_approve` 列表中，这样下次就会跳过提示。
* **拒绝**：拒绝这次调用。

你也可以直接输入 **是** / **否** 到聊天中。回复会被路由回已停放的请求。

***

## 始终允许

使用 **始终允许** 批准会将该工具名称持久化到 `[autonomy].auto_approve` （配置保存 + 实时策略重载），因此闸门会在未来的轮次中对此工具直接短路为 *允许* 。该列表默认预先批准了安全的只读工具（`file_read`, `memory_search`, `memory_list`, `get_time`, `list_dir`, `glob`, `grep`），并且可在 **设置 → 代理访问**中编辑。删除其中的条目即可重新开始收到提示。

***

## 故障关闭行为

每一条非批准路径最终都会变为 **拒绝**:

* **超时**：一个已停放请求会保留 10 分钟；如果期间未作决定，它会被转为最终的 `拒绝`.
* **持久化失败** 或通道中断：拒绝。
* 超时路径会先重新读取已存储的决定，因此如果批准在竞争条件中已经提交，仍以批准为准。

待处理请求会存储在 SQLite 中（`{workspace_dir}/approval/approval.db`），并且 **在核心重启后仍会保留**。在获批的工具执行完成后，闸门会记录一次写入的执行结果（成功 / 错误，错误文本会被脱敏并截断）作为持久的审计轨迹。所有被持久化或广播的内容都会先经过脱敏处理：PII 和聊天内容会被清除，主目录路径会被去除。

***

## 后台和 cron 绕过

该闸门是 **仅限交互式**。后台、分诊和 cron 轮次不带聊天上下文，因此没有人能回答提示。这些轮次会被预先授权并直接通过（没有记录行，也没有事件）。审批只对实时聊天轮次强制执行。（Subconscious 循环对 *非请求的* 写入有其自身独立的升级卡片审批；见下文。）

***

## 配置与 RPC

* **`OPENHUMAN_APPROVAL_GATE`**：设为 `0` / `false` 即可完全跳过安装该闸门。没有闸门时， `提示`-类调用会在不提示的情况下运行。默认开启。
* **`[autonomy].level`** 以及 **`[autonomy].auto_approve`**：层级和允许列表，可通过 `config.update_autonomy_settings` RPC 或“设置 → 代理访问”进行配置。

该 `审批` 控制器公开了三个 JSON-RPC 方法：

| 方法                                         | 用途                                                         |
| ------------------------------------------ | ---------------------------------------------------------- |
| `openhuman.approval_list_pending`          | 已停放请求的实时队列。                                                |
| `openhuman.approval_list_recent_decisions` | 已决策/已执行的审计记录（`限制` 1 到 500，默认 50）。显示于 **设置 → 审批历史**.        |
| `openhuman.approval_decide`                | 应用一个决定（`approve_once` / `approve_always_for_tool` / `拒绝`). |

`list_pending` / `list_recent_decisions` 在未安装闸门时返回空结果（不是错误）； `decide` 在闸门不存在、请求未知或已经被决定时会报错。

***

## 另见

* [隐私与安全](/openhuman/zh/gong-neng/privacy-and-security.md)：自主层级、受信任根，以及路径加固。
* [潜意识循环](/openhuman/zh/gong-neng/subconscious.md)：后台循环及其独立的升级审批。
* [安全架构](/openhuman/zh/kai-fa/architecture/security.md)：命令分类和策略的内部机制。