DingTalk Workspace CLI (dws)

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

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

[!IMPORTANT] 共创阶段：本项目涉及钉钉企业数据访问，需企业管理员授权后方可使用。欢迎加入钉钉 DWS 共创群获取支持与最新动态。详见下方 开始使用。

目录

• 为什么选择 dws？
• 安装
• 升级
• 开始使用
• 快速开始
• 在 Agent 中使用
• 功能特性
• 核心服务
• 安全设计
• 参考与文档
• 贡献指南

为什么选择 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

Skill 模式：mono 与 multi

安装时可以选择两种 skill 组织方式。两种模式下 CLI 命令完全一样（dws aitable ... / dws calendar ...），区别只在 Agent 那边读到的 skill 文档结构。

🧪 multi 模式当前为 EXPERIMENTAL（试验版 / Preview）。20 个独立 skill 全部通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 mono。问题请提 issue 反馈。

怎么选：

• 快速安装（上方一行 curl）：非交互，默认装 mono。
• TTY 安装（先下载再执行）：curl -O .../install.sh && bash install.sh，会弹出 1) mono 2) multi 选项（默认 1）。
• 环境变量覆盖：DWS_SKILL_MODE=multi curl -fsSL ... | sh。
• 装完之后再切换：dws skill setup --mode multi（或 --mode mono），随时重跑都行。

其他安装方式

npm（需要 Node.js（npm/npx））：

npm install -g dingtalk-workspace-cli

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

macOS 用户注意：如果提示“无法打开，因为 Apple 无法检查其是否包含恶意软件”，请执行： bash xattr -d com.apple.quarantine /path/to/dws

从源码构建：

git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
cd dingtalk-workspace-cli
go build -o dws ./cmd       # 编译到当前目录
cp dws ~/.local/bin/         # 安装到 PATH

需要 Go 1.25+。也可以用 make package 构建所有平台产物（macOS / Linux / Windows × amd64 / arm64）。

国内加速安装

国内用户可使用以下通道，避免 GitHub 网络问题。默认（不设置这些环境变量）走 GitHub。

1. 安装脚本 + 预编译二进制（Gitee 镜像）：

仓库镜像地址：https://gitee.com/DingTalk-Real-AI/dingtalk-workspace-cli

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

设置 DWS_GITEE_REPO 后，安装脚本会改从 Gitee API 解析最新版本和各个 release 产物（二进制、校验和、skills 包），而不是走 GitHub。不设置时默认从 GitHub 安装。

2. npm 包（npmmirror 镜像）：

npm install -g dingtalk-workspace-cli --registry=https://registry.npmmirror.com

npmmirror 会自动同步公网 npm 的公开包，国内可直接使用。

3. 单独安装 Skills（Gitee 镜像）：

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

同样设置 DWS_GITEE_REPO，install-skills.sh 会从 Gitee 解析版本和 skills 包；GitHub 不可达时也会自动回退到 Gitee 镜像。

升级

需要 v1.0.7 及以上版本。更早版本请重新执行安装脚本进行升级。

dws 内置自升级能力，直接从 GitHub Releases 拉取更新，支持 SHA256 完整性校验和自动备份。

dws upgrade                    # 交互式升级到最新版本
dws upgrade --check            # 仅检查是否有新版本
dws upgrade --list             # 列出所有可用版本
dws upgrade --version v1.0.7   # 升级到指定版本
dws upgrade --rollback         # 回滚到上一版本
dws upgrade -y                 # 跳过确认直接升级

工作原理

升级过程采用两阶段原子流程，确保一致性：

1. 准备阶段 — 将平台对应的二进制文件和技能包下载到临时目录，校验 SHA256 校验和，解压并验证所有文件。任何步骤失败则立即中止，不会修改现有安装。
2. 执行阶段 — 仅在所有准备工作成功后，替换二进制文件并将技能包安装到所有已检测到的 Agent 目录（~/.agents/skills/dws、~/.claude/skills/dws、~/.cursor/skills/dws 等）。

每次升级前自动备份当前版本，可通过 dws upgrade --rollback 随时回滚。

开始使用

dws auth login            # 自动唤起浏览器
dws auth login --device   # 无浏览器环境（Docker、SSH、CI）

选择组织并授权即可。

如果组织尚未开启 CLI 访问权限，系统会引导你向管理员发送申请。审批通过后重新执行 dws auth login 即可。

组织未开启 CLI 访问权限？

1. 选择组织后，点击「立即申请」通知管理员
2. 管理员收到申请卡片，一键审批
3. 审批通过后，重新执行 dws auth login

管理员：为组织开启 CLI 访问权限

进入 开发者平台 →「CLI 访问管理」→ 开启。

自建应用模式（CI/CD、ISV 集成）

企业自主管控场景，可创建自有钉钉应用：

1. 开放平台应用开发后台 → 创建应用
2. 安全设置 → 添加重定向 URL：http://127.0.0.1,https://login.dingtalk.com
3. 发布应用
4. 登录：

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

首次登录后凭证安全存储（Keychain），后续自动刷新 Token。

多组织（profile）

dws 可以同时登录多个钉钉组织。一个组织就是一个 profile，当前 profile 决定本次命令操作哪个组织（凭证按组织分别存储）。

dws auth login                              # 再登录一个组织 → 新增一个 profile（首次登录的为主组织）
dws profile list                            # 列出已登录组织（主 / 当前标记、状态）
dws profile switch <名称|corpId>            # 切换默认组织（用 - 切回上一个）
dws --profile <名称|corpId> contact user search --query "..."   # 单次对指定组织执行，不改默认组织

跨组织读取由 agent 编排，而非内置 --all-orgs：先 dws profile list 拿到组织，再对每个组织带 --profile 各查一遍，然后合并。写操作默认只在当前组织进行——跨组织写之前先确认目标组织。

沙箱间迁移登录态（Linux）

仅拷贝 ~/.dws/app.json 无法带走 refresh token；access token 约 2 小时后会失效。请使用官方导出/导入：

# A 沙箱（已登录）
dws auth export -o /tmp/dws-auth.tar.gz
# 或便于分片复制：dws auth export --base64 -o /tmp/dws-auth.b64

# B 沙箱
dws auth import -i /tmp/dws-auth.tar.gz
# 或：dws auth import -i /tmp/dws-auth.b64 --base64
dws auth status   # 确认 Refresh Token: 有效

包内包含 ~/.local/share/dws-cli 加密 keychain（含 auth-token.enc 与 dek）及 ~/.dws 必要配置。

快速开始

dws contact user search --query "悟空"             # 搜索联系人
dws calendar event list                            # 查看今天的日程
dws doc search --query "季度"                      # 搜索钉钉文档
dws minutes list mine                              # 列出我创建的 AI 听记
dws drive list                                     # 列出钉盘文件
dws todo task create --title "季度汇报" --executors "<your-userId>"   # 创建待办（请替换为真实 userId）
dws todo task list --dry-run                       # 预览操作但不执行

完整命令列表：docs/command-index.md — 全部命令，带描述和使用场景。

在 Agent 中使用

dws 是为 AI Agent 设计的 CLI 工具。请先完成安装和开始使用，然后配置 Agent 环境：

Agent 调用模式

# 使用 --yes 跳过确认提示（Agent 必须）
dws todo task create --title "Review PR" --executors "<your-userId>" --yes

# 使用 --dry-run 预览操作（安全执行）
dws contact user search --query "张三" --dry-run

# 使用 --jq 精确提取（节省 token）
dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName, userId}'

Schema 发现

Agent 无需预置所有命令知识，通过 dws schema 动态发现可用能力：

# 第一步：发现所有可用产品
dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'

# 第二步：查看目标工具的参数结构
dws schema aitable.query_records --jq '.tool.parameters'

# 第三步：构造正确的调用
dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

Agent Skills

仓库内置完整的 Agent Skill 体系（skills/ 目录），目前重组为两套布局：

• skills/mono/ — 单 skill 布局（一个 SKILL.md + references/products/），默认推荐。
• skills/multi/ — 每个产品一个独立 skill（dingtalk-aitable/ / dingtalk-calendar/ / dingtalk-chat/ ... 共 18 个），每个 skill 自带 SKILL.md。🧪 试验版 / Preview — 各 multi SKILL.md 头部有详细注意事项。

安装之后，Claude Code / Cursor 等 AI 工具就能通过自然语言直接操作钉钉：

# 安装 skills 到当前项目（默认 mono）
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（当前项目）。

国内用户加 DWS_GITEE_REPO 走 Gitee 镜像，见 国内加速安装。

用 dws skill setup 切换或重装：

# 交互式：提示选模式 + 目标 Agent
dws skill setup

# 把 mono skill 铺到所有检测到的 Agent home（claude / cursor / codex / opencode / qoder）
dws skill setup --mode mono --target all --yes

# 只装到某一个 Agent home
dws skill setup --mode multi --target cursor --yes

# 指定本地源目录（比如 fork 或正在改的版本）
DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi

环境变量：DWS_SKILL_MODE=mono|multi（install.sh / install.ps1 也认）、DWS_SKILL_SOURCE=<路径>。

包含内容（mono 布局）：

现成脚本 — 13 个 Python 脚本，覆盖常见多步工作流

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

功能特性

Raw API 调用 — 直接调用钉钉 OpenAPI

dws api 让你直接调用任意钉钉 OpenAPI，无需 SDK，Token 自动获取和刷新。

前置条件：必须使用自有应用凭证登录（见自建应用模式）。通过 MCP 默认凭证登录 不支持 raw API 调用。

# 登录（仅首次）
dws auth login --client-id <APP_KEY> --client-secret <APP_SECRET>

# === api.dingtalk.com ===

# 获取企业所有应用列表
dws api GET /v1.0/microApp/allApps

# 搜索用户 (POST + JSON body)
dws api POST /v1.0/contact/users/search \
  --data '{"queryWord":"张三","offset":0,"size":10}'

# === oapi.dingtalk.com ===

# 获取用户详情（使用 --base-url 指定域名）
dws api POST /topapi/v2/user/get \
  --base-url https://oapi.dingtalk.com \
  --data '{"userid":"<USER_ID>"}'

# 也可以直接使用完整 URL
dws api POST https://oapi.dingtalk.com/topapi/v2/user/get \
  --data '{"userid":"<USER_ID>"}'

# === 通用功能 ===
dws api GET /v1.0/microApp/allApps --page-all   # 自动翻页
dws api GET /v1.0/microApp/allApps --dry-run     # 预览请求
dws api GET /v1.0/microApp/allApps --jq '.agentId'  # jq 过滤

智能输入纠错 — 自动修正 AI 模型常见的参数错误

内置 Pipeline 纠错引擎，支持命名风格转换、粘连参数拆分、拼写模糊匹配：

```bash

命名风格自动转换 (camelCase / snake_case / UPPER → kebab-case)

dws aitable record query --baseId BASE_ID --tableId TABLE_ID # 自动纠正为 --base-id --table-id

粘连参数自动拆分

dws contact user search --query "张三" --timeout30 # 自动拆分为 --timeout 30

拼写错误模糊匹配

dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID # --tabe