钉钉 DWS CLI 运维实战指南
<p class="subtitle">基于 v1.0.15+ · 14大产品能力全覆盖 · 运维场景深度剖析</p>
<div class="section">
<h2>一、DWS 是什么？</h2>
<p><strong>DWS（ DingTalk Workspace CLI）</strong>是钉钉官方提供的命令行工具，通过统一的 <code>dws</code> 命令覆盖钉钉全线产品能力。与直接调用 HTTP API 不同，DWS 封装了认证、错误处理、数据解析等繁琐细节，运维人员只需关注业务逻辑。</p>
<div class="info">
<strong>核心优势：</strong>
<ul style="margin-top:10px">
<li>✅ 统一 CLI，体验一致，所有产品共用同一套 flag 规范（<code>--format json</code>、<code>--yes</code> 等）</li>
<li>✅ JSON 输出 + <code>--help</code> + <code>dws schema</code> 三位一体文档，告别"参数靠猜"</li>
<li>✅ 危险操作二次确认（<code>--yes</code> 显式授权）</li>
<li>✅ 批量操作有脚本（<code>scripts/</code> 目录），拿来即用</li>
<li>✅ 单次批量不超过 30 条记录，服务端限流友好</li>
</ul>
</div>
<h3>版本要求</h3>
<p>CLI 版本需 <code>>= 1.0.15</code>，通过 <code>dws --version</code> 确认。当前 OpenClaw 已集成 DWS，Elaine 可直接调用。</p>
</div>
<div class="section">
<h2>二、14大产品能力总览</h2>
<table>
<tr>
<th>产品</th>
<th>命令前缀</th>
<th>核心能力</th>
<th>运维价值</th>
</tr>
<tr>
<td><span class="tag tag-green">aitable</span></td>
<td><code>dws aitable</code></td>
<td>AI表格/数据表/视图/图表/仪表盘</td>
<td>运维工单管理、资产台账、监控数据报表</td>
</tr>
<tr>
<td><span class="tag tag-blue">attendance</span></td>
<td><code>dws attendance</code></td>
<td>打卡记录/排班/考勤规则/统计</td>
<td>团队出勤核查、外勤人员管理</td>
</tr>
<tr>
<td><span class="tag tag-purple">calendar</span></td>
<td><code>dws calendar</code></td>
<td>日程/会议室/参与者/闲忙查询</td>
<td>值班排班、会议室预定、系统维护窗口通知</td>
</tr>
<tr>
<td><span class="tag tag-yellow">chat</span></td>
<td><code>dws chat</code></td>
<td>群管理/消息收发/机器人/Webhook</td>
<td>告警通知、巡检日报推送、故障群发</td>
</tr>
<tr>
<td><span class="tag tag-green">contact</span></td>
<td><code>dws contact</code></td>
<td>用户查询/部门查询/手机号查人</td>
<td>快速找人、确认值班人员信息</td>
</tr>
<tr>
<td><span class="tag tag-blue">devdoc</span></td>
<td><code>dws devdoc</code></td>
<td>钉钉开放平台文档搜索</td>
<td>API 排查、接口参数确认</td>
</tr>
<tr>
<td><span class="tag tag-red">ding</span></td>
<td><code>dws ding</code></td>
<td>DING消息发送/撤回（应用/短信/电话）</td>
<td>P0 故障紧急通知、必须响应的告警</td>
</tr>
<tr>
<td><span class="tag tag-purple">doc</span></td>
<td><code>dws doc</code></td>
<td>钉钉文档读写/块级编辑/评论</td>
<td>运维手册、故障复盘文档、团队知识库</td>
</tr>
<tr>
<td><span class="tag tag-yellow">drive</span></td>
<td><code>dws drive</code></td>
<td>云盘文件上传/下载/文件夹管理</td>
<td>日志文件归档、备份包存取、报告下载</td>
</tr>
<tr>
<td><span class="tag tag-green">minutes</span></td>
<td><code>dws minutes</code></td>
<td>AI听记/转写/摘要/思维导图/待办</td>
<td>会议纪要自动生成、值班交接记录</td>
</tr>
<tr>
<td><span class="tag tag-blue">oa</span></td>
<td><code>dws oa</code></td>
<td>OA审批/待办/我发起的/同意/拒绝</td>
<td>工单审批加速、请假/出差/报销流程处理</td>
</tr>
<tr>
<td><span class="tag tag-purple">report</span></td>
<td><code>dws report</code></td>
<td>日志/日报/周报/收件箱/模板</td>
<td>团队日报收集、运维日志汇总统计</td>
</tr>
<tr>
<td><span class="tag tag-yellow">mail</span></td>
<td><code>dws mail</code></td>
<td>邮件搜索/详情/发送</td>
<td>告警邮件转发、工单通知邮件确认</td>
</tr>
<tr>
<td><span class="tag tag-green">todo</span></td>
<td><code>dws todo</code></td>
<td>待办创建/查询/修改/完成/删除</td>
<td>故障跟进任务、巡检任务派发</td>
</tr>
</table>
</div>
<div class="section">
<h2>三、命令发现与文档规范</h2>
<p>DWS 的权威文档有两层，发生冲突时按此优先级：<code>dws schema</code> > <code>dws <cmd> --help</code> > 参考文档（.md）。</p>
<h3>3.1 人读视图 — 看 Usage 和 Example</h3>
<pre><code># 查看命令帮助
dws <command-path> --help
示例：日历命令帮助
dws calendar event list --help
<h3>3.2 机读视图 — JSON Schema + Flag 别名</h3>
<pre><code># 列出所有产品及工具
dws schema
查看特定命令的 Schema
dws schema calendar.list_suggested_event_times
dws schema "calendar event list"
只看 flag 别名（实际生效的参数名）
dws schema <path> --jq '.tool.flag_overlay'
只看必填字段
dws schema <path> --jq '.tool.required'
<div class="highlight">
<strong>⚠️ 注意：</strong>所有命令<strong>必须</strong>加 <code>--format json</code> 获取可解析输出。危险操作（删除、审批等）需用户确认后才加 <code>--yes</code> 执行。
</div>
</div>
<div class="section">
<h2>四、运维实战场景</h2>
<h3>场景1：故障告警通知 — Webhook 机器人</h3>
<div class="scenario-card">
<h4>🤖 需求：服务器 CPU 超 90%，自动发钉钉群告警</h4>
<p>通过 Webhook 机器人发送 Markdown 格式告警，可 @ 值班人员。</p>
<pre><code># 发送 Webhook 告警（无需认证，机器人 Code 不需要）
dws chat message send-by-webhook \
--token <webhook-token> \
--title "🚨 服务器告警" \
--text "服务器：生产环境-1\n指标：CPU 92%\n时间：2026-04-30 13:00:00\n请值班人员及时处理！" \
--at-users 1104083318783932 \
--format json
适用命令chat message send-by-webhook
<h3>场景2：紧急故障必须响应 — DING 消息</h3>
<div class="scenario-card">
<h4>📞 需求：P0 故障需立即通知，不接受忽略</h4>
<p>DING 消息支持应用内、短信、电话三种方式，短信/电话可确保触达。</p>
<pre><code># 应用内 DING（免费）
dws ding message send \
--robot-code <ROBOT_CODE> \
--type app \
--users <USER_ID> \
--content "P0故障：数据库连接失败，请立即处理！" \
--format json
电话 DING（紧急，有成本）
dws ding message send \
--robot-code <ROBOT_CODE> \
--type call \
--users <USER_ID> \
--content "紧急：核心服务不可用，请接听！" \
--format json
⚠️ 危险 电话/短信 DING 有通信成本，使用前需确认。
适用命令ding message send
<h3>场景3：故障跟进任务派发 — Todo 待办</h3>
<div class="scenario-card">
<h4>✅ 需求：故障发生后派发跟进任务，设置优先级和截止时间</h4>
<pre><code># 创建紧急待办
dws todo task create \
--title "【P0】修复数据库连接池泄漏" \
--executors <USER_ID> \
--priority 40 \
--due "2026-04-30T18:00:00+08:00" \
--format json
查询未完成待办
dws todo task list --page 1 --size 20 --status false --format json
标记完成
dws todo task done --task-id <taskId> --status true --format json
适用命令todo task create / list / done
<h3>场景4：团队值班排班 — Calendar 日历</h3>
<div class="scenario-card">
<h4>📅 需求：创建值班日程，确认参与人时间冲突</h4>
<pre><code># 创建值班日程
dws calendar event create \
--title "周末值班" \
--start "2026-05-01T09:00:00+08:00" \
--end "2026-05-01T18:00:00+08:00" \
--attendee-user-ids <USER_ID_1>,<USER_ID_2> \
--format json
查询会议室闲忙
dws calendar room freebusy \
--room-ids <ROOM_ID> \
--start "2026-05-01T09:00:00+08:00" \
--end "2026-05-01T18:00:00+08:00" \
--format json
获取时间建议（找出大家都有空的时间）
dws calendar event suggest-times \
--attendee-user-ids <USER_ID_1>,<USER_ID_2> \
--duration 60 \
--format json
适用命令calendar event create / room freebusy / event suggest-times
<h3>场景5：运维工单审批 — OA 审批</h3>
<div class="scenario-card">
<h4>📋 需求：查询待处理工单，审批通过或驳回</h4>
<pre><code># Step 1: 查看待我处理的审批
dws oa approval list-pending --page 1 --size 20 --format json
→ 返回 processInstanceId
Step 2: 查看工单详情
dws oa approval detail --instance-id <processInstanceId> --format json
Step 3: 获取 taskId（审批动作必须用 taskId）
dws oa approval tasks --instance-id <processInstanceId> --format json
Step 4: 同意审批
dws oa approval approve \
--instance-id <processInstanceId> \
--task-id <taskId> \
--remark "工单核实，同意部署" \
--format json
Step 4b: 拒绝审批
dws oa approval reject \
--instance-id <processInstanceId> \
--task-id <taskId> \
--remark "环境信息不完整，请补充后再提交" \
--format json
适用命令oa approval list-pending / detail / tasks / approve / reject
<h3>场景6：团队考勤核查 — Attendance 考勤</h3>
<div class="scenario-card">
<h4>🕘 需求：核查团队今日出勤情况，外勤人员是否正常打卡</h4>
<pre><code># 查询个人考勤记录
dws attendance record get \
--user <USER_ID> \
--date 2026-04-30 \
--format json
批量查询团队排班
dws attendance shift list \
--users userId1,userId2,userId3 \
--start 2026-04-27 \
--end 2026-05-03 \
--format json
查看考勤统计摘要
dws attendance summary \
--user <USER_ID> \
--date "2026-04-30 09:00:00" \
--format json
查看考勤规则（打卡范围、弹性时间）
dws attendance rules --date 2026-04-30 --format json
适用命令attendance record get / shift list / summary / rules
<h3>场景7：运维数据报表 — Aitable AI表格</h3>
<div class="scenario-card">
<h4>📊 需求：查询或管理存储监控数据的 AI 表格</h4>
<pre><code># 搜索"服务器监控"相关的 AI 表格
dws aitable base search --query "服务器监控" --format json
获取表格详情
dws aitable base get --base-id <BASE_ID> --format json
列出数据表中的记录
dws aitable record list \
--base-id <BASE_ID> \
--table-id <TABLE_ID> \
--format json
查看仪表盘（图表可视化）
dws aitable dashboard get \
--base-id <BASE_ID> \
--dashboard-id <DASHBOARD_ID> \
--format json
适用命令aitable base search / record list / dashboard get
<h3>场景8：日志文件归档 — Drive 云盘</h3>
<div class="scenario-card">
<h4>💾 需求：将服务器日志文件上传到钉钉云盘，供团队下载</h4>
<pre><code># Step 1: 获取上传信息
dws drive upload-info \
--file-name "server-error.log" \
--file-size <字节数> \
--format json
→ 返回 uploadId 和上传 URL
Step 2: 上传文件到 OSS
curl -X PUT -T "server-error.log" "<上传URL>"
Step 3: 提交上传
dws drive commit \
--file-name "server-error.log" \
--file-size <字节数> \
--upload-id <uploadId> \
--format json
下载文件
dws drive download --file-id <dentryUuid> --format json
适用命令drive upload-info / commit / download
<h3>场景9：故障复盘文档管理 — Doc 钉钉文档</h3>
<div class="scenario-card">
<h4>📝 需求：创建或更新故障复盘文档，写入 Markdown 内容</h4>
<pre><code># 搜索故障复盘相关文档
dws doc search --query "故障复盘 4月" --format json
读取文档内容
dws doc node get --node-id <NODE_ID> --format json
创建新文档
dws doc node create \
--title "【故障复盘】2026-04-30 数据库故障" \
--folder-id <FOLDER_ID> \
--format json
写入文档块
dws doc block create \
--node-id <NODE_ID> \
--block-type "text" \
--content "## 故障时间\n2026-04-30 13:00 - 14:30" \
--format json
适用命令doc search / node get / node create / block create
<h3>场景10：团队日报汇总 — Report 日志</h3>
<div class="scenario-card">
<h4>📝 需求：按模板收集团队日报，统计提交情况</h4>
<pre><code># 查看可用的日志模板
dws report template list --format json
按模板创建日报
dws report create \
--template-id <TEMPLATE_ID> \
--content "今日完成：修复CPU告警阈值配置\n明日计划：优化数据库索引" \
--format json
查看收件箱（收到的日报）
dws report inbox --format json
查看已发送的日志
dws report list-sent --format json
查看日志详情
dws report detail --report-id <REPORT_ID> --format json
适用命令report create / inbox / list-sent / detail
<h3>场景11：告警邮件转发确认 — Mail 邮箱</h3>
<div class="scenario-card">
<h4>📧 需求：搜索告警邮件，确认工单通知是否已发送</h4>
<pre><code># 搜索关键词邮件
dws mail search \
--keyword "CPU Alert Production" \
--start "2026-04-30T00:00:00+08:00" \
--end "2026-04-30T23:59:59+08:00" \
--format json
查看邮件详情
dws mail get --mail-id <MAIL_ID> --format json
发送邮件
dws mail send \
--to "[email protected]" \
--subject "【告警确认】服务器 CPU 异常已处理" \
--content "告警时间：13:00\n处理时间：13:45\n处理人：张三\n结论：已修复。" \
--format json
适用命令mail search / get / send
<h3>场景12：值班交接 AI 听记 — Minutes AI听记</h3>
<div class="scenario-card">
<h4>🎙️ 需求：上传会议录音，自动生成转写和摘要，提取待办</h4>
<pre><code># 获取听记列表
dws minutes list --format json
获取听记摘要和待办
dws minutes get \
--minutes-id <MINUTES_ID> \
--format json
获取思维导图
dws minutes mindmap --minutes-id <MINUTES_ID> --format json
获取发言人列表
dws minutes speaker-list --minutes-id <MINUTES_ID> --format json
适用命令minutes list / get / mindmap / speaker-list
<h3>场景13：快速找人 — Contact 通讯录</h3>
<div class="scenario-card">
<h4>👤 需求：知道手机号或姓名，快速找到 userId 用于发消息或派任务</h4>
<pre><code># 通过手机号查 userId
dws contact user get-by-mobile --mobile 13800138000 --format json
搜索用户（按姓名）
dws contact user search --keyword "张煜" --format json
获取当前用户信息
dws contact user get-self --format json
查询部门成员
dws contact department members --dept-id 1 --format json
搜索共同群（知道几个人的花名，查共同在哪些群）
dws chat search-common --nicks "张煜,李四" --format json
适用命令contact user get-by-mobile / user search / chat search-common
<h3>场景14：群消息审计 — Chat 消息管理</h3>
<div class="scenario-card">
<h4>🔍 需求：审计某群在某时间段内的所有消息，排查异常发言</h4>
<pre><code># 搜索群
dws chat search --query "运维故障处理" --format json
查看群成员
dws chat group members list --id <openconversation_id> --format json
按时间范围拉取群消息
dws chat message list \
--group <openconversation_id> \
--time "2026-04-30 00:00:00" \
--format json
关键词搜索消息
dws chat message search \
--keyword "异常" \
--group <openconversation_id> \
--start "2026-04-30T00:00:00+08:00" \
--end "2026-04-30T23:59:59+08:00" \
--format json
拉取 @我的消息
dws chat message list-mentions \
--start "2026-04-30T00:00:00+08:00" \
--end "2026-04-30T23:59:59+08:00" \
--format json
导出群聊消息（脚本）
python scripts/chat_export_messages.py \
--query "运维故障处理" \
--time "2026-04-30 00:00:00"
适用命令chat message list / search / list-mentions / scripts/chat_export_messages.py
<div class="section">
<h2>五、危险操作清单与安全规范</h2>
<p>以下操作不可逆或高影响，AI 执行前<strong>必须先展示操作摘要并获得用户明确同意</strong>：</p>
<table>
<tr>
<th>产品</th>
<th>命令</th>
<th>风险说明</th>
</tr>
<tr>
<td>aitable</td>
<td><code>base delete / table delete / field delete / record delete</code></td>
<td>删除后数据无法恢复</td>
</tr>
<tr>
<td>calendar</td>
<td><code>event delete / room delete / participant delete</code></td>
<td>参与者同步收到取消通知</td>
</tr>
<tr>
<td>chat</td>
<td><code>group members remove / message recall-by-bot</code></td>
<td>成员被踢出无法自动恢复，消息撤回不可逆</td>
</tr>
<tr>
<td>doc</td>
<td><code>block delete</code></td>
<td>文档块永久删除</td>
</tr>
<tr>
<td>ding</td>
<td><code>message recall</code></td>
<td>DING 消息撤回</td>
</tr>
<tr>
<td>oa</td>
<td><code>approval revoke / approval reject</code></td>
<td>撤销自己发起的审批；拒绝他人审批</td>
</tr>
<tr>
<td>todo</td>
<td><code>task delete</code></td>
<td>待办永久删除</td>
</tr>
<tr>
<td>minutes</td>
<td><code>replace-text</code></td>
<td>全文批量替换转写与摘要</td>
</tr>
</table>
<div class="warning">
<strong>操作前确认流程：</strong><br>
Step 1 → 展示操作摘要（操作类型 + 目标对象 + 影响范围）<br>
Step 2 → 用户明确回复确认（如 "确认" / "好的"）<br>
Step 3 → 加 <code>--yes</code> 执行命令
</div>
</div>
<div class="section">
<h2>六、自动化脚本生态</h2>
<p>DWS 的 <code>scripts/</code> 目录提供了批量操作的 Python 脚本，适合定时任务和复杂场景：</p>
<table>
<tr>
<th>脚本</th>
<th>场景</th>
</tr>
<tr>
<td><code>chat_export_messages.py</code></td>
<td>导出群聊消息到 JSON 文件</td>
</tr>
<tr>
<td><code>chat_history_with_user.py</code></td>
<td>查询与某人的单聊记录</td>
</tr>
<tr>
<td><code>todo_daily_summary.py</code></td>
<td>查看今天/明天/本周未完成待办汇总</td>
</tr>
<tr>
<td><code>todo_batch_create.py</code></td>
<td>从 JSON 文件批量创建待办</td>
</tr>
<tr>
<td><code>todo_overdue_check.py</code></td>
<td>扫描逾期待办输出逾期清单</td>
</tr>
<tr>
<td><code>attendance_my_record.py</code></td>
<td>查看我今天/指定日期的考勤记录</td>
</tr>
<tr>
<td><code>attendance_team_shift.py</code></td>
<td>查询团队成员本周排班</td>
</tr>
</table>
</div>
<div class="section">
<h2>七、意图判断速查表</h2>
<p>面对业务需求时，快速确定应该使用哪个命令：</p>
<table>
<tr>
<th>需求描述</th>
<th>路由命令</th>
</tr>
<tr>
<td>发群消息/单聊消息（个人身份）</td>
<td><code>chat message send</code></td>
</tr>
<tr>
<td>机器人发消息/群发</td>
<td><code>chat message send-by-bot</code></td>
</tr>
<tr>
<td>Webhook 告警通知</td>
<td><code>chat message send-by-webhook</code></td>
</tr>
<tr>
<td>紧急通知（电话/短信）</td>
<td><code>ding message send --type call/sms</code></td>
</tr>
<tr>
<td>建群/搜群/群管理</td>
<td><code>chat group create / search / rename</code></td>
</tr>
<tr>
<td>创建待办/任务</td>
<td><code>todo task create</code></td>
</tr>
<tr>
<td>审批/驳回工单</td>
<td><code>oa approval list-pending → tasks → approve/reject</code></td>
</tr>
<tr>
<td>考勤打卡记录</td>
<td><code>attendance record get / shift list</code></td>
</tr>
<tr>
<td>搜索同事/找 userId</td>
<td><code>contact user search / user get-by-mobile</code></td>
</tr>
<tr>
<td>发送邮件</td>
<td><code>mail send</code></td>
</tr>
<tr>
<td>日志/日报提交</td>
<td><code>report create</code></td>
</tr>
<tr>
<td>钉钉文档读写</td>
<td><code>doc node get / block create</code></td>
</tr>
<tr>
<td>云盘文件上传/下载</td>
<td><code>drive upload-info / commit / download</code></td>
</tr>
</table>
</div>
<div class="section">
<h2>八、总结</h2>
<p>DWS CLI 将钉钉 14 大产品能力统一封装为一致的命令行接口，特别适合以下运维场景：</p>
<div class="success">
<ul>
<li><strong>告警通知</strong>：Webhook 机器人 + DING 消息，确保 P0 故障 100% 触达</li>
<li><strong>任务管理</strong>：Todo 待办派发 + OA 审批加速工单流转</li>
<li><strong>团队协作</strong>：Calendar 值班排班 + Report 日报收集</li>
<li><strong>数据管理</strong>：Aitable AI表格 监控报表 + Drive 云盘文件归档</li>
<li><strong>审计合规</strong>：Chat 消息审计 + Attendance 考勤核查</li>
<li><strong>知识沉淀</strong>：Doc 钉钉文档 故障复盘 + Minutes AI听记 会议纪要</li>
</ul>
</div>
<p>结合 OpenClaw 的 Cron 定时任务能力，可以将日常运维操作自动化，彻底告别重复性手工劳动。</p>
<div class="info">
<strong>参考资料：</strong>
<ul style="margin-top:10px">
<li>DWS Skill 文档：<code>~/.agents/skills/dws/SKILL.md</code></li>
<li>产品命令参考：<code>~/.agents/skills/dws/references/products/*.md</code></li>
<li>钉钉开放平台文档：<code>dws devdoc search --query "关键词"</code></li>
</ul>
</div>
</div>