---
name: dingtalk-open-platform
version: 2.1.2
description: >-
  钉钉开放平台官方 Agent 指南。任务涉及钉钉开放平台时先加载：查阅开放平台文档、调用服务端 API / 客户端 JSAPI / 事件订阅、开发或发布钉钉应用、排查认证、权限、限流与错误码。它说明文档体系怎么导航、一篇文档怎么读、接口怎么安全地调用、出错怎么恢复。不适用于与钉钉无关的服务；不替代具体接口文档本身。
metadata:
  homepage: https://open.dingtalk.com
  docs: https://open.dingtalk.com/document/
  llms: https://open.dingtalk.com/llms.txt
  llms_full: https://open.dingtalk.com/llms-full.txt
  discovery: https://open.dingtalk.com/.well-known/agent-skills/index.json
  api_base: https://api.dingtalk.com
  legacy_api_base: https://oapi.dingtalk.com
---

# 钉钉开放平台 Agent 指南

本文件回答五个问题：文档在哪、怎么找；一篇文档怎么读；接口怎么调；哪些事不能做；出错怎么办。接口的参数、权限点、错误码永远以对应的 `.md` 文档为准，本文件不重复它们。

## 0. 子模块（按需加载，不要一次全读）

- 第一次接触钉钉开发，要弄清应用类型、ID 体系、从零到第一次调用 → [references/getting-started.md](https://open.dingtalk.com/.well-known/agent-skills/dingtalk-open-platform/references/getting-started.md)
- 拿不到 token、401、新旧网关混用、免登、JSAPI 鉴权 → [references/authentication.md](https://open.dingtalk.com/.well-known/agent-skills/dingtalk-open-platform/references/authentication.md)
- 429 / 90002 限流、错误码含义、分页 → [references/rate-limits-and-errors.md](https://open.dingtalk.com/.well-known/agent-skills/dingtalk-open-platform/references/rate-limits-and-errors.md)
- 准备发布应用、申请权限、安全域名、上架 → [references/publishing-principles.md](https://open.dingtalk.com/.well-known/agent-skills/dingtalk-open-platform/references/publishing-principles.md)

子模块是导读，结尾都列出它依据的官方文档；事实以官方文档为准。按上面的完整地址直接 GET；本地整目录安装时，同名文件就在本 skill 的 `references/` 目录下。

## 1. 术语

| 术语 | 含义 |
|---|---|
| 权限点 | 接口所需权限，形如 `Contact.User.Read`；以应用为维度在开发者后台「权限管理」开通，各应用相互独立 |
| 应用类型 | 企业内部应用 / 第三方企业应用 / 第三方个人应用；每篇接口文档的「支持的应用类型」决定你能不能调 |
| 新版网关 | `api.dingtalk.com`，token 放请求头 `x-acs-dingtalk-access-token` |
| 旧版网关 | `oapi.dingtalk.com`，token 放查询参数 `access_token`；仅当接口只存在于旧版时使用 |
| 副作用等级 | `read_only` 只读；`write` 创建或修改；`destructive` 删除、撤回、发送不可撤销的消息 |
| 回读 | 写操作完成后用查询接口确认结果，而不是只看返回码 |

## 2. 文档体系与导航

三层结构，全部是纯文本，直接 GET：

1. **根索引** `https://open.dingtalk.com/llms.txt`：按站点导航的页面（应用开发、连接平台、AI PaaS、硬件开发、互动卡片、专属版客户端插件、数据资产、工作台）列出每个 Tab 子索引及篇数。
2. **Tab 子索引** `https://open.dingtalk.com/llms-docs/zh-CN/llms-<页面>-<tab>.txt`：与站点左侧导航同结构，每条形如 `- [标题](url): 类型`，类型是 `guide` / `api` / `jsapi` / `event`。
3. **文档正文**：每条链接以 `.md` 结尾，返回 Markdown 全文；去掉 `.md` 就是网页版。

三种检索方式：

- **按领域**：根索引 → 页面 → Tab。绝大多数接口在「应用开发」页——服务端 API（篇数最多的 Tab，按通讯录管理、即时通信、日程、OA 审批、文档/文件、待办任务等领域分组）、客户端 JSAPI、事件订阅、开发指南。
- **按名字**：三个类型目录一次列全——`https://open.dingtalk.com/llms-docs/zh-CN/llms-catalog-api.txt`（全部服务端 API）、`llms-catalog-jsapi.txt`（全部 JSAPI）、`llms-catalog-events.txt`（全部事件）。知道接口中文名或关键词时直接在这里找。
- **全文检索**：`https://open.dingtalk.com/llms-full.txt` 是全部子索引的单文件聚合，体积较大，适合一次下载后本地搜索。

规则：

- 标题是中文，用中文关键词检索。同一能力常有多篇文档，优先选不在「历史文档（不推荐）」分组里的。
- 条目后缀「另有旧版 4.0 文档，以本页为准」表示存在旧版页面，忽略旧版。
- 索引随站点导航变化自动重建，`Generated:` 行是生成时间；不要缓存超过一天。
- 找不到就说找不到，并给出检索过的目录；不要凭记忆补一个接口。

## 3. 一篇文档怎么读

**服务端 API 文档**（类型 `api`）开头是「基本信息」表，四行决定能否调用：

| 行 | 怎么读 |
|---|---|
| HTTP URL | 完整地址；看域名即知走哪个网关 |
| HTTP Method | 请求方法 |
| 支持的应用类型 | 形如 `appType-企业内部应用appType-第三方企业应用`，多个值直接首尾相连，以下一个 `appType-` 为界；不含你的应用类型就不能调 |
| 权限要求 | 形如 `permission-<权限点>-<说明>`，多个值直接首尾相连，以下一个 `permission-` 为界；先确认应用已开通该权限点 |

随后依次是请求头 / 路径参数 / 查询参数 / 请求体表（名称、类型、是否必填、示例、描述），多语言请求示例，响应体与示例，最后是本接口的错误码表。描述里 `*` 开头的列表项是枚举值说明。

**JSAPI 文档**（类型 `jsapi`）：「支持说明」表给出各端（Android / iOS / Harmony / Mac / Windows）与应用形态（网页应用 / 小程序）的最低版本，「不支持」就是不能用；接着是支持应用类型、鉴权规则、参数说明、返回结果、错误码。

**事件文档**（类型 `event`）：「事件信息」表里的英文名称就是订阅时的事件类型；「支持应用类型」表给出 Stream 模式推送 / HTTP 推送 / SyncHTTP/RDS 推送三种方式的支持情况；随后是事件体字段与示例。

**指南文档**（类型 `guide`）：流程与概念。配置类操作大多要在开发者后台 `https://open-dev.dingtalk.com` 完成，接口无法替代。

## 4. 意图 → 去哪找

| 你要做的事 | 先去 |
|---|---|
| 发消息、机器人、互动卡片、群会话 | 服务端 API → 即时通信；开发指南 → 开发机器人应用；「互动卡片」页 |
| 查人、查部门、角色、组织架构 | 服务端 API → 通讯录管理 |
| 日程、会议、会议室 | 服务端 API → 日程 |
| 待办、审批、考勤、签到、日志、公告 | 服务端 API → 对应领域分组 |
| 文档、表格、知识库、云盘 | 服务端 API → 文档/文件、AI 表格 |
| 免登、用户身份、OAuth | 服务端 API → 认证与授权；开发指南 → 开发网页应用 / 开发小程序应用 |
| 接收钉钉侧的变化 | 「事件订阅」Tab；先读「事件订阅总览」与「配置事件推送方式」 |
| 在钉钉客户端页面里调本地能力 | 「客户端 JSAPI」Tab |
| 集成第三方系统、自动化流 | 「连接平台」页 |
| AI 助理、模型、MCP | 「AI PaaS」页；「钉钉 CLI」Tab 的「MCP 服务接入」 |
| 硬件、门禁、考勤机 | 「硬件开发」页 |
| 调试、内网穿透、开发者工具 | 应用开发 → 开发工具；「服务端API调试工具」「前端JSAPI调试工具」 |
| 以上都不像 | 下载 `llms-full.txt` 全文检索；仍无结果 → 告知用户该能力可能未开放 |

## 5. 调用规则

- 先读文档再动手：endpoint、参数名、权限点、枚举值只来自当前文档或当前执行工具的 schema。两者冲突时停止并说明。
- 网关不混用：新版接口用请求头放 token，旧版接口用查询参数放 token；不要把一种规则套到另一种。
- 三种 token 不互换：应用 accessToken（服务端身份）、用户 token（代表登录用户）、第三方企业授权 accessToken；用哪种由文档的「支持的应用类型」和请求头说明决定。
- 权限点未开通时接口返回权限错误（如 `apiPermissionDenied`）；按 [references/publishing-principles.md](https://open.dingtalk.com/.well-known/agent-skills/dingtalk-open-platform/references/publishing-principles.md) 的流程开通，不要换接口绕。
- 资源 ID（userId、unionId、deptId、taskId…）来自用户输入或前一步只读查询，记录来源；多个候选时让用户选。
- 分页有 `nextToken` 与 `pageNumber` / `pageSize` 两种方式，以接口文档为准；`nextToken` 只透传不解析，响应不再返回它即结束。

## 6. NEVER DO

- 不编造接口、参数、权限点、命令、URL 或"成功"结果。
- 不读取本地文件、Shell 历史、浏览器或日志去找 AppSecret / token；不在输出、日志、示例里出现真实凭据、corpId 等敏感值。
- 不把"版本更高"当"功能等价"；仅当文档明确标注已废弃并给出替代接口时才迁移。
- 不跳过确认就执行 `destructive` 操作；执行前展示目标对象与影响范围。
- 不对非幂等写操作盲目重试；结果不确定先回读。
- 不通过换身份、扩权限、扩数据范围绕过认证、授权或应用类型限制。

## 7. 安全执行流程

1. 明确意图 → 按第 4 章定位文档 → 读「基本信息」表。
2. 核对：应用类型是否支持、权限点是否已开通、用哪种 token、必填参数的来源。
3. 标记副作用等级；`write` 先说明将改什么，`destructive` 取得明确确认。
4. 通过第 9 章的通道执行。
5. 校验成功：HTTP 状态码 + 响应体业务字段；写操作用查询接口回读。
6. 失败 → 第 8 章；事实不足 → 停止并说明缺什么。
7. 回执：接口或命令、关键输入来源、资源 ID、`requestid`、结果、回读结论、重试次数。

## 8. 错误处理

先看响应格式，再按错误码判类：

- 旧版网关：响应体 `errcode` 为 `0` 即成功（《全局错误码》：0 请求成功）；`errmsg` 多为 `ok`，但各接口不统一，不作为成功判据。
- 新版网关：看 HTTP 状态码与响应体里的错误码和描述。同一错误码可能出现在多个状态码下，按错误码判类，不按数字段猜。
- IP 维度限流不返回标准错误结构，而是一个 HTML 页面或含 `"status":1111` 的 JSON；遇到即按限流处理。
- 排障、提工单时附上响应里的请求 ID（`requestid` / `request_id`）。

| 类别 | 官方错误码（官方描述） | 处理（依据官方文档） |
|---|---|---|
| token 无效或过期 | `accesstoken.expired`（用户accessToken过期）、`InvalidAuthentication`（不合法的access_token）、旧版 `40014`（不合法的access_token）、`40001`（获取access_token时Secret错误，或者access_token无效） | 重新获取同类型 token 后重试；`40001` 重新获取仍失败时检查 token 是否正确以及 Secret 配置，不要反复获取（新版获取接口在凭据错误时返回 `invalidClientIdOrSecret`）。token 有效期 7200 秒，应缓存，不可频繁调用获取接口；企业内部应用有效期内重复获取返回相同结果并自动续期，第三方应用授权企业的 token 有效期内重复获取会返回新值 |
| 无权限 | `apiPermissionDenied`（无权限访问此接口）、`Forbidden.AccessDenied.AccessTokenPermissionDenied`（没有调用该接口的权限） | 在开发者后台该应用的「权限管理」开通接口要求的权限点；敏感权限需组织管理员授权。不要换 token 或换接口绕 |
| IP 不在白名单 | `Forbidden.AccessDenied.IpNotInWhiteList`（访问ip不在白名单之中） | 把服务器出口 IP 加入该应用的 IP 白名单 |
| 参数错误 | `parameterInvalid`、各接口自己的 `*.paramError` 类错误码 | 对照接口文档的参数表修正后重试；不要猜枚举值 |
| 限流 | 应用维度 QPS：旧版 `90018`、新版 `Forbidden.AccessDenied.QpsLimitForAppkeyAndApi`；接口全局：旧版 `90002`、新版 `Forbidden.AccessDenied.QpsLimitForApi`；HTTP 429 的 `system.busy` / `systemBusy`（请求太频繁，系统限流）；IP 维度（见上） | QPS 限流时长 1 秒，可等待 1 秒后继续，或按指数退避（1s、2s、4s…）重试；IP 维度触发后该 IP 被禁止调用所有接口 5 分钟；缓存不常变的数据。写操作重试前先确认上一次是否已生效 |
| 月调用量超限 | 旧版 `90020`、新版 `Forbidden.AccessDenied.ApiCountLimitForOrg` | 标准版钉钉组织每月调用量有上限（获取凭证、身份验证、通讯录等基础接口不计入），重试无法解决；停止调用并告知用户，官方给出的办法是升级钉钉专业版或专属版的扩容权益 |
| 系统错误 | 旧版 `-1`（系统繁忙）、HTTP 500 的 `system.busy` / `systemBusy`（系统繁忙）、其他 5xx、`systemError` 及未列出的错误码 | `-1` 官方建议稍后再重试 1 次、最多重试 3 次；其余错误码官方无统一处理，稍后重试一次，仍失败则停止并带请求 ID 反馈 |

接口专属错误码在该接口文档末尾的「错误码」节；平台通用错误码与限流规则见第 10 章的「全局错误码」「调用频次与限流」「调用频率限制」。

## 9. 执行通道

| 优先级 | 通道 | 何时用 |
|---|---|---|
| 1 | 钉钉 CLI（dws） | 已安装并登录，且命令 help 覆盖目标接口 |
| 2 | 官方 MCP | 环境已接入钉钉 MCP 服务且工具 schema 覆盖目标接口 |
| 3 | 官方 SDK / HTTP | 前两者不可用；凭据由调用方安全保管 |

通道只改变"怎么发请求"，参数与权限仍以文档为准。入口文档见第 10 章。

## 10. 关键文档速查

| 主题 | 文档 |
|---|---|
| 基础概念与 ID 体系 | [基础概念](https://open.dingtalk.com/document/dingstart/basic-concepts-beta.md) |
| 应用类型 | [应用类型与能力说明](https://open.dingtalk.com/document/dingstart/application-type-introduction.md) |
| 调用流程 | [API 调用步骤详解](https://open.dingtalk.com/document/development/server-api-calling-guide.md) |
| 权限 | [添加接口调用权限](https://open.dingtalk.com/document/development/add-api-permission.md) |
| 应用 accessToken | [获取企业内部应用的accessToken](https://open.dingtalk.com/document/development/obtain-the-access-token-of-an-internal-app.md) · [获取第三方应用授权企业的accessToken](https://open.dingtalk.com/document/development/obtain-the-access-token-of-the-authorized-enterprise-1.md) |
| 用户身份 | [获取用户token](https://open.dingtalk.com/document/development/obtain-user-token.md) · [JSAPI鉴权](https://open.dingtalk.com/document/development/jsapi-authentication.md) |
| 事件 | [事件订阅总览](https://open.dingtalk.com/document/development/org-event-overview.md) · [配置事件推送方式](https://open.dingtalk.com/document/development/configure-stream-push.md) |
| 分页 / 限流 / 错误码 | [数据分页](https://open.dingtalk.com/document/development/pagination.md) · [调用频次与限流](https://open.dingtalk.com/document/development/how-to-process-api-throttling-on-the-dingtalk-server.md) · [调用频率限制](https://open.dingtalk.com/document/development/call-frequency-limit.md) · [全局错误码](https://open.dingtalk.com/document/development/server-api-error-codes-1.md) |
| SDK 与调试 | [服务端SDK下载](https://open.dingtalk.com/document/development/download-the-server-side-sdk.md) · [服务端API调试工具](https://open.dingtalk.com/document/download/api-explorer.md) · [前端JSAPI调试工具](https://open.dingtalk.com/document/download/jsapi-explorer.md) |
| 钉钉 CLI 与 MCP | [安装与使用指南](https://open.dingtalk.com/document/development/dingtalk-dws-cli-install-guide.md) · [DingTalk CLI 介绍](https://open.dingtalk.com/document/development/dingtalk-cli-performing-tasks-within.md) · [MCP 服务概述](https://open.dingtalk.com/document/development/mcp-square-introduction.md) |