claude-code-router AgentClaw 钉钉接入实战从创建企业应用、Stream 模式到锁屏 Handoff【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router本篇指南讲解如何在 claude-code-router下文简称 CCR的 AgentClaw 中接入钉钉DingTalk在钉钉开发者后台创建应用、启用机器人与消息推送能力、选择 Stream 接收模式然后在 CCR 的 Bot Management 中以 App Secret 认证接线并把消息投递策略设为 Forward 或锁屏 Handoff。读完后你将掌握完整的字段映射、四步平台配置、CCR 侧接线步骤以及基于源码认证归一化与 WebSocket 传输机制的故障排查依据。适用对象与前提条件AgentClaw 的钉钉接入面向把 agent 消息带入企业协作环境的场景CCR 通过 App Secret 认证连接钉钉应用把受管 App 中 agent 的会话内容投递到钉钉单聊或群聊并支持锁屏后接管Handoff。在开始之前建议先确认 AgentClaw 总览与使用配置 中的前提条件已满足CCR Desktop 正在运行且 gateway 服务可用已在 Provider Config 中配置好可用模型或所需 Fusion 模型就绪存在一个Entry mode包含 App 的 Agent Profile当前 AgentClaw 接力支持 Claude App、Codex/ChatGPT App、OpenCode App、ZCode App、WorkBuddy App纯 CLI agent 不会转发 Bot 消息钉钉侧已准备好应用的凭据下文步骤 1–4 完成。字段映射钉钉后台字段与 CCR 字段CCR 的 Bot 表单与钉钉开发者后台的字段命名并不完全一致按下表映射钉钉后台字段CCR 字段是否必填说明Client ID / AppKeyApp Key必填应用标识Client Secret / AppSecretApp Secret必填应用密钥RobotCodeRobot Code可选多机器人或媒体场景可能需要在 CCR 源码中钉钉平台的凭据字段定义与上表一一对应appKey和appSecret标记为 requiredappSecret为 password 类型robotCode为可选字段见 钉钉平台凭据规格{ value: dingtalk, label: DingTalk, auth: [ { value: app_secret, label: App Secret, fields: [ { key: appKey, label: App Key, required: true }, { key: appSecret, label: App Secret, required: true, type: password }, { key: robotCode, label: Robot Code } ] } ] }新版钉钉将机器人配置为应用的应用能力——请从应用能力入口添加机器人不要从旧的独立机器人入口开始配置。步骤 1创建钉钉应用打开钉钉开发者后台钉钉开放平台开发者后台。使用钉钉账号登录。选择要连接的开发组织。打开顶部应用开发。点击创建应用。命名应用例如CCR。填写描述其余选项保持默认。点击创建。步骤 2获取 App Key 与 App Secret打开刚创建的应用。在左侧打开应用信息或凭证与基础信息。复制Client ID作为 CCR 的App Key。复制Client Secret作为 CCR 的App Secret。后台可能仍显示旧名称AppKey/AppSecret——按字段含义对应即可不要按字面名称填写。步骤 3启用机器人能力Stream 模式在应用内打开机器人与消息推送或打开应用能力并选择机器人。启用机器人配置。填写机器人名称、头像与描述。消息接收模式选择Stream 模式。保存。如果页面展示了RobotCode复制下来用于 CCR 的 Robot Code。选择 Stream 模式不只是操作习惯问题。CCR 在启动 Bot Gateway 时会为钉钉平台强制注入 WebSocket 传输参数见 传输归一化实现function websocketBotGatewayIntegrationConfig(platform: string, value: Recordstring, unknown): Recordstring, unknown { const config sanitizeBotGatewayRecord(value); delete config.transport; delete config.sendMode; const transport botGatewayWebSocketTransport(platform); return transport ? { ...config, transport } : config; } function botGatewayWebSocketTransport(platform: string): string { if (!platform || platform none) { return ; } return platform slack ? socket : websocket; }也就是说钉钉集成会以transport: websocket运行。同一份 凭据清洗逻辑 还会主动丢弃所有 webhook 相关的键webhook、sendMode等因此如果后台把接收模式设成了 HTTP 回调而 CCR 侧期望 Stream会出现机器人收不到任何消息的症状——这与后文故障排查条目对应。步骤 4发布应用并加入会话打开版本管理与发布创建新版本。设置可见范围——测试阶段建议只选自己或一个测试群。提交发布。发布后在钉钉客户端搜索机器人名称。打开机器人单聊或通过群设置把机器人添加到目标群。在 CCR 中接线打开 CCR 的Bot Management页面点击Add Bot。平台选择DingTalk。认证方式选择App Secret。把 Client ID 粘贴到App Key。把 Client Secret 粘贴到App Secret。如果复制到了 RobotCode粘贴到Robot Code。保存 Bot。打开Agent Profiles编辑要挂载该 Bot 的 Agent Profile。打开Bot开关并选择该 Bot。按需启用Forward agent messages或Handoff见下一节。从 CCR 重新打开该 agent。CCR 侧配置保存后运行时按应用级 botGateway 配置 ← 已保存的 Bot 配置 ← Profile 级 botGateway 配置的顺序合并见 配置合并逻辑。合并结果最终由 botGatewayProfileEnv 编译成环境变量交给 Bot Gateway 运行时其中与钉钉直接相关的几项CCR_BOT_GATEWAY_PLATFORM归一化后的平台名。源码中dingding是dingtalk的别名两者都会归一为dingtalk见 平台归一化CCR_BOT_GATEWAY_AUTH_TYPE钉钉的默认认证类型固定为app_secret见 默认认证类型。用户手填的appsecret这类写法也会被归一化为app_secretCCR_BOT_GATEWAY_CREDENTIALS_JSONApp Key / App Secret / Robot Code 的凭据包CCR_BOT_HANDOFF_ENABLED、CCR_BOT_HANDOFF_IDLE_SECONDS、CCR_BOT_HANDOFF_SCREEN_LOCKHandoff 相关开关默认值为空闲 30 秒、锁屏启用见 Handoff 默认值。单元测试印证了这条认证归一化路径见 bot-gateway-env 测试输入authType: appsecret后环境变量中CCR_BOT_GATEWAY_AUTH_TYPE为app_secret。Forward 还是 HandoffForward agent messages无论是否锁屏都转发。希望完整输出都出现在钉钉里时用它Handoff仅在锁屏后转发。需要配合 Idle seconds空闲秒数与目标设备使用。如果只想在锁屏后收到提示只启用Handoff不要同时启用Forward agent messages。从源码结构看Handoff 的触发条件围绕锁屏与用户空闲时间CCX_BOT_HANDOFF_SCREEN_LOCK与CCX_BOT_HANDOFF_USER_IDLE两个开关默认都是true空闲秒数默认 30 秒。Wi-Fi/蓝牙手机目标属于实验性设置扫描实现依赖arp -a局域网与blueutil/system_profilermacOS 蓝牙等本机命令见 handoff 目标扫描服务它们尚不影响运行时的 Handoff 判定。三种模式的完整对照表全量转发 / 锁屏 Handoff / 仅 IM 发起会话可在 AgentClaw 使用与配置 中查阅。验证接入从 CCR 打开 agent 并触发一条消息。在钉钉中确认应用已收到消息并回复。群聊场景下确认应用或机器人已在目标群内且有发言权限。判断成功的标准钉钉中出现了 agent 的消息且你在钉钉里的回复能让 agent 继续对话。建议按 AgentClaw 验证清单 再走一遍完整闭环从 IM 发送/project current确认 Bot 在线并能读取当前 Project、发送/session list确认会话列表、发送一条自然语言消息确认 agent 执行并回复、锁屏并等待 Handoff 空闲秒数后确认后续消息进入 IM、最后关闭受管 App 确认 Bot 变为离线。常见问题排查认证失败重新复制 App Key 和 App Secret。可对照源码确认认证类型归一化结果应为app_secret凭据以CCR_BOT_GATEWAY_CREDENTIALS_JSON形式注入运行时机器人标识报错核对 Robot Code 是否与钉钉后台展示的一致多机器人场景下 Robot Code 必填项往往就是这里出了问题机器人收不到任何消息确认应用内已启用机器人能力且接收模式是 Stream 模式——CCR 侧对钉钉固定使用 websocket 传输并主动丢弃 webhook 相关配置后台若配置为 HTTP 回调则消息不会进入 CCR用户找不到机器人检查应用是否已发布、可见范围是否包含当前用户或群成员Handoff 不触发确认电脑已锁屏并检查 Handoff 开关、空闲秒数与目标设备设置。参考文件本文档来源AgentClaw DingTalk setup钉钉凭据字段与认证方式规格profiles.tsBot Gateway 环境变量编译、平台/认证归一化与 WebSocket 传输env.tsHandoff 手机目标扫描实验性handoff-scan-service.ts认证与配置合并的单元测试bot-gateway-env.test.mjsAgentClaw 总配置与三种消息模式setup.md【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考