钉钉设置
AigenLabs Agent 可作为聊天机器人集成到钉钉（DingTalk），让你通过单聊或群聊与 AI 助手对话。机器人通过钉钉的 Stream Mode（流模式）连接——一种长连接 WebSocket，无需公网 URL 或 webhook 服务器——并通过钉钉的 session webhook API 以 markdown 格式回复消息。
在开始设置之前，先了解大多数人最关心的内容：AigenLabs 进入你的钉钉工作空间后的行为方式。
AigenLabs 的行为方式
| 场景 | 行为 |
|---|---|
| 单聊（1:1 对话） | AigenLabs 响应每条消息，无需 @提及，每个单聊有独立会话。 |
| 群聊 | AigenLabs 仅在被 @提及 时响应，未被提及则忽略消息。 |
| 多用户共享群聊 | 默认情况下，AigenLabs 在群内按用户隔离会话历史。同一群中的两个用户不共享同一对话记录，除非你明确禁用该功能。 |
钉钉中的会话模型
默认情况下：
- 每个单聊有独立会话
- 共享群聊中的每个用户在该群内有独立会话
通过 config.yaml 控制：
group_sessions_per_user: true
仅当你明确希望整个群共享一个对话时，才将其设为 false：
group_sessions_per_user: false
本指南将带你完成完整的设置流程——从创建钉钉机器人到发送第一条消息。
前置条件
安装所需的 Python 包：
pip install "aigenlabs-agent[dingtalk]"
或单独安装：
pip install dingtalk-stream httpx alibabacloud-dingtalk
dingtalk-stream— 钉钉官方 Stream Mode SDK（基于 WebSocket 的实时消息）httpx— 异步 HTTP 客户端，用于通过 session webhook 发送回复alibabacloud-dingtalk— 钉钉 OpenAPI SDK，用于 AI 卡片、emoji 反应和媒体下载
第一步：创建钉钉应用
- 前往钉钉开发者控制台。
- 使用钉钉管理员账号登录。
- 点击应用开发 → 自建应用 → 创建 H5 微应用（或根据控制台版本选择机器人）。
- 填写：
- 应用名称：例如
AigenLabs Agent - 描述：可选
- 应用名称：例如
- 创建完成后，进入凭证与基础信息，找到你的 Client ID（AppKey）和 Client Secret（AppSecret），复制两者。
Client Secret 仅在创建应用时显示一次。如果丢失，需要重新生成。切勿公开分享这些凭证或将其提交到 Git。
第二步：启用机器人能力
- 在应用设置页面，进入添加能力 → 机器人。
- 启用机器人能力。
- 在消息接收模式下，选择 Stream Mode（推荐——无需公网 URL）。
Stream Mode 是推荐的设置方式。它使用从你的机器发起的长连接 WebSocket，无需公网 IP、域名或 webhook 端点，可在 NAT、防火墙及本地机器后正常工作。
第三步：找到你的钉钉用户 ID
AigenLabs Agent 使用你的钉钉用户 ID 来控制谁可以与机器人交互。钉钉用户 ID 是由组织管理员设置的字母数字字符串。
查找方式：
- 询问你的钉钉组织管理员——用户 ID 在钉钉管理后台的通讯录 → 成员中配置。
- 或者，机器人会在日志中记录每条传入消息的
sender_id。启动 gateway，向机器人发送一条消息，然后在日志中查找你的 ID。
第四步：配置 AigenLabs Agent
方式 A：交互式设置（推荐）
运行引导式设置命令：
aigenlabs gateway setup
在提示时选择 DingTalk。设置向导支持两种授权路径：
- 二维码设备流（推荐）。 用钉钉手机 App 扫描终端中打印的二维码——Client ID 和 Client Secret 将自动返回并写入
~/.aigenlabs/.env，无需前往开发者控制台。 - 手动粘贴。 如果你已有凭证（或扫码不方便），在提示时粘贴你的 Client ID、Client Secret 和允许的用户 ID。
由于钉钉的 verification_uri_complete 在 API 层硬编码为 openClaw 身份，在 Alibaba / DingTalk-Real-AI 在服务端注册 AigenLabs 专属模板之前，二维码目前以 openClaw 来源字符串进行授权。这仅是钉钉呈现授权界面的方式——你创建的机器人完全属于你，且对你的租户私有。
方式 B：手动配置
在 ~/.aigenlabs/.env 文件中添加以下内容：
# 必填
DINGTALK_CLIENT_ID=your-app-key
DINGTALK_CLIENT_SECRET=your-app-secret
# 安全：限制可与机器人交互的用户
DINGTALK_ALLOWED_USERS=user-id-1
# 多个允许用户（逗号分隔）
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2
# 可选：群聊门控（与 Slack/Telegram/Discord/WhatsApp 保持一致）
# DINGTALK_REQUIRE_MENTION=true
# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DINGTALK_MENTION_PATTERNS=^小马
# DINGTALK_HOME_CHANNEL=cidXXXX==
# DINGTALK_ALLOW_ALL_USERS=true
~/.aigenlabs/config.yaml 中的可选行为设置：
group_sessions_per_user: true
gateway:
platforms:
dingtalk:
extra:
# 在群聊中要求 @提及 后机器人才回复（与 Slack/Telegram/Discord 保持一致）。
# 单聊忽略此设置——机器人始终在 1:1 对话中回复。
require_mention: true
# 平台级白名单。设置后，只有这些钉钉用户 ID 可与机器人交互
# （语义与 DINGTALK_ALLOWED_USERS 相同，但作用域在此处而非 .env）。
allowed_users:
- user-id-1
- user-id-2
group_sessions_per_user: true在共享群聊中保持每个参与者的上下文隔离require_mention: true防止机器人响应每条群消息——仅在有人 @提及 时才回答dingtalk.extra下的allowed_users是DINGTALK_ALLOWED_USERS的替代方式；若两者同时设置，则合并生效
启动 Gateway
配置完成后，启动钉钉 gateway：
aigenlabs gateway
机器人应在几秒内连接到钉钉的 Stream Mode。发送一条消息——单聊或已添加机器人的群聊均可——进行测试。
你可以在后台运行 aigenlabs gateway，或将其配置为 systemd 服务以持续运行。详见部署文档。
功能特性
AI 卡片
AigenLabs 可以使用钉钉 AI 卡片代替纯 markdown 消息进行回复。卡片提供更丰富、更结构化的展示，并支持在 agent 生成响应时进行流式更新。
要启用 AI 卡片，在 config.yaml 中配置卡片模板 ID：
platforms:
dingtalk:
enabled: true
extra:
card_template_id: "your-card-template-id"
你可以在钉钉开发者控制台的应用 AI 卡片设置中找到卡片模板 ID。启用 AI 卡片后，所有回复均以带流式文本更新的卡片形式发送。
Emoji 反应
AigenLabs 会自动在你的消息上添加 emoji 反应以显示处理状态：
- 🤔Thinking — 机器人开始处理你的消息时添加
- 🥳Done — 响应完成时添加（替换 Thinking 反应）
这些反应在单聊和群聊中均有效。
显示设置
你可以独立于其他平台自定义钉钉的显示行为：
display:
platforms:
dingtalk:
show_reasoning: false # 在回复中显示模型推理/思考过程
streaming: true # 启用流式响应（与 AI 卡片配合使用）
tool_progress: all # 显示工具执行进度（all/new/off）
interim_assistant_messages: true # 显示中间注释消息
若要禁用工具进度和中间消息以获得更简洁的体验：
display:
platforms:
dingtalk:
tool_progress: off
interim_assistant_messages: false
故障排查
机器人不响应消息
原因：机器人能力未启用，或 DINGTALK_ALLOWED_USERS 中不包含你的用户 ID。
解决方法：确认应用设置中已启用机器人能力且已选择 Stream Mode。检查你的用户 ID 是否在 DINGTALK_ALLOWED_USERS 中。重启 gateway。
"dingtalk-stream not installed" 错误
原因：Python 包 dingtalk-stream 未安装。
解决方法：安装它：
pip install dingtalk-stream httpx
"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"
原因：凭证未在环境变量或 .env 文件中设置。
解决方法：确认 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET 已在 ~/.aigenlabs/.env 中正确设置。Client ID 是你的 AppKey，Client Secret 是钉钉开发者控制台中的 AppSecret。
Stream 断开 / 重连循环
原因：网络不稳定、钉钉平台维护或凭证问题。
解决方法：适配器会以指数退避（2s → 5s → 10s → 30s → 60s）自动重连。检查凭证是否有效，以及应用是否未被停用。确认你的网络允许出站 WebSocket 连接。
机器人离线
原因：AigenLabs gateway 未运行，或连接失败。
解决方法：检查 aigenlabs gateway 是否正在运行。查看终端输出中的错误信息。常见问题：凭证错误、应用被停用、dingtalk-stream 或 httpx 未安装。
"No session_webhook available"
原因：机器人尝试回复但没有 session webhook URL。通常发生在 webhook 过期或机器人在收到消息和发送回复之间重启的情况下。
解决方法：向机器人发送一条新消息——每条传入消息都会提供一个新的 session webhook 用于回复。这是钉钉的正常限制；机器人只能回复最近收到的消息。
安全
务必设置 DINGTALK_ALLOWED_USERS 以限制可与机器人交互的用户。若未设置，gateway 默认拒绝所有用户作为安全措施。只添加你信任的人的用户 ID——已授权用户对 agent 的全部能力拥有完整访问权限，包括工具使用和系统访问。
有关保护 AigenLabs Agent 部署的更多信息，请参阅安全指南。
注意事项
- Stream Mode：无需公网 URL、域名或 webhook 服务器。连接由你的机器通过 WebSocket 发起，可在 NAT 和防火墙后正常工作。
- AI 卡片：可选择使用富文本 AI 卡片代替纯 markdown 回复。通过
card_template_id配置。 - Emoji 反应：自动添加 🤔Thinking/🥳Done 反应以显示处理状态。
- Markdown 响应：回复以钉钉 markdown 格式呈现，支持富文本展示。
- 媒体支持：传入消息中的图片和文件会自动解析，可由视觉工具处理。
- 消息去重：适配器在 5 分钟窗口内对消息进行去重，防止同一消息被处理两次。
- 自动重连：若 stream 连接断开，适配器会以指数退避自动重连。
- 消息长度限制：每条消息的响应上限为 20,000 个字符，超出部分将被截断。