DingTalk Workspace CLI (dws)

dws — 钉钉工作台命令行工具，为人类和 AI Agent 而生。

中文版 · English · 参考手册 · 更新日志

Important

共创阶段：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。当前为灰度共创阶段，请加入钉钉 DWS 共创群完成白名单配置。详见下方 开始使用。

目录

• 为什么选择 dws？
• 安装
• 开始使用
• 快速开始
• 核心服务
• 安全设计
• AI Agent Skills
• 参考与文档
• 贡献指南

---

为什么选择 dws？

• 为人类而设计 — --help 查看用法，--dry-run 预览请求，-f table/json/raw 切换格式。
• 为 AI Agent 而设计 — 结构化 JSON 响应 + 内置 Agent Skills，开箱即用。
• 为企业管理员而设计 — 零信任架构：OAuth 设备流认证 + 域名白名单 + 权限最小化。没有一个字节能绕过安全鉴权和审计。

安装

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install.ps1 | iex

其他安装方式

预编译二进制文件：从 GitHub Releases 下载。

从源码构建：

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
make build

二进制文件默认安装到 ~/.local/bin。如找不到 dws，请将其添加到 PATH：export PATH="$HOME/.local/bin:$PATH"

开始使用

步骤 1：创建钉钉应用

进入 开放平台应用开发后台，在「企业内部应用 - 钉钉应用」点击创建应用。

查看截图

步骤 2：配置重定向 URL

进入应用 → 安全设置，在「重定向 URL」中输入 http://127.0.0.1 并保存。

查看截图

步骤 3：发布应用

点击「应用发布 - 版本管理与发布」，发布版本使应用上线。

查看截图

步骤 4：申请白名单

加入钉钉 DWS 共创群，提供 Client ID 和管理员确认凭证完成白名单配置。

步骤 5：登录认证

dws auth login --client-id <your-app-key> --client-secret <your-app-secret>

或通过环境变量：

export DWS_CLIENT_ID=<your-app-key>
export DWS_CLIENT_SECRET=<your-app-secret>
dws auth login

CLI 参数优先于环境变量。凭证用于钉钉 OAuth 设备流认证。

快速开始

dws contact user search --keyword "悟空"           # 搜索联系人
dws calendar event list                            # 查看日历日程
dws todo task create --title "季度汇报" --executors "<userId>"   # 创建待办
dws todo task list --dry-run                       # 预览操作但不执行

核心服务

服务	命令	描述
通讯录	contact	用户 / 部门
群聊	chat	群管理 / 群成员 / 机器人消息 / Webhook
日历	calendar	日程 / 会议室 / 闲忙
待办	todo	任务管理
审批	approval	流程 / 表单 / 实例
考勤	attendance	打卡 / 排班 / 统计
DING	ding	DING 消息 / 发送 / 撤回
日志	report	日志 / 模版 / 统计
智能表格	aitable	AI 表格操作
工作台	workbench	应用查询
开发者文档	devdoc	开放平台文档搜索

运行 dws --help 查看完整列表，或 dws <service> --help 查看子命令。

即将推出

doc（文档）· mail（邮箱）· minutes（AI 听记）· drive（钉盘）· conference（视频会议）· tb（Teambition）· aiapp（AI 应用）· live（直播）· skill（技能市场）

安全设计

dws 从架构层面将安全作为一等公民，而非事后补丁。凭证不落盘、Token 不出域、权限不越界、操作不脱审 — 每一次 API 调用都必须经过钉钉开放平台的鉴权和审计链路，无例外。

开发者安全机制

机制	说明
Token 加密存储	PBKDF2（600,000 次迭代）+ AES-256-GCM 加密，密钥由设备 MAC 地址派生，文件拷贝到其他设备无法解密
域名白名单	DWS_TRUSTED_DOMAINS 默认仅信任 *.dingtalk.com，Bearer Token 不会发送到非白名单域
HTTPS 强制	除 loopback 开发调试外，所有请求强制 TLS
Dry-run 预览	--dry-run 展示调用参数但不执行，防止误操作生产数据
凭证零落盘	Client ID / Secret 仅在内存中使用，不写入配置文件或日志

企业管理员安全机制

机制	说明
OAuth 设备流认证	用户必须通过管理员授权的钉钉应用认证，未授权应用无法获取 Token
权限最小化	CLI 仅能调用管理员授予该应用的 API 权限范围，无法越权
白名单准入	共创阶段需管理员主动确认开通，后续支持自助审批
操作全链路审计	每一次数据读写都经过钉钉开放平台 API，企业管理员可在管理后台实时追溯完整调用日志，任何异常操作无处隐藏

ISV / 企业服务商安全机制

机制	说明
租户数据隔离	以已授权应用身份调用 API，不同租户数据严格隔离
Skill 沙箱	Agent Skills 是 Markdown 文档（SKILL.md），仅提供 prompt 描述，不执行任意代码
集成链路零盲区	ISV Skill 与 dws Skill 联调时，每一次 API 调用都强制经过钉钉开放平台鉴权，完整调用链路可追溯，不存在绕过审计的旁路

发现安全漏洞？请通过 GitHub Security Advisories 报告，详见 SECURITY.md。

AI Agent Skills

仓库为每个钉钉产品提供 Agent Skill（SKILL.md），安装脚本会自动部署到 ~/.agents/skills/dws。

# 仅安装 skills 到当前项目
curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh

install.sh 安装到 $HOME/.agents/skills/dws（全局）；install-skills.sh 安装到 ./.agents/skills/dws（当前项目）。

ISV Skill 联调

编写您自己的 Agent Skill，与 dws 内置 skill 搭配构建跨产品工作流：ISV Skill → dws Skill → 钉钉开放平台 API（强制鉴权 + 全链路审计）。

示例：CRM Skill 调用日历 Skill 为客户创建会议，再通过待办 Skill 分配跟进任务 — AI Agent 在一次对话中完成跨系统协作。

参考与文档

• 参考手册 — 环境变量、退出码、输出格式、Shell 补全
• 架构设计 — 发现驱动管道、IR、Transport 层
• 更新日志 — 版本历史与迁移说明

贡献指南

参见 CONTRIBUTING.md 了解构建、测试和开发工作流。

许可证

Apache-2.0