首页 > 基础资料博客日记

OpenClaw.NET 外部 CLI 预设系统：从零编写第三方 CLI 集成指南

2026-05-16 21:30:01基础资料围观1次

文章OpenClaw.NET 外部 CLI 预设系统：从零编写第三方 CLI 集成指南分享给大家，欢迎收藏极客资料网，专注分享技术知识

本文基于 OpenClaw.NET Commit 113151c7 及 GitHub 仓库 clawdotnet/openclaw.net，系统讲解 External CLI Preset 系统的架构设计与扩展方法，并以 Terraform CLI 为例演示完整的自定义预设开发流程。

1. 引言：从手动配置到预设即代码

当大型语言模型（LLM，Large Language Model）通过工具调用（tool calling）机制与外部世界交互时，命令行界面（CLI，Command Line Interface）工具往往是功能最丰富、覆盖最广的集成目标。GitHub CLI、Azure CLI、kubectl 等工具经过数年迭代，其命令面和参数设计已经高度成熟。然而，将每一个 CLI 命令安全地接入 AI 网关，从来不是一件轻松的事。OpenClaw.NET 的 External CLI Preset（外部 CLI 预设）系统正是为回答这个问题而生：如何在保持安全基线的前提下，将繁琐的手动配置压缩为一句声明。

1.1 手动配置的痛点

1.1.1 逐行编写 ArgsTemplate 的繁琐

在预设系统出现之前，开发者需要为每条 CLI 命令在 appsettings.json 的 Connectors 字典中手写完整配置。以 GitHub CLI（gh）为例，若要暴露 6 条常用命令——查看仓库元数据（repo_view）、列举议题（issue_list）、列举拉取请求（pr_list）、查看拉取请求详情（pr_view）、列举发布版本（release_list）以及添加评论（issue_comment）——手动配置的规模如下所示：

"Connectors": {
  "gh": {
    "Enabled": true,
    "Executable": "gh",
    "DefaultOutputFormat": "Json",
    "Commands": {
      "repo_view": {
        "ArgsTemplate": ["repo", "view", "{{repo}}", "--json", "name,owner,description,url,isPrivate"],
        "Parameters": { "repo": { "Required": true, "Pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" } },
        "OutputFormat": "Json"
      },
      "issue_list": {
        "ArgsTemplate": ["issue", "list", "--repo", "{{repo}}", "--json", "number,title,state,author,url,labels"],
        "Parameters": { "repo": { "Required": true, "Pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" } },
        "OutputFormat": "Json"
      },
      "pr_list": {
        "ArgsTemplate": ["pr", "list", "--repo", "{{repo}}", "--json", "number,title,state,author,url,headRefName,baseRefName"],
        "Parameters": { "repo": { "Required": true, "Pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" } },
        "OutputFormat": "Json"
      },
      "pr_view": {
        "ArgsTemplate": ["pr", "view", "{{number}}", "--repo", "{{repo}}", "--json", "number,title,state,url,mergeStateStatus,reviewDecision,headRefName,baseRefName"],
        "Parameters": {
          "repo": { "Required": true, "Pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
          "number": { "Required": true, "Pattern": "^[0-9]+$" }
        },
        "OutputFormat": "Json"
      },
      "issue_comment": {
        "ArgsTemplate": ["issue", "comment", "{{number}}", "--repo", "{{repo}}", "--body", "{{body}}"],
        "ReadOnly": false,
        "RiskLevel": "Medium",
        "RequiresApproval": true,
        "Parameters": {
          "repo": { "Required": true, "Pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$" },
          "number": { "Required": true, "Pattern": "^[0-9]+$" },
          "body": { "Required": true, "MaxLength": 16000 }
        }
      }
    }
  }
}

这段配置仅覆盖 5 条只读命令和 1 条变更型命令，却已占据超过 40 行 JSON。其中 "ArgsTemplate" 数组的每一元素都需精确对应 CLI 的 positional 和 flag 参数顺序；"--json" 输出格式标志后紧跟的字段列表必须与 GitHub CLI 的 --json 选项兼容；"Parameters" 字典中的正则表达式（Pattern）需要与对应参数的语法规则保持一致。任何一个元素的错位——例如将 "--json" 误写为 "--format json"——都会导致命令执行失败或被拒绝解析 [¹]。

1.1.2 安全风险：参数占位符与输出格式标志的误配

手动配置中的安全隐患不止于格式错误。参数占位符 "{{parameter}}" 的注入风险是首要关注点：若正则约束缺失或过于宽松，LLM 生成的参数值可能突破预期范围，将额外的 CLI 标志注入命令行。例如，若 repo 参数未施加 RepoPattern（^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$）约束，攻击者可能构造 "owner/repo; rm -rf /" 形式的输入，在未经适当转义的环境中触发命令注入 [²]。

输出格式标志的误配同样构成安全威胁。GitHub CLI 的部分命令默认输出彩色文本，而 --json 标志要求结构化数据。若两者混用，解析器可能将 ANSI 转义序列误判为 JSON 内容，导致下游处理异常。此外，ReadOnly、RiskLevel 和 RequiresApproval 三个安全属性的设置完全依赖配置者的安全判断——遗漏其中任何一个，都可能导致变更型命令在未审批的情况下执行 [²]。

1.1.3 维护困难：CLI 工具版本升级时模板同步的成本

CLI 工具的新版本经常调整命令语法、增减输出字段或废弃旧标志。以 gh CLI 为例，其 --json 可用字段列表在版本迭代中多次扩展。当本地安装的 gh 升级后，网关中的 "ArgsTemplate" 可能与新版本不兼容——输出字段名变更导致 JSON 解析失败，或旧标志被移除导致命令退出码非零。维护者需要逐条审查每个连接器的每条命令，手动更新模板和字段列表，这个成本随连接器数量和命令数量线性增长 [¹]。

1.2 预设系统的诞生

1.2.1 从 40+ 行到 3 行：ExternalCliPresetCatalog 的引入

Commit 113151c7 以 972 行新增代码将预设系统注入 OpenClaw.NET，其中核心文件 ExternalCliPresetCatalog.cs 占 682 行 [³]。该文件定义了一个编译期静态字典，内置 8 个主流 CLI 工具的配置模板：gh（GitHub CLI）、az（Azure CLI）、kubectl（Kubernetes CLI）、stripe（Stripe CLI）、lark（Lark CLI）、github-copilot、codex（OpenAI Codex CLI）和 gemini（Google Gemini CLI）[⁴]。覆盖版本控制、云原生、支付、协作和 AI Agent 五大技术领域。

上述 40 余行的 gh 手动配置，在使用预设后压缩为：

"Presets": ["gh"],
"Connectors": {
  "gh": { "Enabled": true }
}

Executable 字段从预设自动继承，ArgsTemplate 和 Parameters 从编译期字典填充，全局选项（超时、脱敏等）沿用默认值。预设系统不是配置文件的替代，而是配置文件的基线——它将经过安全审查的命令模板打包进程序集，使开发者从重复性工作中解放出来 [¹]。

1.2.2 设计哲学：保守默认、显式启用、安全基线不可降

预设系统的安全设计围绕三个原则展开。第一，保守默认：appsettings.json 中 Presets 的默认值为空数组 []，未显式声明的预设不会导入任何命令模板，确保升级后现有配置行为完全一致 [²]。第二，显式启用（opt-in）：预设导入后生成的连接器初始状态为 Enabled: false，必须在 Connectors 字典中单独设置 "Enabled": true 方可执行。这种"Preset 导入 + Connector 激活"的双层启用机制意味着，单一配置层的遗漏不会导致命令面意外开放 [²]。第三，安全基线不可降：三层合并引擎（Three-layer Merge Engine）在应用用户配置覆盖时，RiskLevel 取 Max(preset, configured)，ReadOnly 取 preset AND configured，RequiresApproval 取 preset OR configured——预设所设定的风险等级、只读限制和审批要求均无法被用户配置削弱 [²]。

1.2.3 本文目标：不仅介绍系统，更指导开发者扩展自己的预设

预设系统的价值不仅在于"开箱即用"的 8 个模板，更在于它为扩展提供了清晰的工程路径。ExternalCliPresetCatalog 的静态字典结构、ExternalCliPresetDefinition 的数据模型、以及 Apply() 方法的三层合并语义，共同构成一套可预测的扩展接口。接下来的章节将首先带领读者遍历 8 个内置预设的全貌，理解每个预设的命令覆盖范围和安全设计意图；随后深入预设的数据模型和合并引擎的内部机制；最终以一个完整的自定义预设开发示例收尾，演示如何将一个新的 CLI 工具从零纳入 OpenClaw.NET 的治理体系。无论你是在评估是否采用预设系统，还是正准备为团队内部的私有 CLI 工具编写预设，本文都将提供可直接复用的代码片段和配置模式。

2. 内置预设全景速览

ExternalCliPresetCatalog 以 682 行源码将 8 个主流 CLI 工具的保守模板固化到程序集中[¹]。这些预设并非随机选取，而是围绕版本控制、云原生基础设施、支付处理、企业协作和 AI Agent CLI 五大技术领域进行的有意识覆盖，命令数量从 2 条到 6 条不等[²]。理解每个预设的风险设计策略，是安全使用预设系统的前提。

2.1 八大预设覆盖五大技术领域

2.1.1 版本控制：`gh`（GitHub CLI）— 6 条命令，1 条变更型

gh 预设是内置预设中命令数量最多的一个，覆盖 6 条常用命令。其中 issue_comment 为唯一变更型命令，风险等级设为 Medium —— 该命令允许在 issue 上添加评论，属于写入操作但不触及代码仓库本身[²]。其余 5 条命令均为查询类操作，默认 Low 风险。标签 github 和 vcs（Version Control System，版本控制系统）标识了该预设的技术归属。对于以 GitHub 为核心代码托管平台的团队，gh 预设提供了 issue 查询、PR 列表、仓库状态等高频操作的即开即用能力。

2.1.2 云原生：`az`（Azure CLI）与 `kubectl` — 全只读设计

az 和 kubectl 两个云原生预设的全部命令均为只读（ReadOnly）设计[²]。az 预设包含 3 条命令，覆盖资源组列表、账户信息和 VM 状态查询；kubectl 预设包含 5 条命令，覆盖 Pod 列表、服务列表、部署状态、节点信息和命名空间查询。这种全只读设计与生产环境中基础设施变更需经人工审批的安全实践一致——查询类操作可以自动化，但任何可能修改集群状态或云资源的命令均被排除在预设之外。如果团队确实需要变更型云操作，必须通过手动配置自行定义命令模板，并显式设置对应的风险等级和审批要求。

2.1.3 支付与协作：`stripe`（PII 敏感）与 `lark`（飞书）

stripe 预设仅有 2 条命令，但 customers_list 明确标记为 Medium 风险，原因是客户列表可能包含个人身份信息（PII，Personally Identifiable Information）[²]。Stripe 作为支付处理平台，其 CLI 返回的数据天然涉及敏感金融信息，即使纯粹的列表查询操作也需要提升风险等级以触发相应的脱敏和审批流程。lark（飞书）预设包含 5 条命令，其中 message_send 是唯一变更型命令，风险等级 Medium —— 该命令允许通过飞书 API 发送消息，虽非破坏性操作，但涉及企业通信渠道的写入权限[²]。标签 lark、feishu 和 collaboration 覆盖了该预设在中英文语境下的识别需求。

2.1.4 AI Agent CLI：`github-copilot`、`codex`、`gemini` — 统一 High 风险 + 强制审批

三个 AI Agent CLI 预设采用与基础设施预设截然不同的安全策略。github-copilot（2 条命令）、codex（4 条命令）和 gemini（2 条命令）的 RiskLevel 统一固定为 High，RequiresApproval 强制为 true[³]。这一决策的技术依据在于：这些 CLI 的 prompt 命令可将本地仓库上下文发送到外部 AI 服务，而 codex 的 exec 命令在 workspace-write 模式下具备文件系统写权限[³]。每个 AI Agent 预设还配置了最大 prompt 长度限制（8000 字符）和非交互式模式参数（-p 或 --sandbox），确保自动化场景中不会触发交互式提示阻塞执行流[³]。codex 预设进一步区分了只读沙箱（read-only）和可写沙箱（workspace-write）两种模式，后者映射到 High 风险等级。

以下矩阵汇总了 8 个内置预设的完整配置：

预设 ID	连接器名称	可执行文件	命令数	风险特征	标签
`gh`	`gh`	`gh`	6	1 条变更型（`issue_comment`，Medium）	github, vcs
`az`	`az`	`az`	3	全只读	azure, cloud
`kubectl`	`kubectl`	`kubectl`	5	全只读	kubernetes, cluster
`stripe`	`stripe`	`stripe`	2	`customers_list` 为 Medium（含 PII）	stripe, payments
`lark`	`lark`	`lark-cli`	5	1 条变更型（`message_send`，Medium）	lark, feishu, collaboration
`github-copilot`	`github-copilot`	`copilot`	2	`prompt` 为 High（AI Agent）	github, copilot, ai
`codex`	`codex`	`codex`	4	`exec_workspace_write` 为 High	codex, openai, ai
`gemini`	`gemini`	`gemini`	2	`prompt` 为 High（AI Agent）	gemini, google, ai

从风险设计维度审视，8 个预设呈现清晰的二分格局。5 个基础设施预设（gh、az、kubectl、stripe、lark）遵循保守策略：仅当命令涉及数据写入或返回 PII 时方设为 Medium 风险，其余查询类命令均为 Low 风险且默认只读[²]。这种"最小必要风险"原则确保日常查询操作不会触发不必要的审批阻塞。而 3 个 AI Agent 预设（github-copilot、codex、gemini）则统一采用最高安全级别——High 风险与强制审批的组合[³]。这一差异反映了基础设施 CLI 与 AI Agent CLI 在威胁模型上的本质区别：前者的风险边界由命令本身的副作用定义，后者的风险则来自本地数据向外部 AI 服务的自动传输，以及 AI 生成代码对文件系统的潜在写入。命令数量方面，gh 以 6 条命令居首，stripe 和 AI Agent 预设以 2 条居末，这种差异与 CLI 工具自身功能广度和预设系统的保守筛选策略均相关。

2.2 安全策略矩阵

2.2.1 风险等级分布

预设系统的风险等级分为三级：Low（查询类操作）、Medium（涉及 PII 或轻度写入）、High（涉及外部数据传输或文件系统写入）。5 个基础设施预设的绝大多数命令处于 Low 和 Medium 两级，3 个 AI Agent 预设全部锁定在 High 级[²][³]。这种分布并非随意设定，而是对应三种不同的威胁模型：Low 级命令的潜在损害限于信息泄露；Medium 级命令可能修改项目数据或暴露敏感个人信息；High 级命令则可能导致本地代码上下文外流至第三方 AI 服务，或授予 AI 代理文件系统写权限。风险等级的三级划分直接驱动下游的行为差异：Medium 级命令触发内容脱敏（RedactSecrets），High 级命令额外触发执行前人工审批。

2.2.2 双层启用机制

预设系统采用"Preset 导入 + Connector 激活"的双层启用机制（opt-in security）[¹]。第一层，appsettings.json 中的 "Presets": [] 默认空数组确保升级后现有配置行为不变，未显式声明的预设不会导入任何命令模板。第二层，预设导入后在 Connectors 字典中生成的连接器初始状态为 Enabled: false，必须单独设置 "Enabled": true 方可执行[¹]。这意味着仅将 "gh" 加入 Presets 数组并不会实际开放任何命令面——还需在 Connectors 中显式启用对应连接器。单层遗漏不会暴露命令面的设计，将配置误操作的风险降至最低。配置验证器（ConfigValidator）进一步在合并后对有效配置执行校验，拒绝未知预设 ID 并检查数组中的空值与重复项[¹]。

2.2.3 三层合并引擎

Apply() 方法实现了三层配置合并[⁴]。第一层复制全局选项；第二层遍历 Presets[] 中的每个 ID，在静态字典中查找对应预设，通过 CloneConnector() 深拷贝后填入 Connectors 字典；第三层遍历用户配置的每个 Connector，若存在对应预设则调用 MergeConnector(preset, configured)，否则直接 CloneConnector(configured)[⁴]。

合并规则遵循"安全保守"原则。其中三项规则构成不可被用户配置削弱的安全基线：RiskLevel 取 Max(preset, configured)，风险等级只升不降；ReadOnly 取 preset AND configured，只读限制不放宽；RequiresApproval 取 preset OR configured，审批要求不绕过[⁴]。举例而言，若某 AI Agent 预设将 RiskLevel 设为 High，用户无法通过本地配置将其降为 Low；若预设要求审批，用户配置无法将其关闭。ExternalCliPresetCatalog 还定义了三组正则表达式约束参数输入：RepoPattern（^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$）用于 GitHub 仓库格式；NumberPattern（^[0-9]+$）用于 PR 号、issue 号等数字参数；SimpleNamePattern（^[A-Za-z0-9_.:-]+$）用于 Kubernetes 命名空间、文档 ID 等标识符[³]。这些模式与合并引擎中的参数约束合并逻辑协同工作，形成参数层面的输入验证防线。

理解了 8 个预设的覆盖范围和安全设计策略后，下一章将深入预设系统的核心架构——从 ExternalCliPresetCatalog 的静态字典结构到三层合并引擎的完整实现路径。

3. 预设系统的核心架构

OpenClaw.NET 的预设系统是一套以编译时固化和安全保守合并为核心约束的微型配置引擎。理解其三层架构——静态字典的存储层、合并引擎的计算层、安全属性的代数层——是正确编写自定义预设的前提。

3.1 ExternalCliPresetCatalog 静态字典

3.1.1 编译时固化设计

所有预设存储于 ExternalCliPresetCatalog 的 static readonly 字典中，编译期嵌入程序集[¹]。运行时无外部文件系统或网络 I/O 依赖，预设查找完全发生在内存中。ExternalCliPresetCatalog.cs 以 682 行代码承载 8 个内置预设定义[²]，将数据与查找逻辑封装在同一编译单元，便于版本控制和代码审查。

字典的键为预设 ID（如 "gh"、"kubectl"），值为包含命令模板、风险等级、参数约束的 ExternalCliConnector 对象。ID 匹配使用 StringComparer.OrdinalIgnoreCase，"GH"、"Gh"、"gh" 均指向同一预设[¹]。

3.1.2 四个核心 API

预设目录暴露四个操作[¹]：List() 返回全部预设摘要（ID、连接器名称、命令数量、标签），供 openclaw external presets CLI 命令消费；TryGet(id) 执行单条查找，ID 不存在时返回 null，由调用方决定处理策略；FindUnknownIds() 验证 Presets[] 中是否存在未定义 ID，为 ConfigValidator 提供前置校验能力，拒绝未知预设并在启动阶段报错；Apply(options) 执行三层合并引擎，输出完整有效配置。四个 API 遵循只读语义——ExternalCliPresetCatalog 不修改输入，Apply() 内部通过深拷贝确保调用方的原始配置对象不受影响。

3.1.3 大小写不敏感 ID 匹配

StringComparer.OrdinalIgnoreCase 基于 Unicode 序号的逐字节比较，忽略大小写但不进行文化敏感转换，性能和文化一致性均优于 CurrentCultureIgnoreCase[¹]。对于 ASCII 预设 ID，该比较器等价于 ToLowerInvariant() 后比较，但避免了字符串分配。

// ExternalCliPresetCatalog 核心结构
public static class ExternalCliPresetCatalog
{
    // 编译期固化，零运行时 I/O
    private static readonly Dictionary<string, ExternalCliConnector> _presets
        = new(StringComparer.OrdinalIgnoreCase)
        {
            ["gh"] = new ExternalCliConnector { /* 6 条命令模板 */ },
            ["az"] = new ExternalCliConnector { /* 3 条命令模板 */ },
            ["kubectl"] = new ExternalCliConnector { /* 5 条命令模板 */ },
            // ... 其余 5 个预设
        };

    public static IReadOnlyList<ExternalCliPresetSummary> List()
        => _presets.Select(p => p.Value.ToSummary()).ToList();

    public static ExternalCliConnector? TryGet(string id)
        => _presets.TryGetValue(id, out var conn) ? conn : null;

    public static IEnumerable<string> FindUnknownIds(IEnumerable<string> ids)
        => ids.Where(id => !_presets.ContainsKey(id));

    public static ExternalCliOptions Apply(ExternalCliOptions userOptions)
    {
        var result = new ExternalCliOptions();
        // 第一层：全局选项复制
        // 第二层：预设导入（CloneConnector 深拷贝）
        // 第三层：用户覆盖（MergeConnector 安全合并）
        return result;
    }
}

3.2 三层合并引擎详解

Apply() 是预设系统的计算核心，三层依次叠加产生最终配置[³]。

第一层将 ExternalCliOptions 中的全局字段复制到结果对象，包括 Enabled、Timeout、RedactSecrets 及 Presets[] 数组[³]。这一层仅执行字段级浅拷贝，不涉及合并逻辑。Presets[] 的保留使下游组件能够追踪哪些预设被激活，便于审计和调试输出。

第二层遍历 Presets[] 中的每个 ID，在静态字典查找对应预设，通过 CloneConnector() 深拷贝后填入 Connectors 字典[³]。深拷贝是关键——它确保每个激活的连接器拥有独立实例，后续用户覆盖不会反向修改静态字典中的原始预设定义。这一层体现双层启用机制的第一半：预设导入填充命令模板与安全属性，但 Enabled 继承默认值 false[⁴]，命令面仍未开放，用户必须在第三层或后续配置中显式启用。

第三层遍历用户配置的每个 Connector。若名称与第二层导入的预设匹配，调用 MergeConnector(preset, configured) 执行安全保守合并；否则 CloneConnector(configured) 深拷贝[³]。

MergeConnector 遵循安全保守原则——任何合并不降低预设的风险等级。规则如下：

字段	合并规则	安全语义
`Enabled`	`preset \|\| configured`（OR）	用户可显式启用
`RiskLevel`	`Max(preset, configured)`	风险只升不降
`ReadOnly`	`preset && configured`（AND）	只读限制不放宽
`RequiresApproval`	`preset \|\| configured`（OR）	审批不绕过
`ArgsTemplate`	用户非空则覆盖	允许自定义命令
`Parameters`	逐字段合并	可增改参数约束
`Tags`	集合并集	保留双方标签

RiskLevel、ReadOnly 和 RequiresApproval 构成不可被用户配置削弱的安全基线[³]。例如 github-copilot 预设将 RiskLevel 设为 High，用户无法降为 Low——Max(High, Low) = High[⁵]。ArgsTemplate 的非空覆盖策略则提供了灵活性：留空继承预设，非空则完全替换。

3.3 安全属性的代数结构

三层合并引擎的安全保守性并非偶然，它建立在三个安全属性的代数结构之上。理解这些结构有助于预判自定义预设中安全字段的交互行为[⁶]。

RiskLevel 的取值空间 Low < Medium < High 构成全序集，Max 运算在该集合上形成半格（semilattice）——满足交换律 Max(a, b) = Max(b, a)、结合律 Max(Max(a, b), c) = Max(a, Max(b, c)) 和幂等律 Max(a, a) = a。最关键的单调性 Max(a, b) >= a 保证合并结果永不低于预设基线。

ReadOnly 的 AND 运算形成合取闭包（conjunctive closure）[⁶]。true AND false = false 意味着只要任一方允许写入，结果即为可写。az 和 kubectl 预设将全部命令的 ReadOnly 设为 true[⁵]，用户配置无法将其放宽为 false AND true = false。但 false AND true = false 同时表明：预设未要求只读时，用户无法单方面施加只读限制。

RequiresApproval 的 OR 运算形成析取闭包（disjunctive closure）[⁶]。true OR false = true 确保审批要求单向强制——预设要求审批则用户无法关闭。三个 AI Agent 预设（github-copilot、codex、gemini）将 RequiresApproval 固定为 true，true OR x = true 确保审批门不可绕过[⁵]。

// 安全属性的代数结构
public enum RiskLevel { Low = 0, Medium = 1, High = 2 }

public static class SecurityAttributeAlgebra
{
    // 半格：Max 运算（单调不减）
    public static RiskLevel MergeRiskLevel(RiskLevel p, RiskLevel c)
        => (RiskLevel)Math.Max((int)p, (int)c);
    // Max(High, Low) = High — 用户无法降低风险等级

    // 合取闭包：AND 运算（限制不放宽）
    public static bool MergeReadOnly(bool p, bool c) => p && c;
    // false AND true = false — 预设未要求只读则用户无法单方面施加

    // 析取闭包：OR 运算（审批不绕过）
    public static bool MergeRequiresApproval(bool p, bool c) => p || c;
    // true OR false = true — 预设要求审批则不可关闭
}

三个结构的共同特征是单调性——安全维度上永不减弱[⁶]。Max 保证风险单调不减，AND 保证只读限制单调不放宽，OR 保证审批要求单调不解除。双层启用机制将这一代数延伸至交互设计：第一层预设导入后，Enabled: false 仍阻断命令面暴露。自定义预设开发者只需关注预设层的安全基线设定——合并引擎自动保证基线不被用户配置削弱。

4. 实战：为 Terraform CLI 编写自定义预设

前三章从内置预设的全貌遍历到合并引擎的安全属性代数，建立了一套可复用的分析框架。本章将这套框架应用于一个具体目标：为 HashiCorp Terraform CLI 编写完整的自定义预设。Terraform 作为基础设施即代码（IaC，Infrastructure as Code）领域的事实标准工具，其命令面具有清晰的只读/变更型分界——plan 和 state list 属于查询类操作，apply 则直接修改云资源状态——这使其成为演示预设开发全流程的理想样本。下文将依次完成命令面分析、预设代码编写、安全加固和测试验证四个阶段。

4.1 准备工作

4.1.1 分析目标 CLI 的命令面

Terraform CLI 的命令树以子命令（subcommand）方式组织。在预设系统的语境中，每条子命令对应一个独立的命令模板，需要分别定义 ArgsTemplate、Parameters 和安全属性。以下是预设覆盖范围内的四条命令及其行为特征：

terraform plan 生成执行计划（execution plan），对比当前配置与远程状态文件的差异，输出拟创建、修改或销毁的资源列表。该命令不修改任何基础设施状态，属于纯只读分析操作。-input=false 标志可抑制交互式提示，-json 标志以结构化 JSON 输出计划摘要而非人类可读文本[¹]。

terraform apply 是命令面中唯一具备破坏性副作用的命令。它根据 Terraform 配置创建或修改基础设施资源，可能涉及资源创建、更新、删除和替换操作。-auto-approve 标志跳过执行前的交互式确认提示，-input=false 抑制变量输入交互[¹]。在预设系统中，该命令必须标记为变更型（ReadOnly: false），并赋予最高风险等级。

terraform state list 列举 Terraform 状态文件中跟踪的所有资源地址，用于审计和排查资源依赖关系。该命令仅读取本地或远程状态文件，不触发任何 API 调用，是最安全的查询操作之一。

terraform output 读取状态文件中的输出变量值（output values），常用于在 CI/CD 流水线中获取资源 ID 或端点地址。-json 标志以 JSON 格式输出所有输出变量，便于下游解析。

四条命令中，plan、state list 和 output 均属于只读查询类操作，apply 是唯一可能改变基础设施状态的变更型命令。这一分布与第 2 章中 az 和 kubectl 预设的全只读设计形成对照——Terraform 预设保留了 apply 命令，原因在于 IaC 工具的核心价值正是将配置变更自动化，完全排除 apply 将使预设失去实用意义。

4.1.2 确定风险等级

风险等级的赋值遵循第 2 章归纳的"最小必要风险"原则。plan、state list 和 output 三条命令均不修改基础设施状态，潜在损害限于信息泄露，风险等级设为 Low。apply 命令可导致云资源的创建、修改和销毁，直接影响生产环境可用性，风险等级设为 High[²]。

RequiresApproval 的设置与风险等级直接关联。apply 命令的 High 风险等级意味着每次执行前必须经过人工审批门（approval gate），因此 RequiresApproval 设为 true。三条只读命令不设审批要求，用户可通过预设直接调用。

4.1.3 定义参数约束

Terraform CLI 的参数分为三类：目标资源地址（address）、工作区名称（workspace）和输出变量名（name）。每类参数需要定义对应的正则表达式约束，防止 LLM 生成的参数值突破预期范围。

WorkspacePattern 约束工作区名称：^[A-Za-z0-9_-]+$。Terraform 工作区名称仅允许字母、数字、下划线和连字符，不允许空格或特殊字符——后者可能被 Shell 解释器误解析[³]。ResourceTypePattern 约束资源类型标识符：^[a-z_]+$。Terraform 资源类型由提供商前缀和资源名组成（如 aws_instance），仅含小写字母和下划线[³]。OutputNamePattern 约束输出变量名：^[A-Za-z0-9_]+$，与 Terraform HCL 语言中标识符的语法规则一致。

这些模式与 ExternalCliPresetCatalog 中已有的 RepoPattern、NumberPattern 和 SimpleNamePattern 遵循同一设计哲学：模式应足够严格以排除注入攻击载荷，又足够宽松以不拒绝合法输入[³]。

4.2 编写预设代码

4.2.1 在 ExternalCliPresetCatalog 中新增 terraform 条目

预设的入口点位于 ExternalCliPresetCatalog 的 static readonly 字典。terraform 条目的结构遵循第 3 章描述的命名约定：ID 小写、连接器名称与 ID 一致、标签覆盖中英文识别。

以下代码片段展示了 terraform 预设的完整 C# 定义，包含 4 条命令模板、安全属性和参数约束：

// ExternalCliPresetCatalog.cs — terraform 预设定义
private static readonly Dictionary<string, ExternalCliConnector> _presets
    = new(StringComparer.OrdinalIgnoreCase)
    {
        // ... 其余 8 个内置预设 ...

        ["terraform"] = new ExternalCliConnector
        {
            Name = "terraform",
            Executable = "terraform",
            Tags = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
            {
                "terraform", "iac", "infrastructure"
            },
            Commands = new Dictionary<string, ExternalCliCommand>
            {
                ["plan"] = new ExternalCliCommand
                {
                    ArgsTemplate = new[]
                    {
                        "plan", "-input=false", "-json",
                        "-target={{target}}", "-var-file={{var_file}}"
                    },
                    Parameters = new Dictionary<string, ExternalCliParameter>
                    {
                        ["target"] = new ExternalCliParameter
                        {
                            Type = ExternalCliParameterType.String,
                            Pattern = "^aws_[a-z]+\\.[a-zA-Z0-9_-]+$",
                            Required = false,
                            Description = "Target resource address (e.g., aws_instance.web)"
                        },
                        ["var_file"] = new ExternalCliParameter
                        {
                            Type = ExternalCliParameterType.String,
                            Pattern = "^terraform\\.tfvars$|^[A-Za-z0-9_/-]+\\.tfvars$",
                            Required = false,
                            Description = "Path to tfvars file"
                        }
                    },
                    RiskLevel = RiskLevel.Low,
                    ReadOnly = true,
                    RequiresApproval = false,
                    OutputFormat = OutputFormat.Json
                },
                ["apply"] = new ExternalCliCommand
                {
                    ArgsTemplate = new[]
                    {
                        "apply", "-input=false", "-auto-approve", "-json",
                        "-target={{target}}"
                    },
                    Parameters = new Dictionary<string, ExternalCliParameter>
                    {
                        ["target"] = new ExternalCliParameter
                        {
                            Type = ExternalCliParameterType.String,
                            Pattern = "^aws_[a-z]+\\.[a-zA-Z0-9_-]+$",
                            Required = false,
                            Description = "Target resource address for scoped apply"
                        }
                    },
                    RiskLevel = RiskLevel.High,
                    ReadOnly = false,
                    RequiresApproval = true,
                    OutputFormat = OutputFormat.Json
                },
                ["state_list"] = new ExternalCliCommand
                {
                    ArgsTemplate = new[] { "state", "list" },
                    Parameters = new Dictionary<string, ExternalCliParameter>(),
                    RiskLevel = RiskLevel.Low,
                    ReadOnly = true,
                    RequiresApproval = false,
                    OutputFormat = OutputFormat.Text
                },
                ["output"] = new ExternalCliCommand
                {
                    ArgsTemplate = new[]
                    {
                        "output", "-json", "{{name}}"
                    },
                    Parameters = new Dictionary<string, ExternalCliParameter>
                    {
                        ["name"] = new ExternalCliParameter
                        {
                            Type = ExternalCliParameterType.String,
                            Pattern = "^[A-Za-z0-9_]+$",
                            Required = false,
                            Description = "Output variable name (optional)"
                        }
                    },
                    RiskLevel = RiskLevel.Low,
                    ReadOnly = true,
                    RequiresApproval = false,
                    OutputFormat = OutputFormat.Json
                }
            }
        }
    };

上述定义中，terraform 条目的结构与 8 个内置预设保持一致。ArgsTemplate 数组中的 "{{parameter}}" 占位符在运行时由 LLM 生成的参数值替换，替换后的数组直接传递给 Process.Start 的参数列表。-input=false 和 -auto-approve 标志固定写入模板，确保自动化场景中 Terraform 不会阻塞于交互式提示[⁴]。

4.2.2 定义 Commands 数组

Commands 字典的键为命令标识符（如 "plan"、"state_list"），值为 ExternalCliCommand 对象。每个命令对象包含四个核心字段。ArgsTemplate 定义 CLI 参数模板数组，其中 "{{parameter}}" 为占位符语法，运行时替换为实际参数值；固定标志如 "-json" 和 "-input=false" 直接硬编码于模板中。Parameters 为每个动态参数定义类型、正则模式、是否必填和描述。RiskLevel、ReadOnly 和 RequiresApproval 构成安全属性三元组，其合并语义遵循第 3.3 节定义的代数结构。

4.2.3 ArgsTemplate 语法与自动化标志

ArgsTemplate 采用 "{{parameter}}" 双花括号占位符语法，与内置预设中 "{{repo}}"、"{{number}}" 的约定一致[³]。当参数值为空或 null 时，占位符及其相邻元素从参数列表中移除，避免向 CLI 传递空字符串。例如 plan 命令的 var_file 参数为可选，若 LLM 未提供该参数，则 "-var-file={{var_file}}" 整项从数组中省略。

-input=false 和 -auto-approve 两个非交互式标志的嵌入位置至关重要。-input=false 抑制 Terraform 在缺少变量值时的交互式提示，-auto-approve 跳过 apply 命令的执行确认[⁴]。二者共同确保网关以非交互式模式（non-interactive mode）调用 Terraform，防止执行流阻塞于终端输入。-json 标志统一输出格式为结构化 JSON，便于下游解析器消费。

4.2.4 Parameters 定义

每个参数通过 ExternalCliParameter 对象定义四个字段。Type 声明参数的数据类型（String、Integer、Boolean），Pattern 为正则表达式字符串，在命令执行前由参数验证器编译并匹配。Required 指示参数是否必填；必填参数缺失时命令在解析阶段即被拒绝。Description 为 LLM 提供参数语义说明，影响工具调用时参数生成的准确性。

4.3 安全加固

4.3.1 为 apply 命令设置 RequiresApproval 与 RiskLevel

apply 命令的安全基线在第 4.1.2 节中已确定：RiskLevel: High 与 RequiresApproval: true。这一基线在第 3 章的合并引擎中具有不可被用户配置削弱的代数保证——Max(High, x) = High 且 true OR x = true[⁵]。即使 appsettings.json 中 terraform 连接器的配置试图覆盖 apply 命令的风险等级为 Low，三层合并引擎仍将结果锁定为 High。

ReadOnly: false 的设置同样具有合取闭包的保护：false AND configured.ReadOnly = false。这意味着用户配置无法将 apply 命令单方面标记为只读——预设未施加只读限制时，用户配置中的 ReadOnly: true 在合并后仍为 false[⁵]。这一行为与 az 和 kubectl 预设的全只读设计形成对比：后两者的 ReadOnly: true 基线确保用户无法将其中的查询命令放宽为可写。

4.3.2 添加参数级正则验证

参数级正则验证是防止命令注入的第二道防线。target 参数的 ResourceTypePattern（^aws_[a-z]+\.[a-zA-Z0-9_-]+$）约束资源地址格式为"提供商类型.资源名"，排除了包含 Shell 元字符（;、&、|、$ 等）的注入载荷[³]。var_file 参数的 ^terraform\.tfvars$|^[A-Za-z0-9_/-]+\.tfvars$ 模式限制变量文件路径为 .tfvars 扩展名，且仅允许特定字符集——/ 用于目录分隔，_ 用于文件名中的下划线，- 用于连字符。点号 . 在正则中经 \. 转义后仅匹配字面量点号，防止路径遍历攻击中常见的 ../etc/passwd 模式匹配。

4.3.3 配置最大输出长度和超时

terraform plan 命令在大型基础设施项目中可能产生数万行的 JSON 输出，超出 LLM 上下文窗口的处理能力。预设中 plan 命令的 OutputFormat: Json 设置确保输出为结构化数据，配合全局配置中的 MaxOutputLength 字段可截断过长输出。以下 appsettings.json 配置展示了 terraform 连接器的完整用户配置：

{
  "OpenClaw": {
    "ExternalCli": {
      "Presets": ["terraform"],
      "Connectors": {
        "terraform": {
          "Enabled": true,
          "Timeout": 120,
          "MaxOutputLength": 50000,
          "RedactSecrets": true
        }
      }
    }
  }
}

上述配置中，Timeout: 120 将 Terraform 命令的超时时间设为 120 秒——terraform plan 在复杂项目中可能需要数十秒完成状态刷新和差异计算，默认值 30 秒可能不足以覆盖该场景。MaxOutputLength: 50000 限制单条命令输出为 50000 字符，超出部分被截断并附加截断提示。RedactSecrets: true 启用敏感信息脱敏，Terraform 的 output 命令可能返回数据库密码或 API 密钥等敏感值，脱敏确保此类数据不会进入 LLM 上下文。

以下矩阵汇总了 terraform 预设的 4 条命令及其安全属性：

命令标识符	CLI 子命令	风险等级	只读	需审批	输出格式	参数数量
`plan`	`terraform plan`	Low	true	false	Json	2
`apply`	`terraform apply`	High	false	true	Json	1
`state_list`	`terraform state list`	Low	true	false	Text	0
`output`	`terraform output`	Low	true	false	Json	1

从风险设计维度审视，terraform 预设呈现与第 2 章中 gh 预设相似的二分格局：3 条只读查询命令锁定在 Low 风险等级，1 条变更型命令以 High 风险 + 强制审批的组合处于最高安全级别。state_list 命令的参数数量为 0，表明该命令不接受动态参数，模板数组中的固定元素直接传递给 CLI。apply 命令的参数数量刻意限制为 1（仅 target），排除 var_file 参数——在自动化场景中通过变量文件传递配置会增加不可预测性，预设选择保守策略，要求所有变量通过 CI/CD 流水线的环境变量或预置 .tfvars 文件管理。

4.4 测试与验证

4.4.1 使用 openclaw external presets 命令验证预设被发现

预设代码编译并通过 CI 后，首要验证步骤是确认新预设已被正确注册到目录中。openclaw external presets CLI 命令遍历 ExternalCliPresetCatalog.List() 返回的预设摘要，文本输出格式为制表符分隔的行列表[⁶]。

$ openclaw external presets
terraform   terraform   4   terraform, iac, infrastructure

上述输出确认 terraform 预设已被目录收录，连接器名称为 terraform，命令数量为 4，标签包含 terraform、iac 和 infrastructure。附加 --json 标志可获取机器可读输出，包含完整的 Commands 列表和 Tags 字段，便于自动化验证脚本解析[⁶]。若输出中未出现 terraform 行，需检查 ExternalCliPresetCatalog.cs 中字典条目是否正确编译到程序集中——预设的 static readonly 字典在编译期固化，运行时无外部加载逻辑[²]。

4.4.2 编写单元测试验证预设导入后连接器默认禁用

以下单元测试代码验证了 terraform 预设的 opt-in 语义：预设导入后连接器初始状态为 Enabled: false，必须经用户配置显式启用方可执行。

[Fact]
public void TerraformPreset_OptInMaterializesDisabledConnector()
{
    // Arrange: 用户配置中声明 Presets 包含 "terraform"，
    // 但 Connectors 中不设置 Enabled 字段
    var userOptions = new ExternalCliOptions
    {
        Presets = new[] { "terraform" },
        Connectors = new Dictionary<string, ExternalCliConnector>()
    };

    // Act: 执行三层合并引擎
    var result = ExternalCliPresetCatalog.Apply(userOptions);

    // Assert: 预设已导入，连接器存在但默认禁用
    Assert.True(result.Connectors.ContainsKey("terraform"));
    var connector = result.Connectors["terraform"];
    Assert.False(connector.Enabled);
    Assert.Equal("terraform", connector.Executable);
    Assert.Equal(4, connector.Commands.Count);
    Assert.Contains(connector.Commands, c => c.Key == "apply");
    Assert.Contains(connector.Commands, c => c.Key == "plan");
    Assert.Contains(connector.Commands, c => c.Key == "state_list");
    Assert.Contains(connector.Commands, c => c.Key == "output");
}

[Fact]
public void TerraformPreset_ConnectorOverrideEnablesCompleteCommandSet()
{
    // Arrange: 用户显式启用 terraform 连接器
    var userOptions = new ExternalCliOptions
    {
        Presets = new[] { "terraform" },
        Connectors = new Dictionary<string, ExternalCliConnector>
        {
            ["terraform"] = new ExternalCliConnector { Enabled = true }
        }
    };

    // Act
    var result = ExternalCliPresetCatalog.Apply(userOptions);

    // Assert: 连接器已启用，命令集完整保留
    var connector = result.Connectors["terraform"];
    Assert.True(connector.Enabled);
    Assert.Equal(4, connector.Commands.Count);
}

[Fact]
public void TerraformPreset_MergePreservesHighRiskBaseline()
{
    // Arrange: 用户试图将 apply 的风险等级降为 Low
    var userOptions = new ExternalCliOptions
    {
        Presets = new[] { "terraform" },
        Connectors = new Dictionary<string, ExternalCliConnector>
        {
            ["terraform"] = new ExternalCliConnector
            {
                Enabled = true,
                Commands = new Dictionary<string, ExternalCliCommand>
                {
                    ["apply"] = new ExternalCliCommand
                    {
                        RiskLevel = RiskLevel.Low,
                        RequiresApproval = false,
                        ReadOnly = true
                    }
                }
            }
        }
    };

    // Act: 三层合并引擎执行安全保守合并
    var result = ExternalCliPresetCatalog.Apply(userOptions);

    // Assert: 安全基线不可降 — Max(High, Low) = High
    var applyCmd = result.Connectors["terraform"].Commands["apply"];
    Assert.Equal(RiskLevel.High, applyCmd.RiskLevel);
    Assert.True(applyCmd.RequiresApproval);
    Assert.False(applyCmd.ReadOnly);
}

三个测试分别对应预设系统的三个核心安全语义。TerraformPreset_OptInMaterializesDisabledConnector 验证双层启用机制的第一层——预设导入后 Enabled 为 false，与第 3 章描述的 gh、az 等内置预设行为一致[²]。TerraformPreset_ConnectorOverrideEnablesCompleteCommandSet 验证第二层——用户显式设置 Enabled: true 后，完整的 4 条命令集可用，无需重新定义任何 ArgsTemplate 或 Parameters。

TerraformPreset_MergePreservesHighRiskBaseline 是安全验证的核心测试。用户配置试图通过三个路径削弱 apply 命令的安全基线：将 RiskLevel 降为 Low、将 RequiresApproval 关闭为 false、将 ReadOnly 提升为 true。三层合并引擎的代数结构确保三条路径均失败——Max(High, Low) 返回 High，true OR false 返回 true，false AND true 返回 false[⁵]。该测试与 ExternalCliTests.cs 中针对 AI Agent 预设的同类测试遵循同一验证模式，区别仅在于被测预设从 github-copilot 或 codex 替换为自定义的 terraform[²]。

4.4.3 验证合并语义：用户配置无法降低风险等级

TerraformPreset_MergePreservesHighRiskBaseline 测试覆盖了第 3.3 节定义的三种安全属性代数结构。RiskLevel 的 Max 半格运算保证预设的 High 基线不可降为 Low 或 Medium；RequiresApproval 的 OR 析取闭包保证预设的 true 基线不可关闭为 false；ReadOnly 的 AND 合取闭包则从另一方向保证预设的 false（可写）基线不可被用户单方面施加为 true（只读）[⁵]。

这一验证模式具有通用性。无论自定义预设的目标 CLI 是 Terraform、Pulumi 还是 Ansible，安全基线的验证均可采用同一测试模板：构造一个试图削弱预设安全属性的用户配置，断言合并后的结果仍保持预设基线。自定义预设开发者只需替换测试中的预设 ID、命令标识符和安全属性期望值，即可复用上述测试结构验证自身预设的安全性。

5. 高级主题与最佳实践

经过第 4 章的 Terraform 预设实战，开发者已具备从零构建自定义预设的完整能力。本章从参数验证、配置策略和社区协作三个维度，提供可在实际项目中直接应用的高级模式与操作清单。

5.1 参数验证模式库

ExternalCliPresetCatalog 内置三组正则表达式，覆盖最常见的 CLI 参数类型[¹]。在自定义预设中复用这些模式，可减少重复定义并确保验证语义一致。

5.1.1 复用内置正则模式

RepoPattern（^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$）约束 owner/repo 格式的仓库标识符；NumberPattern（^[0-9]+$）限定 PR 号、issue 号等纯数字输入；SimpleNamePattern（^[A-Za-z0-9_.:-]+$）覆盖 Kubernetes 命名空间、文档 ID 等标识符[²]。三组模式均遵循保守扩展原则——字符集仅包含无需转义即可安全嵌入命令行的 ASCII 子集，排除了空格和 shell 元字符，在参数层面阻断命令注入的基础攻击向量。

5.1.2 为不同领域设计专用模式

当内置模式不足以覆盖特定 CLI 参数空间时，需要为领域设计专用正则。以下表格汇总了内置模式和建议的新增模式，可作为团队建立参数验证规范的参考基线。

模式名称	正则表达式	适用参数类型	典型 CLI	安全考虑
`RepoPattern`	`^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$`	GitHub 仓库（`owner/repo`）	`gh`	排除路径遍历 `../`
`NumberPattern`	`^[0-9]+$`	PR/Issue/流水线编号	`gh`, `az`	纯数字排除所有注入字符
`SimpleNamePattern`	`^[A-Za-z0-9_.:-]+$`	命名空间、文档 ID	`kubectl`	支持 K8s `namespace:resource` 语法
`ArnPattern`	`^arn:[a-z0-9-]+:…`	AWS ARN	`aws`	禁止空白字符，服务名段强制小写
`K8sResourcePattern`	`^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$`	Pod/Deployment 名称	`kubectl`	RFC 1123 子域名标签
`UrlSafePattern`	`^[A-Za-z0-9_.~/-]+$`	URL 路径段	`curl`	仅含 RFC 3986 unreserved 字符
`UuidPattern`	`^[0-9a-f]{8}-…[0-9a-f]{12}$`	资源唯一标识符	`az`, `aws`	严格匹配 GUID v4 格式

这个模式库的核心设计原则是字符集白名单而非黑名单。RepoPattern 只允许字母、数字、下划线、点和连字符，../../etc/passwd 这类恶意输入会在命令执行前被拦截。K8sResourcePattern 要求名称以字母数字开头和结尾，天然排除 shell 特殊字符。建议团队在内部维护扩展的模式字典，将本表作为起点，随新 CLI 集成逐步沉淀领域专用正则。

5.1.3 模式组合策略

参数验证在 Parameters 配置中遵循分级策略：Required: true 的参数使用最严格模式，Required: false 的可适当放宽。对于复合参数（如 terraform plan -var="name=value"），建议拆分为 name 和 value 两个独立字段分别验证，而非构造覆盖全语法的单一正则。拆分后的验证单元语义更清晰，错误信息也更精确。

5.2 渐进式自定义路径

预设系统支持从快速启用到完全手动的四阶段渐进路径[³]，团队可按需求复杂度选择阶段，避免面对全量配置的学习成本。

5.2.1 阶段一：纯预设导入

最低配置仅声明预设 ID 并启用连接器：

{
  "Presets": ["terraform"],
  "Connectors": { "terraform": { "Enabled": true } }
}

Executable 与命令模板均从预设继承，此阶段适用于快速验证预设是否满足基本需求[³]。

5.2.2 阶段二：覆盖可执行文件路径与全局选项

当 CLI 不在系统 PATH 中，或需使用特定版本时，覆写 Executable 并调整超时：

{
  "Presets": ["terraform"],
  "Connectors": {
    "terraform": {
      "Enabled": true,
      "Executable": "/opt/terraform/1.9.2/terraform",
      "Timeout": 120,
      "RedactSecrets": true
    }
  }
}

此阶段保持预设的命令模板和风险等级不变。三层合并引擎在第三层仅覆盖 Executable、Timeout 等非安全字段，RiskLevel 和 RequiresApproval 仍由预设基线保护[⁴]。

5.2.3 阶段三：添加自定义命令或修改参数约束

当预设未覆盖常用子命令（如 terraform workspace select）时，可在保持预设命令基础上追加：

{
  "Presets": ["terraform"],
  "Connectors": {
    "terraform": {
      "Enabled": true,
      "Parameters": {
        "workspace": {
          "Type": "string", "Pattern": "^[A-Za-z0-9_-]+$",
          "Required": true, "Description": "Terraform workspace name"
        }
      },
      "Commands": {
        "workspace_select": {
          "ArgsTemplate": ["workspace", "select", "{workspace}"],
          "RiskLevel": "Medium", "ReadOnly": false, "RequiresApproval": true,
          "Parameters": ["workspace"]
        }
      }
    }
  }
}

Commands 和 Parameters 均按逐字段合并规则处理——新增命令被追加，预设原有命令保持不变[⁴]。风险等级受半格规则保护：若用户将自定义命令设为 Low，但预设同名命令为 High，合并结果仍为 High[⁵]。

5.2.4 阶段四：完全手动配置

当团队需求与预设分歧较大时，可脱离预设自主维护全部配置。此阶段不再声明 "Presets" 数组，直接在 "Connectors" 中定义完整连接器。用户承担全部安全属性设定责任，建议仅在团队已建立内部审查流程时采用。

5.3 预设发布的社区协作流程

当自定义预设经过内部验证并希望回馈社区时，需遵循代码规范、安全审查和文档配套三条主线。

5.3.1 贡献预设的代码规范

新增预设应遵循 ExternalCliPresetCatalog 的结构约定：预设 ID 使用 CLI 标准缩写，连接器名称与可执行文件名一致，标签至少包含工具品牌和技术领域两个维度[¹]。命令命名采用 snake_case，格式为 {noun}_{verb}，与内置预设风格保持一致。

5.3.2 安全审查清单

每条新增命令在提交 PR 前须通过以下审查：

命令面审查：ArgsTemplate 中是否存在无模式约束的注入点（如 {raw_input}）？
风险等级论证：命令是否为只读？是否涉及数据写入或 PII 返回？是否经与内置预设对照验证[⁶]？
审批必要性：命令执行后是否可逆？不可逆的变更型命令应标记 RequiresApproval: true。
参数约束完整性：每个 {placeholder} 是否在 Parameters 中有类型和模式定义？
合并兼容性：安全基线是否满足单调性——用户配置无法降低 RiskLevel、无法绕过 RequiresApproval[⁵]？

5.3.3 文档配套

每个新增预设须同步更新 docs/EXTERNAL_CLI_CONNECTORS.md，条目遵循 Preset ID → Connector → 命令矩阵 → 风险特征 → 使用示例的结构[⁷]。若预设包含 Medium 或 High 风险命令，文档中须明确说明触发审批的条件。完成上述清单的预设可通过 PR 提交至社区，此时已具备与 8 个内置预设同等的安全可信度。下一章将回顾核心要点并展望预设系统的演进方向。

6. 总结

6.1 核心要点回顾

本文系统梳理了 OpenClaw.NET 的 External CLI Preset 系统，贯穿全文的主线可归结为：安全不是配置后的检查项，而是设计一开始就嵌入系统结构的不可变属性。

第一道安全屏障是双层启用机制。Presets[] 默认空数组确保升级行为零变更，预设导入后连接器初始为 Enabled: false，必须在 Connectors 中单独启用方可执行。单层遗漏不会暴露命令面的设计，将误操作风险降至最低。

第二道屏障是三层合并引擎的安全代数。RiskLevel 的 Max 半格运算保证风险只升不降，ReadOnly 的 AND 合取闭包保证只读限制不放宽，RequiresApproval 的 OR 析取闭包保证审批不绕过。三项规则的共同特征是单调性——安全维度上永不减弱，预设基线不会被用户配置削弱。

在这两道屏障之上，8 个内置预设覆盖了版本控制、云原生、支付、协作和 AI Agent CLI 五大领域，命令面遵循"最小必要风险"原则：查询类操作锁定 Low，涉及 PII 或写入提升为 Medium，涉及外部数据传输固定为 High 并强制审批。

6.2 展望

当前 8 个内置预设只是起点。生态演进遵循两条路径：横向扩展，更多 CLI 工具（aws、pulumi、flyctl 等）通过社区 PR 进入内置目录，覆盖全栈云原生工具链；纵向深化，保守默认、显式启用、安全基线不可降的设计哲学为 REST API、数据库等其他外部系统接入提供了可迁移的安全架构模式。

OpenClaw.NET 作为 AI 网关治理中枢的演进方向，是将"安全内建于结构"的理念从 CLI 层推广到全部外部连接器层，使开发者在享受 AI 自动化效率的同时，始终拥有一条不可被绕过的安全基线。

预设系统保护的从不是某一条命令的安全执行，而是整个 AI 网关的命令面不被意外打开——这才是设计意图所在。

文章来源:https://www.cnblogs.com/shanyou/p/20047683
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：jacktools123@163.com进行投诉反馈，一经查实，立即删除！

标签：

上一篇：Agent Harness 的 Session Tree View：让每一个 Agent 做自己擅长的事情！
下一篇：PyTorch KernelAgent 源码解读 ---（3）--- orchestrator

首页 > 基础资料 博客日记