cli-anything-openclaw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClaw Macro System CLI

What It Is

是什么

The OpenClaw Macro System converts valuable GUI workflows into parameterized, CLI-callable macros. Agents never touch the GUI directly — they call macros through this stable CLI, and the runtime routes execution to the best available backend (native plugin/API, file transformation, semantic UI control, or precompiled GUI macro replay).

OpenClaw Macro System可将有价值的GUI工作流转换为可参数化、可通过CLI调用的宏。Agent绝不会直接操作GUI——它们通过这个稳定的CLI调用宏，运行时会将执行路由到最佳可用后端（原生插件/API、文件转换、语义UI控制或预编译的GUI宏重放）。

Installation

安装

bash

cd openclaw-skill/agent-harness
pip install -e .

Requirements: Python 3.10+, PyYAML, click, prompt-toolkit.

bash

cd openclaw-skill/agent-harness
pip install -e .

要求： Python 3.10+、PyYAML、click、prompt-toolkit。

Quick Start (for agents)

快速入门（面向Agent）

bash

undefined

bash

undefined

1. See what macros are available

1. 查看可用的宏

cli-anything-openclaw macro list --json

2. Inspect a macro's parameters

2. 查看宏的参数

cli-anything-openclaw macro info export_file --json

3. Dry-run to check params without side effects

3. 空运行以检查参数，无副作用

cli-anything-openclaw --dry-run macro run export_file
--param output=/tmp/test.txt --json

4. Execute a macro

4. 执行宏

cli-anything-openclaw macro run export_file
--param output=/tmp/result.txt --json

5. See what backends are available

5. 查看可用的后端

cli-anything-openclaw backends --json

undefined

cli-anything-openclaw backends --json

undefined

Command Reference

命令参考

Global Flags

全局标志

Flag	Description
`--json`	Machine-readable JSON output on stdout
`--dry-run`	Simulate all steps, skip side effects
`--session-id <id>`	Resume or create a named session

标志	描述
`--json`	在标准输出打印机器可读的JSON格式内容
`--dry-run`	模拟所有步骤，跳过副作用操作
`--session-id <id>`	恢复或创建一个命名会话

macro

group

macro

命令组

Command	Description
`macro list`	List all available macros
`macro info <name>`	Show macro schema (parameters, steps, conditions)
`macro run <name> --param k=v`	Execute a macro
`macro dry-run <name> --param k=v`	Simulate without side effects
`macro validate [name]`	Structural validation
`macro define <name>`	Scaffold a new macro YAML

命令	描述
`macro list`	列出所有可用的宏
`macro info <name>`	显示宏的Schema（参数、步骤、条件）
`macro run <name> --param k=v`	执行宏
`macro dry-run <name> --param k=v`	模拟执行，无副作用
`macro validate [name]`	结构验证
`macro define <name>`	生成新宏的YAML模板

session

group

session

命令组

Command	Description
`session status`	Show session statistics
`session history`	Show recent run history
`session save`	Persist session to disk
`session list`	List all saved sessions

命令	描述
`session status`	显示会话统计信息
`session history`	显示最近的运行历史
`session save`	将会话持久化到磁盘
`session list`	列出所有已保存的会话

backends

backends

bash

cli-anything-openclaw backends --json

bash

cli-anything-openclaw backends --json

Shows: native_api, file_transform, semantic_ui, gui_macro, recovery

显示：native_api、file_transform、semantic_ui、gui_macro、recovery

and whether each is available in the current environment.

以及每个后端在当前环境中是否可用。

undefined

undefined

Macro Parameters

宏参数

Pass parameters with

--param key=value

. Repeat for multiple:

bash

cli-anything-openclaw macro run transform_json \
    --param file=/path/to/data.json \
    --param key=settings.theme \
    --param value=dark \
    --json

使用

--param key=value

传递参数，多个参数可重复使用：

bash

cli-anything-openclaw macro run transform_json \
    --param file=/path/to/data.json \
    --param key=settings.theme \
    --param value=dark \
    --json

Output Format (--json)

输出格式（--json）

All commands output JSON when

--json

is set:

json

{
  "success": true,
  "macro_name": "export_file",
  "output": {
    "exported_file": "/tmp/result.txt"
  },
  "error": "",
  "telemetry": {
    "duration_ms": 312,
    "steps_total": 2,
    "steps_run": 2,
    "backends_used": ["native_api"],
    "dry_run": false
  }
}

On failure (

"success": false

), read the

"error"

field for the reason. Exit code is 1 on failure.

当设置

--json

时，所有命令都会输出JSON格式内容：

json

{
  "success": true,
  "macro_name": "export_file",
  "output": {
    "exported_file": "/tmp/result.txt"
  },
  "error": "",
  "telemetry": {
    "duration_ms": 312,
    "steps_total": 2,
    "steps_run": 2,
    "backends_used": ["native_api"],
    "dry_run": false
  }
}

失败时（

"success": false

），请查看

"error"

字段了解原因。失败时退出码为1。

Execution Backends

执行后端

Backends are selected automatically based on the macro step definition:

Backend	Triggered by	Use case
`native_api`	`backend: native_api`	Subprocess / shell command
`file_transform`	`backend: file_transform`	XML, JSON, text file editing
`semantic_ui`	`backend: semantic_ui`	Accessibility / keyboard shortcuts
`gui_macro`	`backend: gui_macro`	Precompiled coordinate replay
`recovery`	`backend: recovery`	Retry / fallback orchestration

后端会根据宏步骤定义自动选择：

后端	触发条件	使用场景
`native_api`	`backend: native_api`	子进程/Shell命令
`file_transform`	`backend: file_transform`	XML、JSON、文本文件编辑
`semantic_ui`	`backend: semantic_ui`	无障碍访问/键盘快捷键
`gui_macro`	`backend: gui_macro`	预编译坐标重放
`recovery`	`backend: recovery`	重试/降级编排

Writing Macros

编写宏

Macros are YAML files in

cli_anything/openclaw/macro_definitions/

. Scaffold one with:

bash

cli-anything-openclaw macro define my_macro --output \
    cli_anything/openclaw/macro_definitions/examples/my_macro.yaml

Minimal schema:

yaml

name: my_macro
version: "1.0"
description: What this macro does.

parameters:
  output:
    type: string
    required: true
    description: Where to write results.
    example: /tmp/result.txt

preconditions:
  - file_exists: /path/to/input

steps:
  - id: step1
    backend: native_api
    action: run_command
    params:
      command: [my-app, --export, "${output}"]
    timeout_ms: 30000
    on_failure: fail  # or: skip, continue

postconditions:
  - file_exists: ${output}
  - file_size_gt: [${output}, 100]

outputs:
  - name: result_file
    path: ${output}

agent_hints:
  danger_level: safe  # safe | moderate | dangerous
  side_effects: [creates_file]
  reversible: true

宏是存储在

cli_anything/openclaw/macro_definitions/

目录下的YAML文件。使用以下命令生成模板：

bash

cli-anything-openclaw macro define my_macro --output \
    cli_anything/openclaw/macro_definitions/examples/my_macro.yaml

最小化Schema：

yaml

name: my_macro
version: "1.0"
description: What this macro does.

parameters:
  output:
    type: string
    required: true
    description: Where to write results.
    example: /tmp/result.txt

preconditions:
  - file_exists: /path/to/input

steps:
  - id: step1
    backend: native_api
    action: run_command
    params:
      command: [my-app, --export, "${output}"]
    timeout_ms: 30000
    on_failure: fail  # or: skip, continue

postconditions:
  - file_exists: ${output}
  - file_size_gt: [${output}, 100]

outputs:
  - name: result_file
    path: ${output}

agent_hints:
  danger_level: safe  # safe | moderate | dangerous
  side_effects: [creates_file]
  reversible: true

Agent Usage Rules

Agent使用规则

Always use
--json
for programmatic output.
Use
--dry-run
to validate params before executing side-effectful macros.
Check
success
field — do not assume success from exit code alone.
Read
error
field when
```
success
```
is false — it explains what failed.
Use
macro info <name>
to discover params before calling
```
macro run
```
.
Use absolute paths for all file parameters.

始终使用
--json
以获取程序化输出。
执行有副作用的宏前，使用
--dry-run
验证参数。
检查
success
字段——不要仅通过退出码判断执行成功。
当
success
为false时，查看
error
字段——它会解释失败原因。
调用
macro run
前，使用
macro info <name>
了解参数信息。
所有文件参数请使用绝对路径。

Example Workflow

示例工作流

bash

undefined

bash

undefined

Step 1: What's available?

步骤1：查看可用的宏

cli-anything-openclaw macro list --json

Step 2: What params does transform_json need?

步骤2：查看transform_json需要哪些参数

cli-anything-openclaw macro info transform_json --json

Step 3: Test safely

步骤3：安全测试

cli-anything-openclaw --dry-run macro run transform_json
--param file=/tmp/config.json
--param key=theme
--param value=dark --json

Step 4: Execute for real

步骤4：实际执行

cli-anything-openclaw macro run transform_json
--param file=/tmp/config.json
--param key=theme
--param value=dark --json

undefined

cli-anything-openclaw macro run transform_json
--param file=/tmp/config.json
--param key=theme
--param value=dark --json

undefined

Version

版本

1.0.0

cli-anything-openclaw

Original

Translation

OpenClaw Macro System CLI

OpenClaw Macro System CLI

What It Is

是什么

Installation

安装

Quick Start (for agents)

快速入门（面向Agent）

1. See what macros are available

1. 查看可用的宏

2. Inspect a macro's parameters

2. 查看宏的参数

3. Dry-run to check params without side effects

3. 空运行以检查参数，无副作用

4. Execute a macro

4. 执行宏

5. See what backends are available

5. 查看可用的后端

Command Reference

命令参考

Global Flags

全局标志

macro group

macro命令组

session group

session命令组

backends

backends

Shows: native_api, file_transform, semantic_ui, gui_macro, recovery

显示：native_api、file_transform、semantic_ui、gui_macro、recovery

and whether each is available in the current environment.

以及每个后端在当前环境中是否可用。

Macro Parameters

宏参数

Output Format (--json)

输出格式（--json）

Execution Backends

执行后端

Writing Macros

编写宏

Agent Usage Rules

Agent使用规则

Example Workflow

示例工作流

Step 1: What's available?

步骤1：查看可用的宏

Step 2: What params does transform_json need?

步骤2：查看transform_json需要哪些参数

Step 3: Test safely

步骤3：安全测试

Step 4: Execute for real

步骤4：实际执行

Version

版本

`macro`
group

`macro`
命令组

`session`
group

`session`
命令组

`backends`

`backends`