Skip to content

dingtalk.md

Latest commit

 

History

History
122 lines (78 loc) · 5.82 KB

dingtalk.md

File metadata and controls

122 lines (78 loc) · 5.82 KB
Raw
title 钉钉接入
nav_title 钉钉
description 用钉钉扫码授权机器人，走 DingTalk Stream 长连接，不需要公网回调地址。
order 4

钉钉接入

适合把钉钉当主力办公工具的国内团队：扫一次码就能授权出一个机器人，走 DingTalk Stream 长连接，不需要公网回调地址和内网穿透。回复默认用 AI Card 流式输出。限制是只处理单聊，不处理群聊；想要可点的权限卡片还得额外配一个模板 ID，否则只能回复文本命令。

扫码绑定机器人

  1. 打开「设置」→「IM 接入」，切到「钉钉」Tab。
  2. 在「扫码绑定钉钉机器人」里点「扫码绑定」。
  3. 用钉钉手机 App 扫码，并在钉钉里确认创建和授权。
  4. 等页面显示「钉钉机器人已绑定」。

扫码绑定与手动填写凭据

授权成功后 Client ID 和 Client Secret 会自动填好并写入本机配置，adapter 随即用新凭据重连。

手动填写凭据

扫码走不通时，也可以自己填。这几个字段就在扫码区域下面：

  • Client ID — 钉钉应用的 appKey
  • Client Secret — 钉钉应用的 appSecret
  • Stream Endpoint — 可选，默认 https://api.dingtalk.com
  • 权限卡片模板 ID — 可选，填了之后权限请求优先发钉钉互动卡片
  • 允许的用户 — 可选，直接放行指定的钉钉用户 ID

填完点「保存」，adapter 会用新凭据重新建立 Stream 长连接。

授权具体用户

机器人绑定完成后，还要让具体的人通过配对码获得授权。

  1. 回到页面顶部的「配对管理」，点「生成配对码」。
  2. 在钉钉里私聊机器人，把这枚 6 位码发过去。
  3. 看到配对成功提示后就能开始聊。

在钉钉里发送配对码并开始对话

配对码 60 分钟内有效、只能用一次。配对成功的人会出现在「已配对用户」列表里，随时可以解绑；被解绑的人要重新发一枚新码。

选项目并开始对话

配了「默认项目」的话，第一条消息就直接在那个目录下开会话。没配的话，机器人会先列出最近用过的项目，回复编号、项目名或绝对路径即可。

之后同一个聊天窗口的消息会复用同一条会话。发 /new 重新选项目，发 /clear 清空上下文但保留项目绑定。

支持的命令

钉钉没有像飞书那样的机器人菜单，命令入口就是单聊输入框。配对成功后机器人会提示发 /help。

  • /help 或 帮助 — 显示可用命令
  • /status 或 状态 — 当前项目、分支、模型、运行状态和任务摘要
  • /projects 或 项目列表 — 重新列出最近项目
  • /new 或 新会话 — 清空当前绑定并重新选择项目
  • /new <编号、项目名或绝对路径> — 直接在指定项目下开新会话
  • /clear 或 清空 — 清空上下文，保留项目绑定
  • /stop 或 停止 — 停止本轮生成

权限审批与消息表现

默认情况下，权限请求以文本消息发出，回复其中一条：

  • /allow <requestId> — 允许这一次
  • /always <requestId> — 永久允许同类请求
  • /deny <requestId> — 拒绝

如果在设置页填了已发布的「权限卡片模板 ID」，adapter 会优先发互动卡片，按钮回调走 DingTalk Stream 回传。卡片发不出去或看不见时，文本命令始终可用。

普通回复优先用 AI Card 做流式输出，图片附件会下载后以内联图片进入模型输入，附件超出大小限制时机器人会在钉钉里提示。

解除绑定

两种粒度：

  • 「解除机器人绑定」清掉钉钉凭据、权限卡片模板 ID 和这个平台的授权名单，之后要重新扫码或手动填凭据。
  • 在「已配对用户」列表里点某个用户右侧的「解绑」，只撤销那一个人。

本地开发启动

发布版桌面端会自动把 adapter 作为 sidecar 拉起。只有从源码运行或单独调试时才需要手动启动：

cd adapters
bun install
bun run dingtalk

可选的环境变量覆盖：

export DINGTALK_CLIENT_ID="..."
export DINGTALK_CLIENT_SECRET="..."
export DINGTALK_STREAM_ENDPOINT="https://api.dingtalk.com"
export DINGTALK_PERMISSION_CARD_TEMPLATE_ID="..."
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"

正常使用桌面端不需要手动设置这些，扫码绑定或手动填写会写好本机配置。

常见问题

扫码成功后发消息仍提示未授权：这是正常流程。扫码只写入机器人凭据，具体用户还要发配对码，或被写进「允许的用户」。

扫码失败或一直等待确认：重新点「扫码绑定」生成新二维码；仍然不行就手动填 Client ID 和 Client Secret。

adapter 启动时报缺少 clientId/clientSecret：环境变量和 ~/.claude/adapters.json 里的 dingtalk.clientId/dingtalk.clientSecret 都没生效，先在设置页完成扫码或手动填写。

权限卡片没出现：确认模板 ID 填的是已发布的模板、模板支持 adapter 用的回调路由、机器人已发布新版本。卡片不可见时用 /allow、/always、/deny 照样能批。

收不到回复：依次确认桌面端在运行、Tab 里显示已绑定、当前用户已配对或在「允许的用户」里、~/.claude/adapters.json 能正常写入；源码运行时还要确认 ADAPTER_SERVER_URL 指向正在跑的桌面服务。

重启后会话没接回来：检查 ~/.claude/adapter-sessions.json 能否正常写入，以及桌面端里那条会话是否还在。

源码入口

adapters/dingtalk/ 下的 index.ts、helpers.ts、ai-card.ts、permission-card.ts、media.ts，以及 adapters/common/ 下的 pairing.ts、session-store.ts、ws-bridge.ts、http-client.ts。