去年下半年，开沿接了一家做精密制造的中型客户的钉钉二开项目，目标是把他们的设备点检、工单流转、车间看板三件事都收进钉钉工作台。开发节奏很顺，前端两周、后端三周、测试一周就出了 demo。但等到准备让全员用的时候，事情卡住了：IT 负责人发现，自己根本不知道这个应用怎么"上"到员工手机上的工作台里——是发个二维码？是管理员一个个加？是上传到钉钉应用市场？前前后后折腾了一周，才把分发流程跑通。这一周的时间，本来可以多做两个看板。
钉钉企业内部应用上架，是一件"做过就不难、没做过就处处是坑"的事。它不像 App Store 那样有清晰的提交—审核—发布动线，钉钉把开发者后台、管理后台、应用市场、企业自己的工作台揉在一起，每个环节的术语都接近但不完全一样。这篇文章把开沿做过的十几个钉钉二开项目里的上架流程沉淀下来，从应用形态选择讲到分发授权，再讲到 AI Agent 怎么嵌进去，给做钉钉二开的工程师和 IT 负责人一份能照着做的清单。
一、钉钉应用先分清四种形态
很多团队动手前没分清自己要做的是哪一种应用，结果开发到一半发现选错了载体，要么权限不够、要么交互别扭。钉钉企业内部应用主要分四类，开发方式、上架路径、用户体验都不一样。
第一类是 H5 微应用。本质是一个跑在钉钉容器里的网页，用 JSAPI 调用钉钉能力（鉴权、扫码、地理位置等），开发门槛最低，前端工程师按普通 Web 项目做就行。绝大多数管理类工具、看板、表单都是 H5。第二类是钉钉小程序，类似微信小程序，用钉钉自己的 DSL，体验比 H5 更原生、启动更快，适合需要离线缓存、复杂交互、调用更多端能力的场景。第三类是 Native 应用，需要在钉钉客户端做深度集成，一般只有合作伙伴或大客户才会走，自研团队基本不碰。第四类是工作台卡片（也叫 IM 卡片、工作通知卡片），不是独立应用，但可以作为入口，把消息、待办、AI 提醒直接挂在 IM 里。
| 形态 | 开发门槛 | 启动速度 | 上架路径 | 典型场景 |
|---|---|---|---|---|
| H5 微应用 | 低 | 一般 | 开发者后台 + 工作台 | 后台管理、看板、AI 对话 |
| 钉钉小程序 | 中 | 快 | 开发者后台 + 工作台 | 现场工单、移动审批 |
| Native 应用 | 高 | 最快 | 合作伙伴通道 | 深度集成场景 |
| 工作台卡片 | 低 | 即时 | 消息接口直推 | 待办、提醒、Agent 触达 |
开沿的经验是：70% 以上的内部应用选 H5 就够了，剩下的看 IT 负责人是否要管 iOS/Android 一致体验，如果要才上小程序。Native 几乎不需要考虑。关于这些形态的能力边界和成本对比，可以参考钉钉应用市场深度玩法和钉钉版本对比。
二、上架前要先备齐的 5 件东西
很多工程师习惯先写代码后想合规，但钉钉上架的卡点恰恰是"代码外"的东西。开沿过往项目里，平均每个客户都会在这五项中漏 1-2 项，导致提交被驳回。
第一项是稳定的回调域名。钉钉要求所有线上应用的服务端入口必须是 HTTPS、固定域名、证书有效期不少于 30 天。临时用 ngrok 或者云函数默认地址都过不了。第二项是 HTTPS 证书。不能用自签证书，必须是 CA 颁发的，建议直接在云厂商买一年期的免费 DV 证书。第三项是鉴权方案。钉钉的免登流程涉及 corpid、agentid、ticket、code、access_token、jsapi_ticket 等多个概念，开发前要先把鉴权时序图画清楚，不然联调时排错成本极高。
第四项是应用图标。需要 256×256 的 PNG，透明背景，建议同时准备一个浅色版本和一个深色版本，未来钉钉适配深色模式时不至于返工。第五项是介绍文案。包括应用名称（4-10 个字）、一句话简介（20-40 字）、详细介绍（200-500 字），别等到提交那一刻才写，提前让产品或者业务方过一遍。
| 准备项 | 关键标准 | 容易踩的坑 |
|---|---|---|
| 回调域名 | HTTPS、固定、可达 | 用了内网或动态地址 |
| HTTPS 证书 | CA 颁发、有效期>30 天 | 自签或快过期 |
| 鉴权方案 | 时序图清晰 | 把 corpid 和 agentid 搞混 |
| 应用图标 | 256×256 PNG 透明 | 直接截屏凑数 |
| 介绍文案 | 名称简介详介齐全 | 临提交才写文案 |
三、6 步上架流程跑一遍
这是开沿团队做钉钉二开的标准动作，从零到工作台展示，正常节奏 3-5 个工作日能跑完，复杂项目（涉及多个权限申请）会拉长到 1-2 周。
第一步：注册应用。进入开发者后台（open-dev.dingtalk.com），选择"企业内部开发 → H5 微应用 / 小程序"，填名称、描述、图标，得到 AppKey 和 AppSecret，这两个值后端要存起来、不能泄露到前端。第二步：开发配置。在应用详情页配置回调域名、IP 白名单（如果有）、开发管理员、安全域名，前端 JSAPI 鉴权的域名列表要和实际部署域名一致。
第三步：内部测试。把应用先发布给开发者本人和 1-3 个测试账号，在钉钉客户端的工作台可见，跑通核心链路。这一步钉钉提供"开发版"的概念，不影响正式员工。第四步：权限申请。根据业务功能选择需要的 API 权限点，比如读通讯录、发工作通知、写审批数据，逐项申请。这一步是最容易拖时间的环节，钉钉对权限申请的合理性审核越来越严，需要在理由里写清楚业务必要性。
第五步：分发授权。在管理后台（admin.dingtalk.com）找到"工作台 → 自建应用"，把刚才在开发者后台发布的应用加进来，选择可见范围（全员/指定部门/指定人员/指定角色），保存即生效。第六步：工作台展示。员工的钉钉工作台会自动出现这个应用图标，点击进入即可使用。如果想置顶或者分组展示，管理员还能在工作台编辑里调整。
| 步骤 | 平台 | 关键动作 | 常见耗时 |
|---|---|---|---|
| 注册应用 | 开发者后台 | 拿 AppKey/Secret | 10 分钟 |
| 开发配置 | 开发者后台 | 配域名/白名单 | 30 分钟 |
| 内部测试 | 钉钉客户端 | 跑核心链路 | 0.5-1 天 |
| 权限申请 | 开发者后台 | 逐项申请 | 1-3 天 |
| 分发授权 | 管理后台 | 选可见范围 | 10 分钟 |
| 工作台展示 | 钉钉客户端 | 自动生效 | 即时 |
关于 API 权限和配额的细节，建议同步看一下钉钉 API 配额与限流策略，避免上线后才发现调用量被限。
四、企业内部上架 vs 应用市场上架的差异
很多人问"我做完了直接上钉钉应用市场不就行了？"两者完全是两件事。企业内部上架，应用只在自己公司可见，审核宽松、上架快、改动灵活；应用市场上架，是公开发售或免费分发给所有钉钉企业，审核严格、流程长、改版需要重新过审。
开沿的判断标准：如果应用强依赖客户自己的业务数据（CRM、ERP、生产数据），就只做企业内部上架，没必要上市场；如果是通用工具（如 AI 翻译助手、智能命名生成器、统一会议室预订），且团队愿意承担运维和客服，可以上应用市场触达更多企业。
| 维度 | 企业内部上架 | 应用市场上架 |
|---|---|---|
| 可见范围 | 仅本企业 | 所有钉钉企业 |
| 审核周期 | 当天到 3 天 | 1-4 周 |
| 审核严格度 | 中 | 高 |
| 改版迭代 | 自由 | 需重新过审 |
| 是否能收费 | 不涉及 | 支持订阅或一次性 |
| 适合场景 | 自研内部工具 | 通用产品化能力 |
要把应用做成市场产品级的，文档、客服、安全合规、SLA 一样都不能少，比单纯做内部工具的投入要多几倍。
五、上架被拒的 6 个常见原因
开沿统计了过去两年里碰到的被拒案例，集中在 6 种原因。如果上架前能一一自查，被拒概率能压到很低。
第一种是回调地址不通。提交时钉钉会自动探测一次，如果服务端没起、防火墙挡了钉钉出口 IP、HTTPS 证书过期，都会立刻被拒。第二种是权限申请理由模糊。比如申请《通讯录读取》只写"业务需要"，几乎一定被打回，要写清楚"用于在应用内显示提交人所属部门，便于审批人识别"。第三种是介绍文案与实际功能不符。文案说支持 AI 写报告，但实际只是个表单，钉钉审核员真的会点进去看。
第四种是图标不符合规范。包括尺寸不对、有白色背景边缘、图形过于复杂识别度低、与官方应用相似度过高。第五种是隐私合规缺失。如果应用涉及收集员工个人信息（手机号、位置、生物特征），必须有隐私政策链接，且页面可访问。第六种是出现敏感内容。包括但不限于政治敏感词、与钉钉竞品的对比攻击、夸大宣传。
| 被拒原因 | 自查方式 | 修复成本 |
|---|---|---|
| 回调地址不通 | curl 测试 + 钉钉出口 IP 白名单 | 低 |
| 权限理由模糊 | 让产品 review 一遍理由文本 | 低 |
| 文案与功能不符 | 自己点一遍是否一致 | 中 |
| 图标不规范 | 对照官方设计指南 | 低 |
| 隐私合规缺失 | 加隐私政策页面 | 中 |
| 出现敏感内容 | 全文搜敏感词清单 | 低 |
六、应用图标和文案的实操规范
工程师团队最容易忽略这一节，但工作台一字排开几十个应用图标，自研应用的识别度直接影响员工使用率。开沿做过 A/B 对比：图标和文案精修过的应用，前两周的活跃使用率比凑数版本高 30-50%。
图标层面，记三个口诀。第一，背景纯色不要渐变；第二，主图形居中且占图标 60-70% 面积；第三，单色或最多两色，与钉钉默认的蓝绿橙色系拉开距离。文案层面，名称别超过 8 个汉字，最好是动词 + 名词结构，比如"巡检上报""车间看板""客户雷达"，比"XX 系统 V2.0"这种命名要友好得多。
详细介绍部分，建议按"做什么 / 给谁用 / 怎么用 / 有什么效果"四段式来写。如果应用接入了 AI 能力，需要在介绍里明确标注，并说明使用的模型类型（如"基于通义千问"或"基于自研轻量模型"），这是钉钉应用市场近期收紧的合规点，企业内部上架也建议遵守。
七、嵌入 AI Agent 的实操路径
钉钉企业内部应用最近一年最大的变化，是从"业务系统的入口"变成"AI Agent 的载体"。开沿过去半年做的内部应用里，超过一半都嵌了 AI 对话或 Agent 调度的能力。这不只是加个 ChatGPT 风格的对话框，而是把 AI 当成应用的核心交互模式。
落地路径分三层。最浅的一层是把对话框塞进 H5 应用，调用 LLM API、流式返回、对接钉钉 SSO 拿用户身份，2-3 天能上线第一版。中间一层是把 Agent 接到工作台卡片和 IM 机器人上，让 AI 主动发提醒、追问、生成日报，用户不用打开应用就能完成轻量任务。最深的一层是 Agent 调度多个钉钉 API（通讯录、审批、文档、CRM），形成"会做事的数字员工"，需要做工具编排、记忆管理、权限隔离。
| 层次 | 技术栈 | 上线周期 | 适用场景 |
|---|---|---|---|
| 对话框嵌入 | LLM API + SSO | 2-3 天 | FAQ、写作助手 |
| IM 卡片触达 | 工作通知 + 机器人 | 1-2 周 | 主动提醒、日报 |
| Agent 多工具调度 | LLM + 钉钉开放平台 + RAG | 1-2 月 | 数字员工 |
具体的技术细节，可以延伸阅读AI Agent 落地路线图、AI Agent 架构模式、AI 记忆工具调用与 RAG、钉钉宜搭自定义开发、AI Agent 钉钉对接 CRM/ERP 的业务跟进。Agent 嵌入企业应用还涉及权限审计与数据安全，参考AI Agent 数据安全和AI Agent 权限审计。
八、自检清单：上架前的最后 10 分钟
把上面所有内容浓缩成一张可以在提交前过一遍的清单。如果团队人手不多，建议把这张清单贴在 wiki 里，每次发布前对照打勾。
- AppKey 和 AppSecret 是否只存在后端，没出现在前端代码或 git 历史
- 回调域名是否 HTTPS，证书有效期是否大于 30 天
- 安全域名列表是否覆盖所有实际访问的子域
- 申请的每一项 API 权限是否都有清晰的业务理由
- 应用图标是否 256×256 透明 PNG，与现有工作台风格协调
- 应用名称是否 4-10 字、动宾结构、识别度高
- 详细介绍是否按"做什么/给谁用/怎么用/效果"写完
- 如果有 AI 能力，是否标注模型来源和数据流向
- 是否有隐私政策页面，链接是否可访问
- 是否在测试号上跑完一遍完整链路（包括异常路径）
如果某一项打不了勾，宁可推迟提交也别硬上，钉钉的拒绝记录会进入应用历史，反复被拒会影响后续权限申请的通过率。
九、上线之后才是真的开始
把应用挂上工作台只是第一步。开沿的项目复盘里，上线后的前三个月才是决定应用生死的关键期。
第一周关注的是基础可用性：是否有 5xx 报错、登录成功率、首屏加载时间。第二到第四周关注使用渗透：每天有多少人打开、打开后的停留时长、核心功能的使用比例，渗透率低于 30% 就要回去看是入口太深还是功能不对。第二个月之后，关注的是迭代节奏：每周或每两周一个小版本，每月一个功能版本，保持应用"活着"的信号。
钉钉自建应用支持热更新（H5 直接改后端、小程序提交新版本），不需要走类似 App Store 那种漫长审核，团队的迭代成本远低于做 App。把这点用好，就能让自研应用的体验持续追平甚至超过买的标品。关于自建和外采的平衡，可以参考CRM 自建与外购决策、标品 20% 的缺口、低代码无法继续的决策点，逻辑是相通的。
做钉钉企业内部应用上架，技术从来不是最难的部分。难的是想清楚要做什么、做给谁、用什么形态、怎么持续运营。当 AI Agent 进一步进入企业应用的核心交互，IT 团队的角色也在变化——从"系统的搭建者"变成"数字员工的训练师"。把上架流程跑顺，是这条新角色路径上很基础也很重要的一步。开沿愿意把过去两年踩过的坑分享出来，希望每一个准备做钉钉二开的团队都能少走一周弯路。
