Подробное техническое описание внешнего соединителя CLI OpenClaw.NET (внешние соединители CLI) — 张善友

На основе документации: https://github.com/clawdotnet/openclaw.net/blob/main/docs/EXTERNAL_CLI_CONNECTORS.md.
На основе кода фиксации: https://github.com/clawdotnet/openclaw.net/commit/bde72ea12f05457d0d36422d627ffbe383fce1d8.
Дата выпуска: 10 мая 2026 г.

一, обзор архитектуры

Внешние разъемы CLI 是 OpenClaw.NET 一受控原生工作 (external_cli), для использования в официальном интерфейсе командной строки платформы (如GitHub CLI, Azure CLI, kubectl, Stripe CLI, Lark/Feishu CLI и т. д.)

Основная философия дизайна:

• отключено по умолчанию — Функциональность не будет включена автоматически, необходима для отображения конфигурации
• Не универсальный Shell — 不可以下载发动员设计, 可可以动发动力的具名发动的
• глубина обороны – путем присвоения имен командам в белом списке, рейтингу риска, предварительному просмотру, просмотру, просмотру, времени, записи аудита и событию времени выполнения для реализации многоуровневого контроля безопасности.

二、安全电视 (Модель безопасности)

2.1 Основной принцип безопасности

Внешний интерфейс командной строки может запускаться от имени мощного пользователя, робота, облака, кластера или платежа, поэтому:

• все最了性安全 (приказы на перемещение) считается высоким риском
• ИспользоватьНаименьшая привилегия (наименьшая привилегия)
• поддерживать сухой предварительный просмотр、процесс рассмотрения 和 журнал аудита

2.2 Метод вызова команды

разъем不电影去电影全电影строкаАгент, указав имя соединителя, имя команды и имя параметра:

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

При запуске параметры шаблона напрямую расширяются через конфигурацию. ProcessStartInfo.ArgumentList,Не через интерпретатор Shell，且这个电影最失或неизвестные параметры

2.3 Ключ по умолчанию

三、подробная конфигурация системы

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 (г) Например:

{
  "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 описание опции конфигурации команды

3.4 варианты проверки параметров

Каждый настраиваемый параметр:

• Required — 下载
• Description — описание параметра
• MaxLength — ограничение максимальной длины
• Pattern — 正则正语设计
• AllowedValues — список 安全值

四、电影与室批技术 (предварительный просмотр и утверждение)

4.1 порядок предварительного просмотра

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

4.2 предварительный просмотр информации о возврате

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 可设计режим пробного запуска（需原全在线了 DryRunArgsTemplate):

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

Примечание: время выполненияне догадаюсь Отметка пробного прогона，должна быть указана в шаблоне。

五、思思、事件与脱敏 (аудит, мероприятия и составление проектов)

5.1 Запись аудита (только аудит путем приложения)

Каждый раз, когда вы выполняете защищенную от изменений запись аудита, она содержит:

• соединительный разъем
• Путь к исполняемому файлу
• 已脱敏的安全行最好
• Параметры и параметры
• Исполнитель、разговор、канал、отправитель
• 实批指纹（如有）
• Код выхода, длительное время выполнения, отметка 超时
• флаг stdout/stderr 截断
• Классификация рисков и классификация работ

5.2 Эксплуатация

Запустить следующий тип события:

• status_check — государственная инспекция
• previewed / dry_run_previewed — предварительный просмотр
• dry_run_executed — Выполнение операции «сухая»
• command_executed — выполнение команды
• command_failed — команда не выполнена
• command_timed_out — 超时
• truncation – выход
• redaction — 脱脱敏
• command_blocked_by_policy — стратегия предотвращения

5.3 脚脱敏 (Редакционная статья)

脱敏применяется к: предварительному просмотру параметров, стандартному выводу, stderr, записи аудита, событию времени выполнения, сообщению об ошибке. Может использоваться в качестве коннектора или конфигурации команды. RedactionRules，поддержка формата ключа для конкретной платформы。

六、анализ вывода (анализ вывода)

按安全图像 StructuredOutput:

Примечание: разъем не вставляется целиком --json Логотип, необходимо отображать выходной логотип в каждом шаблоне команды.

七、手机设计全任 (консервативные пресеты)

7.1 Интерфейс командной строки GitHub (gh)

7.2 Azure CLI (az)

7.3 кубектл

Журнал может быть открыт для доступа к ключу, рекомендуется как минимум средний уровень риска.

7.4 Полосатый интерфейс командной строки

7.5 Жаворонок/Фейшу CLI

八、管理 API (API управления)

Использование RESTful Формат:

九、Команда CLI

# 列出所有连接器
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

十、 Архитектура реализации кода (Commit bde72ea)

10.1 Структура проекта

Это изменение фиксации 29 документов,+2966 строкКод включает в себя следующие модули:

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                 # 单元测试

10.2 Тип ядра и интерфейс

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

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

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

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

10.3 ключевые данные модели

// 连接器配置选项
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 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 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; }
    // ...
}

10.4 выполнение процесса

1. Вызов агента → ExternalCliTool получать запросы на инструменты
2. Стратегия анализа → ToolActionPolicyResolver 解析手机电视符（含 IsMutation、Нужно одобрение、Одобрение отпечатком пальца、Уровень риска、Только чтение）
3. предварительный просмотр сборки → ExternalCliConnectorRegistry.BuildPreview() Анализ шаблона, проверка параметров, расчет отпечатков пальцев
4. инспекция инспекция → Если оно соответствует
5. выполнить команду → ExternalCliRunner.ExecuteAsync() через ProcessStartInfo.ArgumentList начать процесс
6. анализ результатов → 按 StructuredOutput Установить анализ вывода
7. аудиторская запись → письмо ExternalCliAuditEntry(Невозможно подделать)
8. отправка события → через ExternalCliEventSink Отправить событие времени выполнения

10.5 Улучшение анализа стратегии

ToolActionDescriptor новое поле:

• RequiresApproval — если требуется
• ApprovalFingerprint — 室批指纹
• RiskLevel — уровень риска
• ReadOnly — 英语可读

OpenClawToolExecutor 中国手手机手机:

• Поддержка проверки проверки
• Если шаблон, параметры или стратегия будут изменены после пробной версии, несовпадение отпечатков пальцев предотвратит выполнение.

十一、飞书 (Feishu/Lark) Подробное руководство по настройке CLI

11.1 Понимание структуры

OpenClaw можно вызвать через внешний разъем CLI. lark-cli（официальный npm包 @larksuite/cli）来手机飞书。设计算:

1. Создано на открытой платформе 飞书.Самостоятельное применениеи получи сертификат
2. установка и настройка lark-cli
3. завершенныйавторизованный пользователь（Процесс авторизации устройства OAuth 2.0）
4. Конфигурация внешнего CLI в коннекторе OpenClaw

11.2 Шаг первый: Создайте приложение

1. Посетите открытую платформу

2. Создайте заявку

1. После входа в систему нажмите 右上角. 「Разработчик фона」
2. щелкнуть 「создать заявку」 → выбрать 「корпоративное приложение для самостоятельной сборки」
3. Введите название приложения (如「我的AI助助」）和описание).
4. щелкнуть 「подтверждение создано」

3. Включите возможности робота.

1. Левое меню → 「применимость」→「робот」
2. щелкнуть 「英语」

4. Получите сертификат

1. Левое меню → 「可语证与天物下载」
2. Скопируйте следующую информацию для резервного копирования:
   • Идентификатор приложения（这些如 cli_xxxxxxxxx）
   • Секрет приложения(Нажмите «Просмотр», чтобы отобразить весь контент, сохраните его)

5. Разрешить доступ
Левое меню → 「电影电影」найдите и откройте следующий ресурс:

6. Заявление о выпуске

1. Левое меню → 「управление версиями и выпуск」
2. 「создать версию」 → Заполните описание версии → “преданный идее”
3. Ожидание одобрения

11.3 Шаг 2. Установка и настройка Lark-Cli

1. Установка Lac-cli

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

# 验证安装
lark-cli --version

2. 定作度证（电影式）

lark-cli config init --new

Введите идентификатор приложения и секрет приложения.

3. 设计度证（非电影式/автоматизация）

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

--brand feishu Для внутреннего использования 版飞书, международного использования 版 Lark. --brand lark。

4. проверьте конфигурацию

lark-cli doctor

应电影电影правильная конфигурация、действительный сертификат。

11.4 Шаг третий: авторизация пользователя (авторизация устройства OAuth 2.0)

1. ក្រ្រ្រ្រ

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=..."
}

2. Полная авторизация
копировать verification_url Приложение 到电视电影电影，使用飞书怤码技术。

3. Завершите вход
Выполните после сканирования кода:

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

4. 公司电影电视入(如递documents电影能力）

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

Повторите процесс авторизации по скан-коду.

11.5 Шаг 4. Проверьте функциональность Lark-cli

# 搜索文档
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"

11.6 Шаг 五:在 OpenClaw 中设计 Feishu Внешний разъем CLI

В файл конфигурации OpenClaw добавлено:

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

11.7 Шаг 6. Проверьте интеграцию OpenClaw

# 查看连接器状态
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

11.8 Режим ленивого человека

Вы также можете позволить AI-помощнику автоматически выполнить большую часть работы по настройке:

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

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

十二、полные возможности Lark-Cli一解

十三、лучшая практика и осторожность

13.1 Рекомендации по обеспечению безопасности

1. принцип минимальных полномочий — 只开通安全最好的最新的
2. Обзор операции — Все в порядке записи/изменения RequiresApproval: true
3. Использовать только предустановку чтения — Первоначальная конфигурация разрешает только операцию чтения.
4. Мониторинг журналов аудита — регулярный осмотр external_cli Аудиторская запись
5. конфигурация — 作电影安全安全证证的安全旅行 RedactionRules
6. Установите разумное время — По заданным командным характеристикам TimeoutSeconds

13.2 Общие вопросы

十四, заключение

OpenClaw.NET 的 Внешние соединители CLI предоставляет возможности安全、受控、можно проверитьИнтерфейс командной строки интегрирован в AI Agent.Белое имя команды присвоения имен, шаблон параметра, рейтинг риска, процесс предварительного просмотра и проверки, 脱脱敏和实迗和实迗等 множественный механизм безопасности, реализованный одновременно с сохранением глубины платформы для обеспечения безопасной работы.

正解飞书/Фейху 电影, проход lark-cli Внешний разъем CLI. AI-агент может безопасно читать документ, запрашивать календарь, отправлять сообщения и т. д. Все изменения в операциях необходимо проверять, чтобы обеспечить безопасность корпоративных данных.