### [钉钉CLI工具](https://hello123.com/) **Published:** 2026-07-09T10:36:00 **Author:** hello123 **Excerpt:** 钉钉CLI工具（dws）是钉钉 2026 年 3 月开源的命令行程序，基于 Go 1.25+ 开发，把钉钉 18 个产品共 331 条命令封装为 CLI，原生支持 Claude Code、Cursor 等 AI Agent 调用。本文从功能清单、安装认证、横向对比三个角度展开。 ## 钉钉CLI工具 是什么：一次坦诚的初次接触 ### 一个命令行工具，不是另一个钉钉客户端 **钉钉CLI工具**（DingTalk Workspace CLI，命令名 `dws`）是钉钉官方开源的命令行程序。它基于 `Go` 1.25+ 开发，于 2026 年 3 月 27 日以 Apache-2.0 协议在 GitHub 开源。与图形界面的钉钉客户端不同，dws 没有可视化窗口，所有操作通过文本命令完成。它面向的场景是把钉钉的产品能力（通讯录、日历、待办、审批等）封装成可调用的命令行接口，让人类开发者与 AI Agent 都能在终端中操作钉钉。 ![钉钉CLI工具截图](https://cdn.hello123.com/wp-content/uploads/2026/06/dingtalk-workspace-cli-scaled.webp) ### 定位：钉钉产品能力的命令行封装 根据 GitHub 仓库 README 的"Key Services"清单，dws 将钉钉的 **18 个产品**（contact、chat、calendar、todo、approval、attendance、ding、report、aitable、doc、drive、minutes、mail、sheet、wiki、devdoc、aisearch、live）共 **331 条命令**统一封装到一个二进制文件中。这意味着原本需要在钉钉 Web 端逐项点开的操作，可以在终端中以单条命令完成，也可以让 AI Agent 通过结构化输入直接调用。 ### 核心卖点：为 AI Agent 而生的 CLI dws 的原生设计目标是让 AI Agent 能像调用本地命令一样调用钉钉能力。仓库 README 明确说明它"为人类和 AI 代理而构建"，提供三种输出格式：表格（默认）、`JSON`、原始 **API** 响应。AI Agent 可以从 `JSON` 响应中直接提取字段，而不需要解析自然语言文本。安装时附带的 Agent Skills 让 **Claude** Code、Cursor 等工具开箱即用。 ## 核心功能：能做什么与怎么用 ### 18 个产品共 331 条命令 根据 GitHub 仓库的"Key Services"清单，dws 覆盖的产品按命令数排序：Chat/IM（**65 条**）、AI Tables（**52 条**）、Doc（**28 条**）、Sheet（**23 条**）、Wiki（**21 条**）、Report（**20 条**）、Minutes（**19 条**）、Mail（**18 条**）、Calendar（**17 条**）、Todo（**16 条**）、Contact（**15 条**）、Approval（**15 条**）、Drive（**9 条**）、Attendance（**4 条**）、AI Search（**3 条**）、DevDoc（**2 条**）、Ding（**2 条**）、Live（**1 条**）。此外还提供 `dws api`（**1 条**）用于直接调用任意钉钉 OpenAPI。 ### 安装方式：一行脚本或 npm `macOS`/`Linux` 用户可以通过仓库提供的 install.sh 脚本一行命令安装；`Windows` 用户使用 PowerShell 的 install.ps1 脚本。也支持 `npm install -g dingtalk-workspace-cli`（需 `Node.js` 环境），或从 GitHub Releases 直接下载对应平台的二进制。从源码编译需要 Go 1.25+ 环境。 ### 认证：OAuth 设备流与企业管理员授权 首次运行需要执行 `dws auth login`，浏览器会自动打开完成钉钉账号授权。无头环境（Docker、`SSH`、CI）可使用 `dws auth login `–devic`e` 走设备流。仓库 README 强调"不是任何一个字节可以绕过认证和审计"，所有调用都经过钉钉开放平台的鉴权链路。 ### 输出格式：表格、JSON 与原始响应 通过 `-f table/json/raw` 切换输出格式。表格适合人类阅读，JSON 适合程序处理，原始 API 响应适合调试。还可以用 `--jq` 表达式精确提取字段，例如 `--jq '.result[0].orgEmployeeModel | {name, dept}'` 只取姓名和部门，降低 **Token** 消耗。 ## 使用 钉钉CLI工具 的几个前提条件 ### 环境依赖：Go 1.25+（仅源码编译时） 如果直接下载二进制或使用 shell 脚本安装，无需任何运行时环境——单文件即可执行。只有从源码编译时才需要 Go 1.25+。npm 安装方式需要 Node.js。 ### 安装步骤：脚本一行命令 macOS/Linux：`curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh`。Windows：`irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex`。安装后需要将 `~/.local/bin` 加入 PATH。也可以从 Releases 页面直接下载对应平台的二进制。 ### 认证配置：企业管理员需开启 CLI 访问 仓库 README 的"Important"提示：项目处于 Co-creation Phase（共创阶段），需要企业管理员授权。如果组织未开启 CLI 访问，登录时会提示"Apply Now"通知管理员，管理员在"开发者平台 → CLI 访问管理"中开启。开启后重新执行 `dws auth login`。 ### 首次运行：auth login 加一条查询命令 `dws auth login` 完成授权后，可以运行 `dws contact user search `–query` "engineering"` 验证通讯录权限，或 `dws calendar event list` 查看今天的日历事件。如果两条命令都返回数据，说明认证和权限配置完成。所有写入类命令都支持 `--dry-run` 预览参数和执行结果，避免误操作。 ## 横向对比：钉钉CLI工具 与同类的真实差距 ### 对比钉钉开放平台 Web 控制台：操作路径的压缩 Web 控制台需要逐级菜单点击，适合偶尔配置或非技术用户。dws 把多步操作压缩成单条命令，例如查询某部门员工：Web 端要先进入通讯录 → 部门 → 搜索，dws 直接 `dws contact dept members `–name` "研发部"`。但 Web 控制台对非技术用户更友好，dws 更适合高频或批量化场景。 ### 对比钉钉开放平台 API：封装层级的不同 直接调用钉钉 API 需要自己处理 OAuth 鉴权、Token 刷新、请求构造。dws 封装了这些底层细节，调用方只需要关心业务参数。但 dws 的灵活性不如直接调 API——复杂的定制场景仍需走 API。dws 也提供了 `dws api` 命令直接调任意 OpenAPI 作为兜底。 ### 对比通用脚手架工具（如 curl 加脚本）：标准化与可维护性 开发者完全可以自己写 shell 脚本调钉钉 API。dws 的价值在于标准化：331 条命令统一参数风格（kebab-case 命名）、统一错误处理、统一输出格式。脚本更容易维护。但通用性不如自定义脚本，只能覆盖 dws 已封装的产品。 ## 从场景到人群：钉钉CLI工具 的适用画像 ### 场景一：AI Agent 批量处理办公任务 让 Claude Code 或 Cursor 读取一份员工 Excel，自动调用 `dws contact user search` 校验花名册，再用 `dws todo task create` 给每位员工创建待办。整个流程在 AI Agent 对话中完成，不需要切回钉钉客户端操作。仓库 README 的"Using with Agents"章节正是为此设计。 ### 场景二：CI/CD 流水线中的自动化通知 Jenkins 或 GitHub Actions 构建完成后，用 `dws chat message send-by-bot `–robot-code`BOT_CODE`–group`GROUP_ID`–title`"构建完成"`–text` @release.md` 把构建报告推送到钉钉群。比邮件通知更直接，也避免了 Web 端复制粘贴。 ### 场景三：批量查询与数据导出 通过 `--jq` 表达式组合多条命令，把钉钉 AI 表格的数据导出为 JSON，再喂给下游分析工具。例如 `dws aitable record query `–base-id`BASE_ID`–table-id`TABLE_ID`–jq` '.records[] | {name, dept}'` 只提取需要的字段。仓库 README 还提供了 13 个 `Python` 脚本（如 `import_records.py`、`todo_batch_create.py`）覆盖常见批量场景。 ### 不适用场景：纯非技术用户 没有命令行经验的用户不适合直接使用 dws。但可以通过 Claude Code 等 AI Agent 间接调用——用自然语言描述需求，AI 自动生成 dws 命令。钉钉官方在 README 中也强调"为人类和 AI 代理而构建"，意图是让 AI 承担命令构造的复杂度。 ## 钉钉CLI工具 的价值逻辑：效率之外的收益 ### 标准化接口降低集成成本 传统钉钉 API 集成需要为每个产品单独写鉴权和请求逻辑。dws 把 18 个产品统一到一套命令风格下，开发者学一次就能调全部。这对需要对接多个钉钉产品的 ISV（独立软件开发商）尤其有价值，可以显著减少重复工程。Apache-2.0 协议也允许 ISV 在商业产品中集成 dws，无需额外授权谈判。 ### 安全架构：零信任设计 仓库 README 的"Security by Design"章节明确：凭据不落盘（内存中处理）、Token 不出可信域名（默认 `*.dingtalk.com`）、权限不超授权、操作不漏审计。比开发者自建脚本调 API 更安全，因为绕过审计的可能性被架构层面堵死。 ### Agent Skills：让 AI 开箱即用 安装时可以选择 `mono`（单一 skill，默认）或 `multi`（18 个分产品 skill，实验性）两种布局。skill 文件安装到 `~/.agents/skills/dws`，Claude Code、Cursor、Codex、OpenCode、Qoder 等 AI 工具能自动发现并按需调用。 ## 从最近版本看 钉钉CLI工具 的产品方向 ### v1.0.7+：自助升级与回滚 仓库 README 的"Upgrade"章节显示，v1.0.7 及以上版本支持 `dws upgrade` 自助升级，从 GitHub Releases 拉取并通过 SHA256 校验。还支持 `--rollback` 回滚到上一版本。升级采用两阶段原子流程：先 Prepare（下载校验）再 Apply（替换），失败时不动现有安装。 ### Multi-skill 模式：实验性功能 2026 年的版本引入了 `multi` skill 布局，把原本单一的 dws skill 拆成 18 个分产品的 skill（dingtalk-aitable、dingtalk-calendar 等）。仓库明确标注为 EXPERIMENTAL / preview，未来接口和命名可能调整，生产环境仍推荐 mono。 ### 即将推出的产品：conference README 的"Coming soon"提到 `conference`（视频会议）产品即将推出。这意味着 dws 还在扩展覆盖范围，未来视频会议相关的查询和控制也可能通过 CLI 完成。 ## 替代品推荐：什么场景下 CLI 不是首选 ### 钉钉开放平台 Web 控制台：适合可视化操作者 偏好图形界面的用户应使用 Web 控制台。所有操作有视觉反馈，适合偶尔配置或非技术用户。dws 和 Web 控制台是互补关系，不是替代关系——同一企业的不同岗位可以各取所需。 ### 直接调用钉钉开放平台 API：更细粒度的控制 有 API 集成经验的开发者可以直接调用钉钉 OpenAPI。这提供最大的灵活性，但需要自己处理 OAuth、Token 刷新、错误重试。dws 的 `dws api` 命令也提供了直接调任意 OpenAPI 的入口，兼顾灵活性和便捷性。 ## 数据隐私与安全：代码在本地，凭证需自管 ### 凭证存储：PBKDF2 加 AES-256-GCM 加密 仓库 README 的"Security by Design"章节说明：Token 用 PBKDF2 加 AES-256-GCM 加密存储，密钥由设备物理 MAC 地址生成，并集成 Keychain/DPAPI。这意味着即使配置文件被复制到另一台机器，也无法解密。 ### 域名白名单：Token 不外发 默认 `DWS_TRUSTED_DOMAINS` 为 `*.dingtalk.com`。Bearer Token 永远不会被发送到非白名单域名，防止 Token 被诱导发往外部服务器。所有请求强制 `HTTPS`（开发环境 loopback 除外）。 ### 审计：所有调用走开放平台 dws 的每一次 API 调用都经过钉钉开放平台的鉴权和审计链路。企业管理员可以在开放平台后台看到完整的调用日志，包括调用者身份、调用的命令、时间戳。仓库 README 强调"no anomalous operation can hide"（异常操作无处藏身）。 ## 学习曲线：从零到熟练的路径 ### 前提技能：命令行基础 作为一款命令行工具，dws 要求用户具备终端操作经验，了解钉钉应用的基本概念（如 OAuth、access\_token、组织架构）。无命令行经验者会感到吃力——但通过 AI Agent 间接使用可以绕过这层门槛。 ### 文档质量：GitHub README 加命令索引 仓库提供 README（中英文）、Reference 文档、Command Index（`docs/command-index.md`）、Changelog。每条命令都有 `--help` 输出。文档覆盖安装和命令列表，但故障排除场景的指引相对较少，遇到边缘问题可能需要查 Issues。 ### 典型学习周期：开发者 1 小时内跑通 具备命令行和 OAuth 基础的开发者，从安装到首次成功调用 `dws contact user search` 平均耗时 1 小时以内。熟悉 `--dry-run` 和 `--jq` 用法后，可以快速组合多命令完成复杂任务。 ## 参考资料 - [GitHub 仓库](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli)（2026-03-27 开源）— 官方源码与文档 - [钉钉开放平台文档](https://open.dingtalk.com/document/development/dingtalk-cli-performing-tasks-within) — 官方介绍 dws 如何让 AI Agent 在钉钉内执行任务 ---