qclaw-openclaw

QClaw OpenClaw CLI

MANDATORY — Required reading

This environment does not have a globally installed openclaw CLI。 directly executing the openclaw command will fail.

All operations that require calling the openclaw CLI (including but not limited to config、cron、skills、plugins、models、status etc.), must and can onlybe executed through the wrapper scripts provided by this skill. Do not attempt:

❌ openclaw config get ...(the global command does not exist)
❌ npx openclaw ...(environment variables are incorrect)
❌ Directly calling node openclaw.mjs ...(missing necessary environment variables and paths)

The correct approach is to use this skill's scripts, which will automatically set all necessary environment variables and paths.

The OpenClaw service is managed by the QClaw Electron daemon (automatic startup, circuit breaker protection); directly starting or stopping the service via the CLI is prohibited.

Execution method

This skill provides cross-platform scripts, located in the skill directory under scripts/ . The scripts will automatically read the runtime path and environment variables from ~/.qclaw/qclaw.json .

macOS

bash <skill_dir>/scripts/openclaw-mac.sh <command> [args...]

Windows

<skill_dir>\scripts\openclaw-win.cmd <command> [args...]

<skill_dir> is the directory path where this SKILL.md is located.

Allowed commands

config — configuration management

# 读取配置值
bash <skill_dir>/scripts/openclaw-mac.sh config get <dot.path>

# 设置配置值
bash <skill_dir>/scripts/openclaw-mac.sh config set <dot.path> <value>

# 删除配置值
bash <skill_dir>/scripts/openclaw-mac.sh config unset <dot.path>

Example:

# 查看当前网关端口
bash <skill_dir>/scripts/openclaw-mac.sh config get gateway.port

# 设置默认模型
bash <skill_dir>/scripts/openclaw-mac.sh config set agents.defaults.model.primary "claude-sonnet-4-20250514"

Configuration effective rules: OpenClaw configuration changes uniformly support hot reloading, taking effect automatically within the process after modification. Strictly prohibited to perform any service restart behavior (including but not limited to gateway/daemon restart、kill PID、taskkill）。

[MANDATORY] Official Schema validation rules before modification

For all operations that modify openclaw.json , official documentation validation must first be completed:

Check official documentation first: Before modification, you must first check the OpenClaw official documentation for the corresponding configuration item (field path, type, allowed values, constraints, default value).
Refuse if unable to confirm: If no corresponding official documentation is found, or it cannot be confirmed that the field conforms to the official schema, this modification must be refused; do not guess fields or write by trial and error.
Only writing officially defined fields is allowed: Adding or writing fields not defined by the official schema is prohibited, and writing values with mismatched types is prohibited.
Confirm first, then write to disk: Only after confirming that the change conforms to the official schema is it allowed to execute config set/unset or other write operations.

Refusal wording requirement: When there is no official schema basis, clearly reply "Missing OpenClaw official schema basis, refusing to modify openclaw.json”。

[MANDATORY] Automatic rollback rules for configuration modification failures

For all operations that modify the openclaw.json configuration file, the following transactional rules must be followed:

Back up first, then modify: Before executing the modification, first save a pre-modification snapshot of openclaw.json (used only for rollback of this change).
Roll back on failure: If the context log/execution result shows that this modification failed (regardless of the reason for failure), you must immediately roll back to the pre-modification snapshot of this change.
Only roll back this change: The rollback target is to revoke the current modification only; do not overwrite earlier historically valid configurations.
Do not skip rollback: After a failure is detected, continuing subsequent configuration writes is not allowed; the rollback must be completed first before continuing.
Post-rollback Verification: After the rollback is complete, the target configuration item must be re-read to confirm that it has been restored to the state before the modification.

cron — Scheduled Tasks

# 列出所有定时任务
bash <skill_dir>/scripts/openclaw-mac.sh cron list

# 添加定时任务
bash <skill_dir>/scripts/openclaw-mac.sh cron add --trigger "<cron_expression>" --action "<prompt>"

# 编辑定时任务
bash <skill_dir>/scripts/openclaw-mac.sh cron edit <job_id> --trigger "<cron_expression>"

# 启用/禁用定时任务
bash <skill_dir>/scripts/openclaw-mac.sh cron enable <job_id>
bash <skill_dir>/scripts/openclaw-mac.sh cron disable <job_id>

# 删除定时任务
bash <skill_dir>/scripts/openclaw-mac.sh cron rm <job_id>

# 立即运行（调试）
bash <skill_dir>/scripts/openclaw-mac.sh cron run <job_id>

# 查看执行历史
bash <skill_dir>/scripts/openclaw-mac.sh cron runs

# 查看调度器状态
bash <skill_dir>/scripts/openclaw-mac.sh cron status

models — Model Configuration

# 查看已配置模型
bash <skill_dir>/scripts/openclaw-mac.sh models list

# 查看模型状态
bash <skill_dir>/scripts/openclaw-mac.sh models status

# 设置默认模型
bash <skill_dir>/scripts/openclaw-mac.sh models set <model_id>

# 设置图像模型
bash <skill_dir>/scripts/openclaw-mac.sh models set-image <model_id>

# 管理模型别名
bash <skill_dir>/scripts/openclaw-mac.sh models aliases --help

# 管理 fallback 列表
bash <skill_dir>/scripts/openclaw-mac.sh models fallbacks --help

skills — Skills Management

# 列出所有 skills
bash <skill_dir>/scripts/openclaw-mac.sh skills list

# 查看 skill 详情
bash <skill_dir>/scripts/openclaw-mac.sh skills info <skill_name>

# 检查 skills 就绪状态
bash <skill_dir>/scripts/openclaw-mac.sh skills check

plugins — Plugin Management

# 列出所有插件
bash <skill_dir>/scripts/openclaw-mac.sh plugins list

# 查看插件详情
bash <skill_dir>/scripts/openclaw-mac.sh plugins info <plugin_id>

# 启用/禁用插件
bash <skill_dir>/scripts/openclaw-mac.sh plugins enable <plugin_id>
bash <skill_dir>/scripts/openclaw-mac.sh plugins disable <plugin_id>

# 安装/卸载插件
bash <skill_dir>/scripts/openclaw-mac.sh plugins install <path_or_spec>
bash <skill_dir>/scripts/openclaw-mac.sh plugins uninstall <plugin_id>

# 诊断插件问题
bash <skill_dir>/scripts/openclaw-mac.sh plugins doctor

agents — Agent Workspace Management

# 列出 agents
bash <skill_dir>/scripts/openclaw-mac.sh agents list

# 添加新 agent
bash <skill_dir>/scripts/openclaw-mac.sh agents add <name>

# 删除 agent
bash <skill_dir>/scripts/openclaw-mac.sh agents delete <name>

# 设置 agent 身份
bash <skill_dir>/scripts/openclaw-mac.sh agents set-identity <name> --emoji "🤖"

channels — Channel Management

# 列出通道
bash <skill_dir>/scripts/openclaw-mac.sh channels list

# 查看通道状态
bash <skill_dir>/scripts/openclaw-mac.sh channels status

# 查看通道能力
bash <skill_dir>/scripts/openclaw-mac.sh channels capabilities

# 查看通道日志
bash <skill_dir>/scripts/openclaw-mac.sh channels logs

gateway — Gateway Status Query (read-only)

# 查看网关详细状态（只读，不操作服务）
bash <skill_dir>/scripts/openclaw-mac.sh gateway status

Other Allowed Commands

# 系统状态
bash <skill_dir>/scripts/openclaw-mac.sh status

# 网关健康检查
bash <skill_dir>/scripts/openclaw-mac.sh health

# 诊断
bash <skill_dir>/scripts/openclaw-mac.sh doctor

# 安全审计
bash <skill_dir>/scripts/openclaw-mac.sh security audit

# 记忆搜索
bash <skill_dir>/scripts/openclaw-mac.sh memory search <query>
bash <skill_dir>/scripts/openclaw-mac.sh memory status

# 会话列表
bash <skill_dir>/scripts/openclaw-mac.sh sessions list

# 日志查看
bash <skill_dir>/scripts/openclaw-mac.sh logs --follow

# 执行审批管理
bash <skill_dir>/scripts/openclaw-mac.sh approvals get
bash <skill_dir>/scripts/openclaw-mac.sh approvals allowlist --help

# 更新检查（仅查看状态，不执行更新）
bash <skill_dir>/scripts/openclaw-mac.sh update status

Forbidden Commands

The following commandsare strictly forbidden from being executed. The OpenClaw service lifecycle is uniformly managed by the QClaw Electron daemon:

Command	Reason
`gateway run/start/stop/restart`	The service is managed by the Electron ProcessSupervisor
`gateway install/uninstall`	System service installation is controlled by Electron

Note: gateway status isallowed. It only queries status and does not operate the service. | daemon start/stop/restart | Same as above; daemon is an alias for gateway | | daemon install/uninstall | Same as above | | node start/stop | Node host service management | | reset | Destructive operation; will clear all local configuration and state | | uninstall | Destructive operation; will uninstall the service and data |

Configuration Hot Reload and In-Process Take Effect

OpenClaw configuration modifications uniformly use a hot reload mechanism:

After executing config set/unset through this skill, there is no need to restart the service
the configuration will automatically reload and take effect within the current process
Any form of service restart operation is forbidden (including gateway/daemon restart、kill、taskkill）

If the configuration does not take effect immediately, first use read-only commands to check the current status:

bash <skill_dir>/scripts/openclaw-mac.sh config get <dot.path>
bash <skill_dir>/scripts/openclaw-mac.sh status
bash <skill_dir>/scripts/openclaw-mac.sh health

Troubleshooting

`~/.qclaw/qclaw.json` does not exist

The QClaw desktop application is not started or did not successfully start the OpenClaw service. Please start the QClaw application first.

Invalid PID (process does not exist)

During the configuration hot reload process, the status may be briefly updated. Wait a few seconds and then query status/health again.

Command execution reports Gateway connection failure

The Gateway service may not be ready. First check the health status:

bash <skill_dir>/scripts/openclaw-mac.sh health

If it continues to fail, execute doctor and collect logs; do not perform any restart operations.

Script reports that the Node binary or openclaw.mjs cannot be found

qclaw.json The path in may be outdated (the path changes after an application upgrade). Please execute status/doctor to re-validate the metadata and collect logs for feedback.