# 企业微信智能机器人 DM 排障指南

## 现象：用户私聊机器人提示「仅创建者可使用」

### 第一步：确认错误来源

**Hermes 侧快速自检**：查日志有没有 `Unauthorized user` 或 `DM sender ... blocked by policy`

```bash
grep -i "Unauthorized\|blocked by policy" ~/.hermes/logs/gateway.log | tail -5
```

- **有记录** → Hermes 授权层拦了，检查 `WECOM_ALLOW_ALL_USERS` 和 Pairing 状态
- **无记录** → 消息从未到达 Hermes，问题在企微平台层

> 当 `WECOM_ALLOW_ALL_USERS=true` + `dm_policy: open` 时，Hermes 侧不会拦截任何人。绝大部分「仅创建者可使用」都是企微平台层拦截。

### 第二步：确认机器人创建者身份

| 创建者类型 | 非创建者能否看到机器人 | 如何让其他人私聊 |
|-----------|:---:|---|
| **管理员（超级管理员/分级管理员）** | ✅ 可见范围内的成员可在 通讯录→智能机器人 中看到 | 调整「可见范围」即可 |
| **普通成员** | ❌ 无法在通讯录/工作台中看到 | **创建者必须「推荐给联系人」** |

官方文档原文：
> 成员创建的机器人，「可使用的成员」范围内的其他普通成员，无法在【通讯录 -> 智能机器人】【客户端 -> 工作台 -> 智能机器人】中查看该机器人。

### 第三步（成员创建的机器人）：推荐给联系人

创建者操作：
1. 工作台 → 智能机器人 → 点击机器人 → 详情
2. 点击「去使用」旁边的 **「…」**
3. 选择 **「推荐给联系人」** → 选择目标用户
4. 用户收到推荐后即可私聊

其他方式（效果相同）：
- **扫码使用**：生成二维码，用户扫码后可使用
- **机器人链接**：复制固定链接发给用户
- **添加到群聊**：把机器人加到群里，群成员可 @ 使用

### 第四步（管理员创建的机器人）：检查可见范围

管理员创建的机器人：
- 协作 → 智能机器人 → 点机器人 → 右上角「…」→ 可见范围 → 改为「所有成员」或添加指定部门/成员
- 自建应用：应用管理 → 机器人 → 编辑 → 可见范围 → 调整

### OpenClaw MCP 限制（仅作澄清，与 Hermes 无关）

OpenClaw 文档提到：授权了「个人/小团队接口能力」（收发消息、文档、日程、会议等）的机器人会被企微强制限制为「仅创建者可对话」。这是 **OpenClaw MCP 集成的平台安全策略**，因为 MCP 授权后机器人可以操作用户敏感数据。

**Hermes 通过 WebSocket 长连接直接接入，不经过 OpenClaw/MCP 层，不受此限制。** 排查 Hermes 私聊问题时跳过这个方向。

### 长连接模式私聊支持

企微官方开发文档（path/101463）明确列出：
- `chattype: single` 单聊消息回调
- `enter_chat` 进入单聊会话事件
- 图片/语音/文件/视频消息「仅支持单聊」
- 主动推送：`chat_type: 1`（单聊）+ `chatid` = userid

**长连接模式完全支持私聊，无需切换到 URL 回调模式。**

### Hermes DM 授权优先级

`gateway/run.py` `_is_user_authorized()` 检查顺序：

1. Per-platform allow_all (`WECOM_ALLOW_ALL_USERS=true`) → ✅ 直接放行
2. Bot bypass（特定平台）
3. Pairing 已审批用户 → ✅ 放行
4. Per-platform allowlist → 名单内放行
5. Global allow_all (`GATEWAY_ALLOW_ALL_USERS=true`)
6. 默认拒绝 → 触发配对码流程

**只要第 1 步通过（设了 `WECOM_ALLOW_ALL_USERS=true`），后续都不会执行。**