OpenClaw.NET 外部 CLI 连接器 (External CLI Connectors) 详细技术总结

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

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

{
  "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 }
        }
      }
    }
  }
}

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

# 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

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

# 列出所有连接器
openclaw external list

# 查看连接器状态
openclaw external status gh

# 列出连接器命令
openclaw external commands gh

# 预览命令
openclaw external preview gh repo_view --param repo=clawdotnet/openclaw.net

# 执行命令
openclaw external execute gh repo_view --param repo=clawdotnet/openclaw.net

# 使用 --json 获取机器可读输出
openclaw external list --json

docs/
  EXTERNAL_CLI_CONNECTORS.md          # 新增完整文档 (278行)
  README.md                           # 添加文档链接
  SITE_MAP.md                         # 添加站点地图

src/OpenClaw.Agent/
  OpenClawToolExecutor.cs             # 工具执行器集成 (+29/-4)
  Tools/ExternalCliTool.cs            # 新增 External CLI 工具实现 (251行)

src/OpenClaw.Client/
  OpenClawHttpClient.cs               # HTTP 客户端新增 Admin API 方法 (+51行)

src/OpenClaw.Cli/
  CliArgs.cs                          # CLI 参数解析扩展
  ExternalCliCommands.cs              # 新增 CLI 命令实现 (250行)
  OpenClawHttpClient.cs               # CLI HTTP 客户端包装 (+15行)
  Program.cs                          # 注册 external 子命令 (+3行)

src/OpenClaw.Core/
  Abstractions/IToolActionDescriptorProvider.cs  # 抽象接口
  ExternalCli/
    ExternalCliServices.cs            # DI 服务注册
    ExternalCliConnectorRegistry.cs   # 连接器注册表
    ExternalCliRunner.cs              # 命令执行器
  Models/
    ExternalCliModels.cs              # 数据模型 (284行)
    GatewayConfig.cs                  # 配置集成 (+1行)
    Session.cs                        # JSON 序列化 (+26行)
    ToolingPolicyModels.cs            # 策略模型 (+4行)
  Pipeline/ToolActionPolicyResolver.cs # 策略解析 (+27/-1)
  Validation/ConfigValidator.cs       # 配置验证 (+78行)

src/OpenClaw.Gateway/
  Composition/                         # DI 组合注册
  Endpoints/AdminEndpoints.ExternalCli.cs  # Admin API 端点 (264行)
  Endpoints/ExternalCliStores.cs      # 存储抽象

OpenClaw.Tests/
  ExternalCliTests.cs                 # 单元测试

// 连接器注册表
public interface IExternalCliConnectorRegistry
{
    ExternalCliPreparedInvocation BuildPreview(ExternalCliPreviewRequest request, bool dryRun);
}

// 命令执行器
public interface IExternalCliRunner
{
    Task<ExternalCliExecutionResult> ExecuteAsync(ExternalCliPreparedInvocation prepared, CancellationToken ct);
}

// 审计 Sink
public interface IExternalCliAuditSink { void Record(ExternalCliAuditEntry entry); }

// 事件 Sink
public interface IExternalCliEventSink { void Record(ExternalCliRuntimeEvent evt); }

// 连接器配置选项
public sealed class ExternalCliConnectorOptions
{
    public bool Enabled { get; set; } = false;
    public string DisplayName { get; set; } = "";
    public string Executable { get; set; } = "";
    public string DefaultOutputFormat { get; set; } = "json";
    public ExternalCliStatusCommandOptions? StatusCommand { get; set; }
    public ExternalCliStatusCommandOptions? VersionCommand { get; set; }
    public Dictionary<string, ExternalCliCommandOptions> Commands { get; set; } = new();
    // ...
}

// 命令配置选项
public sealed class ExternalCliCommandOptions
{
    public string Description { get; set; } = "";
    public string[] ArgsTemplate { get; set; } = [];
    public string[]? DryRunArgsTemplate { get; set; }
    public string RiskLevel { get; set; } = ExternalCliRiskLevel.High;
    public bool ReadOnly { get; set; } = false;
    public bool RequiresApproval { get; set; } = false;
    public string StructuredOutput { get; set; } = ExternalCliOutputFormat.Text;
    public Dictionary<string, ExternalCliParameterOptions> Parameters { get; set; } = new();
    // ...
}

// 执行结果
public sealed class ExternalCliExecutionResult
{
    public ExternalCliInvocationPreview Preview { get; init; } = new();
    public int ExitCode { get; init; }
    public double DurationMs { get; init; }
    public bool TimedOut { get; init; }
    public bool Failed { get; init; }
    public bool StdoutTruncated { get; init; }
    public bool StderrTruncated { get; init; }
    // ...
}

// 审计记录
public sealed class ExternalCliAuditEntry
{
    public string Id { get; init; } = "";
    public DateTimeOffset TimestampUtc { get; init; }
    public string SessionId { get; init; } = "";
    public string Connector { get; init; } = "";
    public string Command { get; init; } = "";
    public string RedactedArgsPreview { get; init; } = "";
    public string? ApprovalFingerprint { get; init; }
    public int ExitCode { get; init; }
    // ...
}

# 全局安装
npm install -g @larksuite/cli

# 验证安装
lark-cli --version

lark-cli config init --new

echo "你的App Secret" | lark-cli config init \
  --app-id "你的AppID" \
  --app-secret-stdin \
  --brand feishu

lark-cli doctor

lark-cli auth login --no-wait --recommend --json

{
  "device_code": "ABC123XYZ",
  "user_code": "ABCD1234",
  "verification_url": "https://open.feishu.cn/open-apis/authen/v1/scan?qrcode=..."
}

lark-cli auth login --device-code "ABC123XYZ"

lark-cli auth login --no-wait --scope "search:docs:read" --json

# 搜索文档
lark-cli docs +search --query "文档" --as user

# 创建文档
lark-cli docs +create --title "测试文档" --markdown "# 你好世界"

# 查询日历
lark-cli calendar +agenda --as user

# 发送消息
lark-cli message +send --to-user "user_open_id" --text "Hello from CLI"

{
  "OpenClaw": {
    "ExternalCli": {
      "Enabled": true,
      "DefaultTimeoutSeconds": 60,
      "MaxStdoutBytes": 262144,
      "MaxStderrBytes": 65536,
      "RedactSecrets": true,
      "AllowFreeformCommands": false,
      "RequireApprovalForMutatingCommands": true,
      "Connectors": {
        "lark": {
          "Enabled": true,
          "DisplayName": "Lark/Feishu CLI",
          "Executable": "lark-cli",
          "DefaultOutputFormat": "json",
          "StatusCommand": {
            "Args": ["auth", "status"],
            "TimeoutSeconds": 20
          },
          "VersionCommand": {
            "Args": ["--version"],
            "TimeoutSeconds": 10
          },
          "Commands": {
            "auth_status": {
              "Description": "Check lark-cli auth status",
              "ArgsTemplate": ["auth", "status"],
              "RiskLevel": "low",
              "ReadOnly": true,
              "StructuredOutput": "text",
              "Parameters": {}
            },
            "docs_search": {
              "Description": "Search Feishu documents",
              "ArgsTemplate": ["docs", "+search", "--query", "{{query}}", "--as", "user", "--json"],
              "RiskLevel": "low",
              "ReadOnly": true,
              "StructuredOutput": "json",
              "Parameters": {
                "query": { "Required": true, "MaxLength": 200 }
              }
            },
            "docs_read": {
              "Description": "Read a Feishu document",
              "ArgsTemplate": ["docs", "+get", "{{doc_id}}", "--as", "user"],
              "RiskLevel": "low",
              "ReadOnly": true,
              "StructuredOutput": "json",
              "Parameters": {
                "doc_id": { "Required": true }
              }
            },
            "docs_create": {
              "Description": "Create a Feishu document",
              "ArgsTemplate": ["docs", "+create", "--title", "{{title}}", "--markdown", "{{content}}"],
              "RiskLevel": "medium",
              "ReadOnly": false,
              "RequiresApproval": true,
              "StructuredOutput": "json",
              "Parameters": {
                "title": { "Required": true, "MaxLength": 200 },
                "content": { "Required": true, "MaxLength": 50000 }
              }
            },
            "calendar_agenda": {
              "Description": "Query calendar agenda",
              "ArgsTemplate": ["calendar", "+agenda", "--as", "user"],
              "RiskLevel": "low",
              "ReadOnly": true,
              "StructuredOutput": "json",
              "Parameters": {}
            },
            "message_send": {
              "Description": "Send a Feishu message",
              "ArgsTemplate": ["message", "+send", "--to-user", "{{to}}", "--text", "{{text}}"],
              "RiskLevel": "medium",
              "ReadOnly": false,
              "RequiresApproval": true,
              "StructuredOutput": "text",
              "Parameters": {
                "to": { "Required": true },
                "text": { "Required": true, "MaxLength": 2000 }
              }
            }
          }
        }
      }
    }
  }
}

# 查看连接器状态
openclaw external status lark

# 列出可用命令
openclaw external commands lark

# 预览搜索文档命令
openclaw external preview lark docs_search --param query="项目计划"

# 执行搜索（如需要审批，先预览再加 --yes）
openclaw external execute lark docs_search --param query="项目计划" --yes

# 预览创建文档（变更命令，需要审批）
openclaw external preview lark docs_create \
  --param title="会议纪要 2026-05-10" \
  --param content="# 会议纪要\n\n## 参与人\n- ..."

# 审批后执行
openclaw external execute lark docs_create \
  --param title="会议纪要 2026-05-10" \
  --param content="# 会议纪要\n\n## 参与人\n- ..." \
  --yes

帮我配置飞书云文档能力。请按以下步骤做：

1. 检查是否安装了 lark-cli，如果没有则执行：
   npm install -g @larksuite/cli

2. 运行 lark-cli doctor 检查当前状态

3. 如果显示缺少凭证配置，问我 App ID 和 App Secret

4. 拿到凭证后完成配置：
   echo "AppSecret" | lark-cli config init --app-id "AppID" --app-secret-stdin --brand feishu

5. 运行 lark-cli auth login --no-wait --recommend --json
   把返回的 verification_url 发给我，告诉我扫码授权

6. 我扫码确认后，用返回的 device_code 执行登录

7. 如果缺少搜索权限，按上面的方式再走一遍授权流程补充 search:docs:read

8. 全部完成后，用以下命令验证各项能力：
   - lark-cli docs +search --query "文档" --as user
   - lark-cli docs +create --title "测试文档" --markdown "# 你好"
   - lark-cli calendar +agenda --as user