Skip to content

reference.md

Latest commit

 

History

History
158 lines (119 loc) · 10.6 KB

reference.md

File metadata and controls

158 lines (119 loc) · 10.6 KB
Raw

Reference / 参考手册

Environment Variables / 环境变量

Variable Purpose / 用途
DWS_CONFIG_DIR Override default config directory / 覆盖默认配置目录
DWS_AGENT_PRODUCT Optional, caller-declared Agent product sent through the existing HTTP claw-type header (for example qwenwork). Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match ^[A-Za-z0-9][A-Za-z0-9_-]*$. Unset or empty values preserve the edition default (openClaw in the open-source build). / 可选、由调用方声明的 Agent 产品标识，经校验后覆盖 HTTP claw-type 请求头；未设置或为空时保持当前发行版默认值
DWS_AGENT_HOST Optional, caller-declared Agent runtime form sent as x-dws-agent-host (for example cloud or desktop). Surrounding ASCII spaces/tabs are trimmed; the remaining value must be at most 64 bytes and match ^[a-z0-9][a-z0-9_-]*$; unset values are omitted. / 可选、由调用方声明的 Agent 运行形态，经校验后作为 x-dws-agent-host 发送；未设置时省略
DWS_<PRODUCT>_MCP_URL Override a product MCP endpoint for local development / 本地开发时覆盖指定产品 MCP endpoint
DWS_CLIENT_ID OAuth client ID (DingTalk AppKey)
DWS_CLIENT_SECRET OAuth client secret (DingTalk AppSecret)
DWS_TRUSTED_DOMAINS Comma-separated trusted domains for bearer token (default: *.dingtalk.com). * for dev only / Bearer token 允许发送的域名白名单，默认 *.dingtalk.com，仅开发环境可设为 *
DWS_ALLOW_HTTP_ENDPOINTS Set 1 to allow HTTP for loopback during dev / 设为 1 允许回环地址 HTTP，仅用于开发调试
DWS_DISABLE_KEYCHAIN macOS only. Set 1 to skip system Keychain for the encryption key and use file-based storage (same scheme as Linux). For sandboxed runtimes (e.g. Codex App) that block Keychain APIs. Weakens at-rest protection — DEK and ciphertext live in the same directory. / 仅 macOS。设为 1 时跳过系统 Keychain，密钥以文件形式存储（与 Linux 一致）。用于 Keychain API 被拦截的沙盒环境（如 Codex App）。代价是 DEK 与密文同目录，保护强度低于默认方案

Agent Product and Host trust model / Agent 产品与运行形态的信任模型

DWS_AGENT_PRODUCT and DWS_AGENT_HOST are caller-declared selection and observation signals. They are not credentials, attestations, or proof of the calling host's identity. DingTalk services may record them for logs/BI and may combine supported values with separately authenticated context for PAT compatibility, PAT identity/source derivation, or Discovery eligibility. A service must allowlist supported values and must never grant access, bypass authentication, or skip authorization solely because either Header claims a particular product or runtime form. They are not used to select ordinary MCP tool endpoints.

DWS_AGENT_PRODUCT controls only the HTTP claw-type Header. The similarly named clawType tool argument on IM send operations is an independent message-display axis used for the “Send from AI” label. It remains controlled by the active edition's ClawTypeValue and --ai-tag; changing DWS_AGENT_PRODUCT does not change that message label.

For QwenWork, report the dimensions separately:

DWS_AGENT_PRODUCT=qwenwork
DWS_AGENT_HOST=cloud       # or desktop

Do not set arbitrary product values that the target service has not explicitly enabled. Older combined Host labels such as qwenwork_cloud still satisfy the generic syntax for compatibility, but new integrations should use the two-dimensional convention above.

DWS_AGENT_PRODUCT 和 DWS_AGENT_HOST 均由调用方声明，不是认证凭据，也不能证明 真实宿主身份。服务端可以在独立认证上下文中将受支持值用于日志/BI、PAT 兼容策略、 PAT 身份/来源派生或 Discovery 准入，但不得仅凭这两个 Header 放权、绕过认证或跳过 授权。HTTP claw-type 与 IM 消息发送参数 clawType 是两个独立维度；后者仅控制 “Send from AI”展示，仍由发行版 ClawTypeValue 和 --ai-tag 决定。

Exit Codes / 退出码

Code Category Description / 描述
0 Success Command completed successfully / 命令执行成功
1 API MCP tool call or upstream API failure / MCP 工具调用或上游 API 失败
2 Auth Authentication or authorization failure / 身份认证或授权失败
3 Validation Invalid input, flags, or parameter schema mismatch / 输入参数校验失败
4 PAT PAT authorization interception; stderr carries raw machine-readable PAT JSON / PAT 授权拦截；stderr 返回原始机器可解析 JSON
5 Internal Unexpected internal error / 未预期的内部错误
6 Discovery Static endpoint resolution or protocol negotiation failure / 静态端点解析或协议协商失败

With -f json, error responses include structured payloads: category, reason, hint, actions.

使用 -f json 时，错误响应包含结构化字段：category、reason、hint、actions。

Output Formats / 输出格式

dws contact user search --query "Alice" -f table   # Table (default, human-friendly / 表格，默认)
dws contact user search --query "Alice" -f json    # JSON (for agents and piping / 适合 agent)
dws contact user search --query "Alice" -f raw     # Raw API response / 原始响应
dws schema -f pretty "calendar event create"         # Pretty Agent schema view / Agent Schema 彩色查看

Dry Run / 试运行

dws todo task list --dry-run    # Preview MCP call without executing / 预览但不执行

Output to File / 输出到文件

dws contact user search --query "Alice" -o result.json

Schema Introspection / Schema 查询

--help 展示当前二进制的 Cobra 命令和可接受 flag，dws schema 查询同版本内嵌的 Agent 命令契约。Schema 查询不访问 MCP endpoint、不执行 tools/list，也不搜索钉钉文档或任何业务数据。

Schema 的稳定 canonical_path、主 CLI 路径和 aliases 来自 reviewed CommandRegistry，并在发布时逐项绑定当前 Cobra tree。编辑 internal/cli/schema_command_registry.json 时必须遵守同目录的 schema_command_registry.schema.json；普通生成流程只校验该 reviewed input，不会覆盖它。Native annotation 只做实现一致性校验；Catalog 是该统一强类型契约的发布输出，不作为命令发现或下一轮生成的输入。

路径写法

dws schema                                      # 当前公开产品面的紧凑概览
dws schema calendar                             # 展开一个产品
dws schema "calendar event"                     # 展开一个命令分组
dws schema "calendar event create"              # 按 CLI 空格路径查询工具
dws schema calendar.create_calendar_event       # 按 canonical path 查询工具
dws schema --cli-path "calendar event create"   # 显式 CLI path
dws schema "calendar event create" --compact    # 支持：省略 provenance/debug 字段
dws schema --all                                # 全部工具的完整 leaf Schema，用于审计/CI/baseline

兼容入口 dws schema list 等价于根概览。schema --all 是完整导出：每个工具都包含完整 leaf 参数、约束和安全语义。它输出很大，只用于明确要求的全量导出、审计、CI 或参数 baseline；普通 Agent 任务应按概览、产品/分组、leaf 渐进查询，不要把 --all 直接注入上下文。schema --all --compact 虽受支持，但会裁掉 provenance 和接口映射字段，不能作为完整 baseline。

Leaf 查询、--all 中对应工具和 Catalog full tool 均由同一个 resolved ToolSpec 投影，内容必须一致；概览、产品/分组和 Catalog summary 也由该 ToolSpec 的统一 summary 投影生成。通过 alias 查询时，只允许 cli_path 和 is_alias 发生视图变化，参数、安全和接口契约不得变化。

--compact 是 Schema 的展示选项。当前版本支持该 flag；若兼容旧二进制时收到 unknown_flag: --compact，用同一个 Schema 查询去掉 --compact 重试。这只降低输出裁剪能力，不表示 leaf 不存在，也不能改用 Schema 查询业务数据。

Schema、Help 与业务数据的边界

问题 事实源
命令是否由当前二进制暴露、Cobra 接受哪些 flags dws <path> --help
Agent 选哪个命令、参数映射与组合约束、risk/confirmation 对应的 leaf dws schema "<path>"
当前钉钉中的文档、文件、日程、消息等业务数据 实际执行 dws doc read、dws drive search 等 read/search/list 命令

Schema 与 Help 冲突表示发布契约漂移，不能静默猜测。执行参数必须以 Cobra 实际接受的 flag 为准；安全语义冲突时采用更保守的处理（例如先确认）或停止执行并报告漂移。完成命令发现后，仍必须执行真实业务命令；dws schema 本身不会读取或搜索业务内容。

单工具输出字段

字段 说明
canonical_path / primary_cli_path / aliases 稳定工具 ID、主 CLI 路径和兼容路径
product_id / interface_ref CLI 产品与实际 MCP product/RPC binding
title / description / agent_summary 人类说明、接口说明和 Agent 摘要
parameters.<flag> CLI flag 的类型、属性名、required、默认值、格式、枚举和条件必填
constraints one-of、互斥、联动等组合约束
effect / risk / confirmation / idempotency Agent 执行与安全策略
use_when / avoid_when / examples Agent 选择提示和示例
reviewed / agent_source_refs 语义审核状态与来源追踪

parameters.<flag>.required 是按来源 precedence 解析后的 Agent 参数契约；cli_required=true 才表示 Cobra 将该 flag 标记为硬必填。条件必填或别名选择通过 required_when 和 constraints.require_one_of 表达。required 不直接复制 MCP input schema，也不取代 Cobra 的实际执行校验。

筛选输出

dws schema "calendar event create" --jq '.parameters'                              # 只看参数
dws schema "calendar event create" --jq '[.parameters | to_entries[] | select(.value.required)]'  # 只看 Agent required 参数

Shell Completion / 自动补全

# Bash
dws completion bash > /etc/bash_completion.d/dws

# Zsh
dws completion zsh > "${fpath[1]}/_dws"

# Fish
dws completion fish > ~/.config/fish/completions/dws.fish