Claude Code Haha

中文

English

中文

English

主题

钉钉接入 ​

钉钉 Adapter 的接入教程。钉钉走 DingTalk Stream，不需要公网回调地址。

适用场景 ​

钉钉方案适合通过钉钉单聊远程驱动本机 Claude Code。当前实现只处理单聊消息，不处理群聊。

当前实现支持文本聊天、图片附件、项目选择、状态查看、停止生成、AI Card 流式输出，以及文本或卡片形式的权限审批。

实现入口：adapters/dingtalk/index.ts

1. 绑定钉钉机器人 ​

打开桌面端 设置 -> IM 接入 -> 钉钉。

推荐使用扫码绑定：

  1. 点击「扫码绑定」。
  2. 使用钉钉手机 App 扫码。
  3. 在钉钉里确认创建并授权机器人。
  4. 等待桌面端显示「钉钉机器人已绑定」。
  5. 点击保存，或确认当前配置已经写入本地。

授权成功后，桌面端会把 clientId 和 clientSecret 写入 ~/.claude/adapters.json 的 dingtalk 配置。发布版桌面端会重启 adapter sidecar，让新凭据立即生效。

钉钉机器人绑定和手动凭据配置

2. 手动填写凭据 ​

如果扫码不可用，也可以手动填写：

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

保存后 adapter 会用 DingTalk Stream 建立长连接。

3. 授权具体钉钉用户 ​

机器人绑定完成后，还需要让具体用户通过配对码授权：

  1. 在 设置 -> IM 接入 顶部的「配对管理」里点击「生成配对码」。
  2. 在钉钉机器人单聊里发送这枚 6 位配对码。
  3. 看到配对成功提示后，就可以开始聊天。

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

配对码有效期 60 分钟，一次性使用。配对用户会出现在「已配对用户」列表里，可以随时解绑。解绑后该用户需要重新发送新的配对码才能使用。

4. 选择项目并开始对话 ​

如果已经配置默认项目，发送任意消息会直接在该目录下创建或复用 Claude Code session。

如果没有配置默认项目，adapter 会返回最近项目列表。回复编号、项目名或绝对路径后，会新建会话并绑定到当前钉钉 chat。

后续消息会复用 ~/.claude/adapter-sessions.json 里的 chat 到 session 映射。发送 /new 可以重新选择项目并开启新会话。

支持的命令 ​

钉钉这里没有像飞书那样的机器人菜单配置流程；当前命令入口就是单聊输入框。配对成功后，bot 会提示发送 /help；用户也可以随时发送 /help 或 帮助 查看完整命令列表。

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

权限审批 ​

默认情况下，钉钉 adapter 会发送文本审批消息。回复：

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

如果配置了已发布的钉钉互动卡片模板 ID，adapter 会优先发送权限卡片，并通过 DingTalk Stream 的 /v1.0/card/instances/callback 接收按钮回调。卡片发送失败或不可见时，仍可使用文本命令审批。

返回消息的表现 ​

  • 使用 dingtalk-stream 接收机器人单聊消息。
  • 使用消息里的 sessionWebhook 回复 Markdown 文本。
  • 普通回复优先使用 AI Card 做流式输出。
  • 权限审批可以使用互动卡片；没有模板时自动回退文本命令。
  • 图片附件会下载后以内联图片形式进入模型输入。
  • 附件会走公共大小限制检查，超限时 adapter 会在钉钉里返回提示。

解绑 ​

有两种解绑：

  • 解绑钉钉机器人账号：在钉钉标签页点击「解绑机器人账号」，会清空 dingtalk.clientId、dingtalk.clientSecret、allowedUsers、pairedUsers 和权限卡片模板 ID。
  • 解绑某个用户：在「已配对用户」列表里点击对应钉钉用户右侧的「解绑」，只移除该用户的 pairedUsers 记录。

解绑机器人账号后需要重新扫码或手动填写凭据。解绑用户后，该用户需要重新发送新的配对码才能继续使用。

本地开发启动 ​

发布版桌面端会自动启动 adapter sidecar。只有本地开发或单独调试时才需要手动运行：

bash
cd adapters
bun install
bun run dingtalk

可选环境变量：

bash
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"

正常桌面端使用不需要手动设置这些环境变量，扫码绑定或手动填写会写入本地配置。

常见问题 ​

扫码成功后发消息仍提示未授权 ​

这是正常授权流程的一部分。扫码绑定只写入机器人凭据；具体钉钉用户还需要发送配对码，或被加入 Allowed Users。

扫码失败或一直等待确认 ​

重新点击「扫码绑定」生成新二维码。如果仍失败，可以手动填写 Client ID 和 Client Secret。

adapter 启动时报缺少 clientId / clientSecret ​

说明 DINGTALK_CLIENT_ID / DINGTALK_CLIENT_SECRET 和 ~/.claude/adapters.json 里的 dingtalk.clientId / dingtalk.clientSecret 都没有生效。先在桌面端钉钉标签页完成扫码绑定或手动填写凭据。

权限卡片没有出现 ​

优先检查：

  • 是否已经配置发布后的权限卡片模板 ID。
  • 模板是否支持 adapter 使用的回调路由。
  • 当前机器人是否已经发布新版本。

即使卡片不可见，也可以用 /allow <requestId>、/always <requestId>、/deny <requestId> 完成审批。

收不到回复 ​

优先检查：

  • 桌面端是否正在运行。
  • 钉钉标签页是否显示已绑定。
  • 当前用户是否已经配对或在 Allowed Users 中。
  • ~/.claude/adapters.json 是否能正常写入。
  • 本地开发时 ADAPTER_SERVER_URL 是否指向正在运行的 Desktop server WebSocket 地址。

会话没恢复 ​

检查 ~/.claude/adapter-sessions.json 是否能正常写入，以及 Desktop server 里的 session 是否仍存在。

源码入口 ​

  • adapters/dingtalk/index.ts
  • adapters/dingtalk/helpers.ts
  • adapters/dingtalk/ai-card.ts
  • adapters/dingtalk/permission-card.ts
  • adapters/dingtalk/media.ts
  • adapters/common/pairing.ts
  • adapters/common/session-store.ts
  • adapters/common/ws-bridge.ts
  • adapters/common/http-client.ts

Released under the MIT License.

Copyright 2026 Claude Code Haha Contributors