架构概述

External CLI Connectors 是 OpenClaw.NET 的一个受控原生工具 (external_cli)，用于将官方平台 CLI（如 GitHub CLI、Azure CLI、kubectl、Stripe CLI、Lark/Feishu CLI 等）包装为可被 AI Agent 安全调用的工具。

核心设计哲学：

• 默认禁用 — 功能不会自动启用，需要显式配置
• 不是通用 Shell — 不接受任意命令字符串，只允许预配置的具名命令
• 深度防御 — 通过命名命令白名单、风险评分、预览、审批、脱敏、超时、审计记录和运行时事件实现多层安全控制

---

二、安全模型 (Security Model)

2.1 核心安全原则

外部 CLI 可以在强大的用户、机器人、云、集群或支付身份下运行，因此：

• 所有变更性命令 (mutating commands) 被视为高风险
• 使用最小权限原则 (least privilege)
• 支持 dry-run 预览、审批流程 和 审计日志

2.2 命令调用方式

连接器不接受原始命令字符串。Agent 通过指定连接器名、命令名和命名参数来调用：

{
  "action": "execute",
  "connector": "gh",
  "command": "issue_list",
  "parameters": {
    "repo": "clawdotnet/openclaw.net"
  }
}

运行时通过配置化的参数模板直接展开为 ProcessStartInfo.ArgumentList，不经过 Shell 解释器，且拒绝缺失或未知参数（除非命令显式允许）。

2.3 关键安全默认值

配置项	默认值	含义
Enabled	false	默认不注册工具
AllowFreeformCommands	false	拒绝自由形式命令
RequireApprovalForMutatingCommands	true	非只读命令需要审批
RiskLevel	high	默认高风险，总是需要审批
ReadOnly	false	默认可变操作

---

三、配置系统详解

3.1 顶层配置结构

{
  "OpenClaw": {
    "ExternalCli": {
      "Enabled": true,                          // 总开关
      "DefaultTimeoutSeconds": 60,              // 默认超时
      "MaxStdoutBytes": 262144,                 // stdout 最大字节数 (256KB)
      "MaxStderrBytes": 65536,                  // stderr 最大字节数 (64KB)
      "RedactSecrets": true,                    // 启用密钥脱敏
      "AllowFreeformCommands": false,           // 禁止自由命令
      "RequireApprovalForMutatingCommands": true, // 变更命令需审批
      "Connectors": {                           // 连接器配置
        // 各平台CLI连接器定义
      }
    }
  }
}

3.2 连接器配置结构

以 GitHub CLI (gh) 为例：

{
  "gh": {
    "Enabled": true,
    "DisplayName": "GitHub CLI",
    "Executable": "gh",
    "DefaultOutputFormat": "json",
    "StatusCommand": {
      "Args": ["auth", "status"],
      "TimeoutSeconds": 20
    },
    "VersionCommand": {
      "Args": ["--version"],
      "TimeoutSeconds": 10
    },
    "Commands": {
      "repo_view": {
        "Description": "View repository metadata",
        "ArgsTemplate": [
          "repo", "view", "{{repo}}",
          "--json", "name,owner,description,url,isPrivate"
        ],
        "RiskLevel": "low",
        "ReadOnly": true,
        "StructuredOutput": "json",
        "Parameters": {
          "repo": {
            "Required": true,
            "Pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
          }
        }
      },
      "issue_create": {
        "Description": "Create a GitHub issue",
        "ArgsTemplate": [
          "issue", "create", "--repo", "{{repo}}",
          "--title", "{{title}}", "--body", "{{body}}"
        ],
        "RiskLevel": "medium",
        "ReadOnly": false,
        "RequiresApproval": true,
        "StructuredOutput": "text",
        "Parameters": {
          "repo": { "Required": true },
          "title": { "Required": true, "MaxLength": 200 },
          "body": { "Required": true, "MaxLength": 16000 }
        }
      }
    }
  }
}

3.3 命令配置选项说明

字段	类型	说明
Description	string	命令描述
ArgsTemplate	string[]	参数模板，{{param}} 占位符将被替换
RiskLevel	string	风险等级: low / medium / high
ReadOnly	bool	是否为只读操作
RequiresApproval	bool	是否需要审批（覆盖默认策略）
StructuredOutput	string	输出格式: json / ndjson / csv / table / text
DryRunArgsTemplate	string[]	(可选) Dry-run 模式的参数模板
Parameters	dict	参数定义，含 Required/MaxLength/Pattern/AllowedValues
RedactionRules	string[]	(可选) 平台特定的密钥脱敏规则
RequiredScopes	string[]	(可选) 所需身份/权限范围
RequiredIdentity	string	(可选) 所需身份标识
TimeoutSeconds	int	(可选) 命令级别超时覆盖
WorkingDirectory	string	(可选) 工作目录
Environment	dict	(可选) 环境变量

3.4 参数验证选项

每个参数可配置：

• Required — 是否必填
• Description — 参数描述
• MaxLength — 最大长度限制
• Pattern — 正则表达式验证
• AllowedValues — 允许值列表

---

四、预览与审批流程 (Preview & Approval)

4.1 预览命令

openclaw external preview gh repo_view --param repo=clawdotnet/openclaw.net

4.2 预览返回信息

字段	说明
可执行文件路径	解析后的 CLI 路径
参数列表	展开的参数（已脱敏）
风险等级	low / medium / high
操作类型	只读 (ReadOnly) 或变更 (Mutating)
是否需要审批	true / false
输出格式	json / ndjson / csv / table / text
所需身份/权限范围	如配置了 RequiredScopes
审批指纹 (Approval Fingerprint)	稳定的指纹值，用于审批匹配

4.3 执行审批流程

# 1. 先预览
openclaw external preview gh issue_create \
  --param repo=clawdotnet/openclaw.net \
  --param title="Example" \
  --param body="Example body"

# 2. 确认后加 --yes 执行（自动携带指纹）
openclaw external execute gh issue_create \
  --param repo=clawdotnet/openclaw.net \
  --param title="Example" \
  --param body="Example body" \
  --yes

指纹安全机制： 如果命令模板、解析参数或策略在审批和执行之间发生变化，指纹不匹配将导致执行被阻止。

4.4 Dry-Run 支持

预览时加上 --dry-run 可执行 dry-run 模式（需命令配置了 DryRunArgsTemplate）：

openclaw external preview gh issue_create \
  --param repo=clawdotnet/openclaw.net \
  --param title="Test" \
  --param body="Test body" \
  --dry-run

注意： 运行时不会猜测 dry-run 标志，必须在模板中显式配置。

---

五、审计、事件与脱敏 (Audit, Events & Redaction)

5.1 审计记录 (Append-Only Audit)

每次执行写入不可篡改的审计记录，包含：

• 连接器名和命令名
• 可执行文件路径
• 已脱敏的命令行预览
• 参数和参数哈希
• 执行者、会话、频道、发送者
• 审批指纹（如有）
• 退出码、执行时长、超时标志
• stdout/stderr 截断标志
• 风险等级和工作目录

5.2 运行时事件

触发以下事件类型：

• status_check — 状态检查
• previewed / dry_run_previewed — 预览
• dry_run_executed — Dry-run 执行
• command_executed — 命令执行
• command_failed — 命令失败
• command_timed_out — 超时
• truncation — 输出截断
• redaction — 密钥脱敏
• command_blocked_by_policy — 策略阻止

5.3 密钥脱敏 (Redaction)

脱敏应用于：参数预览、stdout、stderr、审计记录、运行时事件、错误消息。可为连接器或命令配置 RedactionRules，支持平台特定的密钥格式。

---

六、输出解析 (Output Parsing)

按命令配置 StructuredOutput：

格式	处理方式
json	解析 stdout 为 JSON，返回解析后的 JSON + 脱敏 stdout
ndjson	解析换行分隔 JSON 为 JSON 数组
csv / table / text	作为脱敏文本返回

注意： 连接器不会注入全局 --json 标志，需要在每个命令模板中显式放置输出标志。

---

七、推荐配置预设 (Conservative Presets)

7.1 GitHub CLI (gh)

类别	命令示例
只读	auth status, repo view, issue list, pr list, pr view, release list
需审批	issue create, issue comment, pr review, pr merge, release create

7.2 Azure CLI (az)

类别	命令示例
只读	account show, group list, resource list, webapp list
需审批	resource create/update/delete, deployment create, role assignment changes

7.3 kubectl

类别	命令示例
只读	config current-context, get pods/services/deployments -o json, describe
高风险需审批	apply, delete, scale, rollout restart, exec, port-forward

日志可能暴露密钥，建议至少 medium 风险等级。

7.4 Stripe CLI

类别	命令示例
只读	listen status, fixtures/list, customers/list（最小权限凭证）
高风险需审批	payment mutations, refunds, customer/subscription mutations, webhook trigger, event replay

7.5 Lark / Feishu CLI

类别	命令示例
只读	auth status, schema inspection, calendar agenda, docs search/read, sheets read, mail search/read, meeting minutes query
需审批	send messages, write docs, write sheets, send email, approve/reject workflows, create/update OKRs, raw API calls

---

八、管理 API (Admin API)

网关暴露以下 RESTful 端点：

方法	端点	说明
GET	/admin/external-cli/connectors	列出