dingtalk-workspace-cli/docs/devapp-agent-install-guide.md

dws dev 一键安装与 Agent 接入指南

面向希望用 Codex、Claude、Cursor 等开发 Agent 管理钉钉开放平台应用的开发者。

这份指南参考 Notion Developer Platform 的引导方式：先给出一条可复制的安装命令，再用最短路径完成验证、登录、Agent 调用和排障。

一键安装

dws dev 能力已经合入主干并随正式版发布。专用安装脚本会下载预编译二进制 + dingtalk-misc skill（开放平台应用文档落在 misc），只需要 curl + tar，不需要 git / go / make。

macOS / Linux

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

Windows（PowerShell）

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

这个脚本会：

1. 从 DingTalk-Real-AI/dingtalk-workspace-cli 的最新 Release 下载对应平台的预编译二进制。
2. 安装 dws 到默认目录 ~/.local/bin。
3. 从 Release 的 skills 包里安装 dingtalk-misc skill 到本机已检测到的 Agent 目录。

支持这些环境变量（全部可选）：

变量	说明
DEVAPP_REPO	覆盖发布仓库，默认 DingTalk-Real-AI/dingtalk-workspace-cli
DEVAPP_VERSION	钉某个 release tag，默认取最新 release
DWS_INSTALL_DIR	二进制安装目录，默认 ~/.local/bin
DWS_NO_SKILLS	设为 1 跳过 dingtalk-misc skill 安装

dws dev 已在正式版里，所以你也可以直接用标准安装脚本 install.sh，二者都会带上 dws dev。

国内加速

dws dev 已在正式版里，国内用户直接用标准安装脚本的 Gitee 镜像即可（二进制和 skill 都从 Gitee 拉，避免 GitHub 网络问题）：

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 可执行：

dws version

确认 dws dev app 命令存在：

dws dev app --help --format json

如果能看到 list、get、create、update、permission、member、robot、security、version、webapp、event、credentials 等子命令，说明已安装成功。

确认登录状态：

dws auth status

如果尚未登录：

dws auth login

登录完成后读取应用列表：

dws dev app list --format json

dws dev 是什么

dws dev 是钉钉开放平台开发者命令组，三块能力：

• dws dev app — 开放平台企业内部应用的全生命周期管理（创建、配置、权限、成员、安全、机器人、版本发布、事件订阅）。
• dws dev connect — 把现成机器人接到当前本地 agent（起 Stream 连接做本地转发，不建号、不产生审批工单）。
• dws dev doc — 开放平台开发文档搜索。

安装后，开发者和 Agent 可以用统一命令管理企业内部应用，而不需要反复进入开发者后台页面。它让 Agent 可以完成这些工作：

• 查询、创建、更新、启用、停用、删除开放平台应用。
• 查询应用凭证，读取 clientId / appKey，敏感凭证走专用命令。
• 配置网页应用首页和管理后台地址。
• 查询、申请、移除权限点。
• 管理应用成员。
• 配置安全项，包括 IP 白名单、登录重定向 URL、端内免登地址。
• 异步创建机器人、配置/启停现有机器人。
• 创建版本、发起发布、查询审批和发布状态。

给 Agent 使用

安装完成后，可以直接让 Agent 操作 dws dev。

示例：

帮我查一下最近创建的开放平台应用。

帮我给 unifiedAppId=<unifiedAppId> 的应用配置机器人，先 dry-run 给我确认。

帮我查询这个应用缺哪些权限点，并申请 Contact.User.mobile。

帮我发布这个应用版本，先预检是否需要审批。

Agent 写操作必须遵循：

1. 先查询定位应用。
2. 先 dry-run 预览。
3. 明确展示将要修改的应用、字段和值。
4. 用户确认后加 --yes 执行。
5. 执行后回读验证。

第一个写操作

推荐用机器人配置作为 smoke test。建号是异步的，分两步。

提交建号任务（记下返回的 taskId）：

dws dev app robot submit \
  --name "告警助手" \
  --robot-name "告警机器人" \
  --desc "处理告警通知和事件回调" \
  --dry-run \
  --format json

确认预览无误后去掉 --dry-run、加 --yes 执行，再用返回的 taskId 查结果，直到 status 变成 SUCCESS：

dws dev app robot result --task-id <taskId> --format json

对已有机器人的应用，改配置/启停用 robot config / robot enable / robot disable：

dws dev app robot get --unified-app-id <unifiedAppId> --format json
dws dev app robot config --unified-app-id <unifiedAppId> --name "新机器人名称" --dry-run --format json

常用命令

应用管理

dws dev app list --format json
dws dev app get --unified-app-id <unifiedAppId> --format json
dws dev app create --name "考勤应用" --dry-run --format json
dws dev app update --unified-app-id <unifiedAppId> --name "新应用名" --dry-run --format json
dws dev app enable --unified-app-id <unifiedAppId> --dry-run --format json
dws dev app disable --unified-app-id <unifiedAppId> --dry-run --format json
dws dev app delete --unified-app-id <unifiedAppId> --confirm-name "<应用名>" --format json

删除不可逆，需要用 --confirm-name 传入应用名做二次确认。

凭证查询

dws dev app credentials get --unified-app-id <unifiedAppId> --format json

凭证输出可能包含敏感字段，不要把完整结果写入文档、日志或长期记忆。

权限点管理

dws dev app permission list --unified-app-id <unifiedAppId> --format json
dws dev app permission add --unified-app-id <unifiedAppId> --scope-values Contact.User.mobile --dry-run --format json
dws dev app permission remove --unified-app-id <unifiedAppId> --scope-values Contact.User.mobile --dry-run --format json

权限申请和移除只使用 scopeValue，不要传 API 名或权限分组名。

机器人能力

dws dev app robot get --unified-app-id <unifiedAppId> --format json
dws dev app robot submit --name "<智能体名>" --robot-name "<机器人名>" --desc "<描述>" --dry-run --format json
dws dev app robot result --task-id <taskId> --format json
dws dev app robot config --unified-app-id <unifiedAppId> --name "机器人名称" --dry-run --format json
dws dev app robot enable --unified-app-id <unifiedAppId> --dry-run --format json
dws dev app robot disable --unified-app-id <unifiedAppId> --dry-run --format json

成员与安全

dws dev app member list --unified-app-id <unifiedAppId> --format json
dws dev app member add --unified-app-id <unifiedAppId> --user-ids <userId> --dry-run --format json
dws dev app member remove --unified-app-id <unifiedAppId> --user-ids <userId> --dry-run --format json
dws dev app security config --unified-app-id <unifiedAppId> --redirect-urls <url> --dry-run --format json
dws dev app security config --unified-app-id <unifiedAppId> --ip-whitelist <ip> --dry-run --format json

网页应用与事件

dws dev app webapp get --unified-app-id <unifiedAppId> --format json
dws dev app webapp config --unified-app-id <unifiedAppId> --homepage-url <url> --dry-run --format json
dws dev app event list --unified-app-id <unifiedAppId> --format json
dws dev app event subscribe --unified-app-id <unifiedAppId> --dry-run --format json
dws dev app event unsubscribe --unified-app-id <unifiedAppId> --dry-run --format json

版本发布

dws dev app version list --unified-app-id <unifiedAppId> --format json
dws dev app version create --unified-app-id <unifiedAppId> --dry-run --format json
dws dev app version check-approval --unified-app-id <unifiedAppId> --version-id <versionId> --format json
dws dev app version publish --unified-app-id <unifiedAppId> --version-id <versionId> --dry-run --format json
dws dev app version status --unified-app-id <unifiedAppId> --version-id <versionId> --format json

发布前先用 version check-approval 预检是否需要审批。含高敏权限的版本，publish 需加 --confirmed-sensitive。

安全边界

dws dev 的目标不是绕过开发者后台权限，而是让 CLI、MCP 和 Web 后台保持一致。

默认安全策略：

• 写操作先 dry-run。
• 删除、停用、发布必须由用户确认（删除还需 --confirm-name 二次确认）。
• Agent 不接收用户手动传入的 access token、cookie、clientSecret、appSecret。
• 应用定位优先使用 unifiedAppId、agentId、appKey。
• 对权限点申请、成员变更、安全配置、版本发布记录操作结果，便于审计和回滚。

排障

dws dev app 不存在

先确认装上的是带 dws dev 的版本：

dws version
dws dev app --help --format json

如果命令缺失，重新执行本文的一键安装命令（或标准 install.sh）升级到最新正式版。

dws dev app list 失败

优先检查登录态：

dws auth status
dws auth login

然后确认当前账号能访问目标企业，并且当前用户在目标企业内。

提示"当前用户没有开发者身份"

创建应用需要开放平台开发者权限。请企业管理员在钉钉开放平台（open-dev.dingtalk.com）的「权限管理」中把你的账号添加为开发者，然后重试。

页面能操作，但 CLI 或 MCP 提示无权限

通常说明 CLI/MCP 后端鉴权和 Web 后台权限没有对齐。先确认当前用户是否满足以下任一条件：

• 应用 owner。
• 应用管理员。
• 应用开发者。
• 企业管理员或具备开放平台应用管理权限的角色。

机器人配置失败

先查当前机器人状态：

dws dev app robot get --unified-app-id <unifiedAppId> --format json

如果机器人不存在，用 robot submit 异步创建；如果已存在，用 robot config 修改，或用 robot enable 重新启用。

页面文案建议

用于产品页顶部：

Install dws dev in one command.

Let your coding agents manage DingTalk Open Platform apps from the terminal:
create apps, configure robots, apply permissions, manage security settings,
and publish versions with dry-run safety built in.

中文版本：

一行命令接入 dws dev。

让 Codex、Claude、Cursor 等开发 Agent 直接管理钉钉开放平台应用：
创建应用、配置机器人、申请权限、管理安全配置、发布版本。
所有写操作先预览，再确认执行。

参考

• Notion Developer Platform: https://www.notion.com/product/dev
• Notion CLI Help: https://www.notion.com/help/use-notion-from-your-terminal-with-notion-cli
• Notion Developer Platform Blog: https://www.notion.com/blog/introducing-developer-platform