---
url: /zh/guides/access.md
---
# 访问控制

Memoh 的访问控制分成两层：

* **渠道成员**：控制来自 Telegram、Discord、飞书、QQ 等 IM 渠道的身份。
* **工作区成员**：控制客户端和工作区里的 Memoh 注册用户。

旧的 ACL 规则模型仍然存在，但现在主要作为渠道聊天权限背后的高级引擎。日常配置应优先从 Bot 的 **Access** 页开始，使用 **渠道成员** 和 **工作区成员** 两个入口。

***

## 核心模型

| 层级 | 身份 | 控制内容 |
|------|------|----------|
| **渠道成员** | IM 平台上观测到的渠道身份 | 这个平台身份能否和 Bot 聊天，以及能否通过 IM 命令管理 Bot |
| **工作区成员** | Memoh 注册用户账号 | 这个用户能否在客户端使用 Bot、读写文件、执行工作区命令或管理 Bot 设置 |

这两层可以通过账号绑定连接起来。工作区用户可在 **Profile -> Connected Accounts** 生成一次性代码，然后在 IM 里向某个 Memoh Bot 发送 `/link <code>`，把发送消息的渠道身份绑定到自己的 Memoh 账号。

绑定本身不授予访问权限。它只负责连接身份。真正的权限仍来自渠道成员、工作区成员、Bot 所有者或系统管理员身份。

***

## 快速开始

### 允许任何 IM 用户聊天

1. 打开 Bot 的 **Access** 页。
2. 进入 **渠道成员**。
3. 将 **访问模式** 设为 **黑名单模式**。
4. 保持成员列表为空，或只添加要拦截的身份。

黑名单模式表示 ACL 默认行为是 `allow`。除非命中拒绝规则，否则所有人都能聊天。

### 只允许指定 IM 身份

1. 打开 **渠道成员**。
2. 将 **访问模式** 设为 **白名单模式**。
3. 添加允许访问的渠道身份。
4. 为每个允许身份保持 **聊天** 勾选。

白名单模式表示 ACL 默认行为是 `deny`。只有命中允许规则的身份能聊天。

### 给 Web 用户授权

1. 打开 **工作区成员**。
2. 添加指定成员，或添加 **全部成员**。
3. 选择该成员应该拥有的权限。

工作区访问面向 Memoh 注册用户。除非用户绑定了自己的 IM 身份，否则它和 IM 聊天权限是分开的。

***

## 渠道成员

渠道成员是 IM 侧的访问控制入口。

每一行代表一个**渠道身份**（一个 Telegram 用户或 Discord 成员），或一个**群聊**（见下）。成员从卡片头部的内联选择器添加，个人身份和群聊候选在同一个下拉里分区展示。每一行有两个互相独立的权限：

| 权限 | 含义 |
|------|------|
| **聊天** | 控制该 IM 身份发来的入站消息能否触发 Bot。 |
| **管理** | 控制该身份能否通过 IM slash command 管理 Bot。管理权限不会自动授予聊天权限。 |

### 聊天

聊天勾选框背后是 `chat.trigger` 的 ACL 规则。

在**黑名单模式**下：

* 默认是 `allow`
* 添加身份或取消勾选聊天，会创建拒绝规则
* 勾选聊天，会删除该身份的拒绝规则

在**白名单模式**下：

* 默认是 `deny`
* 添加身份或勾选聊天，会创建允许规则
* 取消勾选聊天，会删除该身份的允许规则

### 管理

管理勾选框会为该渠道身份写入一个本地 Channel Access 覆盖。

管理权限用于 IM 命令。它让某个渠道身份可以在 owner 级别的 slash command 流程里作为 Bot 管理者行动。它刻意和聊天权限分开：即使某个身份有管理权限，只要聊天关闭或 ACL 拒绝，它的普通聊天消息仍会被拦截。

### 群聊作为成员

除了单个身份，也可以把整个**群聊**加成一行成员。群聊候选来自 Bot 在各渠道观测到的会话，行上带"群"标记。

* 群行的**聊天**勾选含义是"这个群里的所有人"——白名单模式下放行全群，黑名单模式下屏蔽全群。
* **群没有管理权限**。管理者永远是单个渠道身份。
* 要表达"这个人、在这个群里"这类组合，仍然走高级 ACL 规则。

### 平台成员

如果某个渠道身份已经绑定到此 Bot 的工作区成员，这一行会被标记为平台成员。

当对应的工作区成员在 **工作区成员** 中拥有 **管理** 权限时，该渠道身份会自动继承管理权限。渠道成员行会显示这个管理权限来自继承。若你在渠道成员里切换管理权限，Memoh 会写入本地覆盖：

* 本地**开启**会强制该渠道身份拥有管理权限
* 本地**关闭**会压制该渠道身份继承来的管理权限
* **恢复继承**会删除本地覆盖，重新跟随工作区成员权限

只有纯本地渠道行可以从渠道成员里删除。平台成员行来自账号绑定，应通过权限设置或断开绑定来管理。

***

## 工作区成员

工作区成员是 Web/工作区侧的访问控制入口。

你可以授权给：

* **指定成员**
* **全部成员**

Bot 所有者会作为隐式 owner 条目显示，并始终拥有完整权限。系统管理员也会解析为完整权限。

工作区权限包括：

| 权限 | 允许的操作 |
|------|------------|
| **可对话** | 在 Web 聊天界面使用 Bot。 |
| **可读文件** | 读取 Bot 工作区文件。 |
| **可写文件** | 修改 Bot 工作区文件，并隐含可读文件。 |
| **可执行命令** | 运行工作区执行流程。 |
| **可管理** | 管理 Bot 设置和访问控制，并隐含所有其他工作区权限。 |

工作区管理权限也会流入渠道成员。若一个拥有工作区管理权限的用户绑定了 Telegram 身份，该 Telegram 身份会在渠道侧继承管理权限。

工作区的**可对话**不等于渠道的**聊天**。工作区权限授权客户端与工作区 API；渠道聊天权限则通过 ACL 引擎授权 IM 入站消息。

***

## 绑定渠道身份

用户可在 **Profile -> Connected Accounts** 绑定 IM 身份：

1. 点击 **Connect**。
2. 复制生成的 `/link <code>` 命令。
3. 在 IM 渠道里把它发送给某个 Memoh Bot。
4. 该代码会把发送消息的渠道身份绑定到当前 Memoh 用户账号。

重要细节：

* link code 是一次性的，并且会在短时间后过期
* 即使发送者被聊天 ACL 拒绝，`/link <code>` 仍然允许执行，所以用户能从未绑定状态恢复
* 绑定是账号级别的：它全局连接工作区用户和渠道身份
* 绑定本身不授予聊天或管理权限

绑定完成后，对应渠道成员行可以继承工作区管理权限。

***

## 访问模式与高级 ACL 规则

渠道聊天使用 ACL 引擎。Access 页把它呈现为**访问模式**加可选的高级规则。

| 访问模式 | ACL 默认行为 | 真正影响结果的规则 |
|----------|--------------|--------------------|
| **黑名单模式** | `allow` | `deny` 规则 |
| **白名单模式** | `deny` | `allow` 规则 |

只有和当前默认行为相反的规则会覆盖默认模式。和默认行为相同的规则不会改变结果。

高级规则可以针对：

* 所有用户
* 某个平台上的所有用户
* 某个渠道身份
* 某个平台上的某个渠道身份

高级规则也可以限定在：

* 任意聊天
* 私聊
* 群聊
* 话题/线程
* 指定会话 ID
* 指定 thread ID

规则目标负责平台过滤。来源范围负责会话和 thread 过滤。

和旧 ACL 文档不同，当前版本不再提供手动规则优先级或拖拽排序行为。理解时应按“当前默认模式 + 命中的反向规则”来判断。

***

## 创建预设

创建 Bot 时选择的 ACL 预设，只初始化渠道聊天行为。之后可在 **渠道成员** 中修改。

| 预设 | 初始行为 |
|------|----------|
| `allow_all` | 默认行为 `allow`；不额外创建规则 |
| `private_only` | 默认行为 `deny`；允许私聊 |
| `group_only` | 默认行为 `deny`；允许群聊 |
| `group_and_thread_only` | 默认行为 `deny`；允许群聊和 thread |
| `deny_all` | 默认行为 `deny`；不额外创建允许规则 |

预设不会配置工作区成员，也不会创建账号绑定。

***

## 示例

### 公开 IM Bot，只拉黑少数人

在渠道成员中使用**黑名单模式**。默认保持聊天开启，只添加被拦截的身份。只有需要拦截整个平台或某个群/thread 上下文时，才使用高级规则。

### 私有 IM Bot

在渠道成员中使用**白名单模式**。添加允许的渠道身份，并保持聊天勾选。如果同一批人还需要通过 IM 管理 Bot，再授予管理权限。

### Web 团队 Bot

使用**工作区成员**。添加指定用户或全部成员，然后按 Web/工作区角色选择可对话、文件权限、命令执行和管理权限。

### 工作区管理员同时从 Telegram 管理

在工作区成员中给该用户授予**可管理**。让用户用 `/link <code>` 绑定 Telegram 账号。其 Telegram 身份会在渠道成员中继承管理权限。如果只想禁用该身份的 Telegram 侧管理能力，可在渠道成员中关闭管理权限，创建本地覆盖。

***

## 排查

访问结果不符合预期时，按顺序检查：

1. **涉及哪一层？** IM 消息走渠道聊天 ACL；客户端和工作区 API 走工作区成员。
2. **身份是否已绑定？** Connected Accounts 决定工作区管理权限能否继承到渠道成员。
3. **当前渠道访问模式是什么？** 黑名单模式默认允许；白名单模式默认拒绝。
4. **管理权限是继承还是覆盖？** 渠道成员的信息弹窗会显示管理权限是跟随工作区，还是已被本地覆盖。
5. **`/access` 显示什么？** 在 IM 中，`/access` 会展示当前身份、写权限和发送者的聊天 ACL 上下文。

请记住，管理和聊天是分开的。管理权限可以允许 owner 级别的 IM 命令，但普通入站聊天仍需要渠道聊天权限放行发送者。
