ClawHub

dingtalk-cli

Data & APIs

当用户提到钉钉知识库、钉钉文档、读取/写入文档、知识库目录、文档成员、`.axls` 表格、workbook、dingtalk doc、wiki workspace 时使用。通过本地 `dingtalk-cli` 命令调用钉钉开放平台 API，适合 agent 直接执行。

Install

openclaw skills install dingtalk-cli

dingtalk-cli

dingtalk-cli 是面向 agent 的钉钉文档 CLI，覆盖：

  • 知识库列表与详情
  • 节点查询、URL 反查
  • 文档创建、正文读取、Markdown 覆盖写入、删除
  • .axls 钉钉表格的 workbook/sheet/range 读取
  • 文档成员添加、更新、移除

安装

pip install dingtalk-cli

如需从源码开发安装：

pip install -e .

启动前配置

优先使用命令保存配置：

dingtalk-cli auth setup \
  --app-key <APP_KEY> \
  --app-secret <APP_SECRET> \
  --operator-union-id <UNION_ID>

如果只有 userId：

dingtalk-cli auth setup \
  --app-key <APP_KEY> \
  --app-secret <APP_SECRET> \
  --operator-user-id <USER_ID>

配置会写到 ~/.dingtalk-cli/config.json。也可用环境变量覆盖：

  • DINGTALK_APP_KEY
  • DINGTALK_APP_SECRET
  • DINGTALK_OPERATOR_ID
  • DINGTALK_CLI_CONFIG_DIR

注意：

  • 写操作必须带真实用户身份 operatorId，且应为 unionId
  • 输出中不会打印完整凭证，只显示脱敏值

常用命令

# 看知识库
dingtalk-cli workspace list --all

# 用 URL 反查节点
dingtalk-cli node resolve-url "https://alidocs.dingtalk.com/i/nodes/xxx"

# 读取文档正文
dingtalk-cli doc read --url "https://alidocs.dingtalk.com/i/nodes/xxx"

# 覆盖写入文档
dingtalk-cli doc overwrite --doc-key <DOC_KEY> --content-file /abs/path/content.md --yes

# 若立即删除刚创建的文档，优先使用 create 返回的 workspace_id + node_id
dingtalk-cli doc delete --workspace-id <WORKSPACE_ID> --node-id <NODE_ID> --yes

# 读取 .axls 表格
dingtalk-cli workbook read --node-id <NODE_ID> --range A1:Z80

# 添加成员
dingtalk-cli member add --node-id <NODE_ID> --member-id <USER_ID> --role editor

Agent 使用约定

  • 优先使用 --json
  • 对破坏性命令显式传 --yes
  • 读取普通文档用 doc
  • 读取 .axls 用 workbook
  • 若 doc read 返回“目标节点是 .axls”，不要重试同一命令，直接切到 workbook
  • 对创建命令返回的结果，立即读写时优先使用 doc_key
  • 对创建后立即删除的场景，优先使用返回的 workspace_id + node_id

错误提示

  • MissingoperatorId：未配置 operator unionId
  • paramError：把 userId 当成 unionId 传了
  • Forbidden.AccessDenied.AccessTokenPermissionDenied：应用权限不够
  • Target document should be doc.：目标不是普通文档，通常应改走 workbook
More in Data & APIs