#第 6 章：自动化命令与脚本集成

难度: ⭐⭐ 基础 | 预计阅读: 20 分钟 | 前置章节: 第 1-2 章

本章讲解如何利用 OpenClaw 的自动化能力，包括命令行工具、脚本集成、钩子系统和定时任务，实现无人值守的自动化工作流。你将学会用 CLI 管理 OpenClaw 实例、配置 Hook 扩展事件处理、设置 Cron 定时任务，以及将外部脚本和工具集成到 Agent 工作流中。

#6.1 OpenClaw 命令行工具

OpenClaw 提供完整的 CLI 工具集，覆盖服务管理、配置读写、会话操作和诊断排错等场景。CLI 是除 Web Dashboard 之外与 OpenClaw 交互的主要方式，也是脚本自动化的基础。

#命令分类总览

下表列出 OpenClaw CLI 的主要命令类别及其用途：

#核心命令

以下是日常使用最频繁的命令，建议反复练习直至熟记：

openclaw status          # 查看服务状态
openclaw doctor          # 系统诊断（检查端口、依赖、配置等）
openclaw gateway start   # 启动 Gateway
openclaw gateway stop    # 停止 Gateway
openclaw daemon install  # 安装系统服务（开机自启）
openclaw daemon status   # 查看守护进程运行状态
openclaw logs --follow   # 实时查看日志（Ctrl+C 退出）
openclaw dashboard       # 打开 Web 控制台

#配置管理

OpenClaw 的运行时配置存储在 ~/.openclaw/openclaw.json 中，可通过 CLI 读写：

# 读取单项配置
openclaw config get gateway.port

# 修改配置项（立即生效，无需重启）
openclaw config set gateway.port 18789

# 查看完整配置
cat ~/.openclaw/openclaw.json | python3 -m json.tool

#会话管理

会话（Session）是 Agent 执行任务的上下文环境。每个会话拥有独立的对话历史和工作目录：

openclaw session list     # 查看活跃会话（含 ID、创建时间、状态）
openclaw session new      # 创建新会话

#6.2 Hook 钩子系统

Hook 是 OpenClaw 的事件驱动扩展机制，在特定生命周期节点自动执行预定义逻辑。通过 Hook，你可以在会话启动时加载上下文、在命令执行后记录日志、在会话结束时持久化记忆，实现无需手动干预的智能化流程。

#内置 Hook

OpenClaw 默认提供以下 Hook，开箱即用：

#Hook 执行流程

Hook 的执行遵循以下生命周期顺序：

Gateway 启动 → boot-md(加载上下文) → bootstrap-extra-files(补充文件)
    ↓
会话进行中 → command-logger(记录每条命令)
    ↓
会话结束 → session-memory(保存记忆)

#配置 Hook

在 ~/.openclaw/openclaw.json 中配置 Hook 的启用状态和条目列表：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": [
        "boot-md",
        "bootstrap-extra-files",
        "command-logger",
        "session-memory"
      ]
    }
  }
}

如需临时禁用某个 Hook，只需将其从 entries 数组中移除即可。完全禁用 Hook 系统则将 enabled 设为 false。

#验证 Hook 状态

启动一次新会话后，通过日志确认 Hook 是否正常触发：

# 查看最近的日志，确认 boot-md 等 Hook 是否执行
openclaw logs --follow
# 或查看审计日志中 command-logger 的记录
tail -20 ~/.openclaw/logs/config-audit.jsonl

#6.3 Cron 定时任务

OpenClaw 支持 Cron 定时任务，可在隔离 Session 中自动执行预设操作。Cron 任务非常适合需要周期性运行的场景，如每日归档、每周总结、定期巡检等。

#查看已配置的定时任务

定时任务配置位于 ~/.openclaw/cron/jobs.json，可直接查看：

# 查看当前已配置的所有定时任务
cat ~/.openclaw/cron/jobs.json | python3 -m json.tool

# 查看最近的任务执行记录
ls -lt ~/.openclaw/cron/runs/ | head -10

#配置示例

以下是一个包含每日归档和每周总结的典型 Cron 配置：

{
  "jobs": [
    {
      "name": "每日记忆归档",
      "schedule": "0 6 * * *",
      "timezone": "Asia/Shanghai",
      "action": "归纳前日 memory 日志，写入 MEMORY.md"
    },
    {
      "name": "每周工作总结",
      "schedule": "0 17 * * 5",
      "timezone": "Asia/Shanghai",
      "action": "归纳本周日志，生成周报"
    }
  ]
}

#Cron 表达式说明

Cron 表达式由 5 个字段组成，分别表示分钟、小时、日期、月份和星期：

┌───── 分钟 (0-59)
│ ┌───── 小时 (0-23)
│ │ ┌───── 日 (1-31)
│ │ │ ┌───── 月 (1-12)
│ │ │ │ ┌───── 星期 (0-7, 0 和 7 都是周日)
│ │ │ │ │
* * * * *

#常用 Cron 表达式速查

#任务隔离与执行记录

每个 Cron 任务在独立 Session 中运行，不影响主会话。执行结果以 JSONL 格式保存在 ~/.openclaw/cron/runs/ 目录下，文件名为任务的 UUID：

# 查看某次执行的详细日志
cat ~/.openclaw/cron/runs/<run-id>.jsonl | python3 -m json.tool

# 统计本月执行的任务数量
ls ~/.openclaw/cron/runs/*.jsonl | wc -l

#6.4 脚本与工具集成

OpenClaw Agent 可以调用系统命令、运行本地脚本、使用内置工具和通过 MCP 协议连接外部服务。这种开放式集成机制让 Agent 具备几乎无限的能力扩展空间。

#集成方式对比

#执行本地脚本

Agent 可以直接运行系统命令和各种语言的脚本。确保脚本位于可访问的路径下：

# Python 脚本
python3 scripts/process.py

# Bash 脚本（推荐先赋予执行权限）
chmod +x scripts/deploy.sh
bash scripts/deploy.sh

# Node.js 脚本
node scripts/transform.js

最佳实践：将 Agent 常用的脚本统一放在 ~/.openclaw/workspace/skills/<skill-name>/scripts/ 目录下，便于 Skill 打包和分发。

#web_fetch 工具

web_fetch 是 OpenClaw 内置的网页抓取工具，支持提取文本、Markdown 和 HTML 内容：

# 在 Agent 对话中使用（提取纯文本）
web_fetch(url="https://example.com", extractMode="text", maxChars=8000)

# 提取 Markdown 格式内容
web_fetch(url="https://docs.example.com/api", extractMode="markdown", maxChars=10000)

#McPorter MCP 工具

McPorter 是 OpenClaw 的 MCP（Model Context Protocol）网关，可连接多个外部工具服务器：

# 列出所有已注册的 MCP 工具
mcporter list

# 调用指定工具（格式：server.tool key=value）
mcporter call tavily.search query="OpenClaw tutorial"

# 查看 MCP 配置
cat ~/.openclaw/workspace/config/mcporter.json | python3 -m json.tool

#6.5 实战：搭建自动化巡检

结合 Skills + Cron + 脚本，搭建一套完整的自动化巡检流程。以下示例展示如何创建巡检脚本、注册定时任务，并通过消息通道发送报告。

#场景：每日项目健康检查

创建巡检脚本 ~/.openclaw/workspace/scripts/daily-check.sh：

#!/bin/bash
# scripts/daily-check.sh — 每日项目健康检查脚本

set -e
echo "=== 项目健康检查 ==="
echo "时间: $(date '+%Y-%m-%d %H:%M:%S')"
echo ""

# 1. 检查 Gateway 状态
echo "--- Gateway 状态 ---"
openclaw daemon status

# 2. 检查 Skills 状态
echo ""
echo "--- 已安装 Skills ---"
for dir in ~/.openclaw/workspace/skills/*/; do
  if [ -f "$dir/SKILL.md" ]; then
    echo "  ✅ $(basename "$dir")"
  else
    echo "  ⚠️  $(basename "$dir") (缺少 SKILL.md)"
  fi
done

# 3. 检查磁盘空间
echo ""
echo "--- 磁盘空间 ---"
df -h ~/.openclaw/ | tail -1

# 4. 检查最近日志
echo ""
echo "--- 最近 Memory 日志 ---"
ls -lt ~/.openclaw/workspace/memory/*.md 2>/dev/null | head -5

# 5. 检查 Cron 任务执行情况
echo ""
echo "--- 最近 Cron 执行 ---"
ls -lt ~/.openclaw/cron/runs/*.jsonl 2>/dev/null | head -3

echo ""
echo "=== 检查完成 ==="

#赋予执行权限并测试

chmod +x ~/.openclaw/workspace/scripts/daily-check.sh
bash ~/.openclaw/workspace/scripts/daily-check.sh

#配置定时执行

将上述脚本注册为 Cron 任务，在 ~/.openclaw/cron/jobs.json 中添加：

{
  "name": "每日健康巡检",
  "schedule": "0 6 * * *",
  "timezone": "Asia/Shanghai",
  "action": "执行 ~/.openclaw/workspace/scripts/daily-check.sh 并将报告通过飞书发送给管理员"
}

#配合消息通道发送报告

巡检完成后，可通过 openclaw message send 将报告推送到飞书等渠道：

# 将巡检结果发送到飞书群
REPORT=$(bash ~/.openclaw/workspace/scripts/daily-check.sh)
openclaw message send \
  --channel feishu \
  --target "<chat_id>" \
  --message "📊 每日巡检报告

$REPORT"

#6.6 Shell 补全配置

OpenClaw CLI 支持主流 Shell 的命令补全，提升日常操作效率：

# Bash 补全（添加到 ~/.bashrc）
source ~/.openclaw/completions/openclaw.bash

# Zsh 补全（添加到 ~/.zshrc）
source ~/.openclaw/completions/openclaw.zsh

# Fish 补全
source ~/.openclaw/completions/openclaw.fish

配置完成后重新加载 Shell，即可使用 Tab 键自动补全 openclaw 命令和子命令。

#进阶：脚本架构设计

设计健壮的自动化脚本体系需要理解以下架构要点：

• 命令编排模式：复杂自动化任务建议拆分为多个独立脚本，通过 openclaw run 串联执行，每个脚本负责单一职责，便于调试和复用。
• 错误处理链：在脚本中使用 set -euo pipefail 确保错误及时中断，结合 openclaw hooks 配置失败回调通知，实现自动化流程的可观测性。
• 变量注入机制：openclaw run 支持通过 --env KEY=VALUE 注入运行时变量，脚本内通过环境变量读取，避免硬编码敏感信息。
• 幂等性设计：自动化脚本应保证多次执行结果一致，使用状态检查（如 openclaw status）在执行前判断是否需要操作。
• Cron 集成：定时任务配置在 cron/jobs.json 中，支持 cron 表达式，通过 openclaw cron list 查看和管理所有定时脚本。

#注意事项与常见错误

编写自动化脚本时常见的错误和需要注意的问题：

⚠️ 注意：Cron 任务的执行环境与交互式 Shell 不同，PATH 和环境变量可能缺失，建议在脚本头部显式设置所需环境变量。

#进阶：脚本架构与自动化原理

设计复杂自动化脚本时，理解 OpenClaw 的命令执行架构至关重要：

#注意事项与常见错误

编写自动化脚本时的常见错误：

#进阶：脚本架构与自动化原理

设计复杂自动化脚本时的架构选型：

#注意事项与常见错误

编写自动化脚本的常见错误：

#实操练习

以下练习帮助你巩固本章所学的自动化技能，请按步骤依次完成。

#练习 1：CLI 基础操作

1. 运行 openclaw doctor 检查当前环境，查看输出中是否有 ❌ 标记的异常项
2. 使用 openclaw config get gateway.port 查看当前端口配置
3. 运行 openclaw session list 查看现有会话列表
4. 执行 openclaw logs --follow，观察实时日志输出（按 Ctrl+C 退出）

# 按顺序执行以下命令
openclaw doctor
openclaw config get gateway.port
openclaw session list
openclaw logs --follow

预期结果：doctor 输出各项检查结果；config get 返回端口号（默认 18789）；session list 显示活跃会话；logs 实时滚动输出。

#练习 2：配置并验证 Hook

1. 打开配置文件 ~/.openclaw/openclaw.json，确认 hooks.internal.enabled 值为 true
2. 检查 entries 数组中包含 boot-md 和 command-logger
3. 创建一个新会话 openclaw session new，触发 boot-md Hook
4. 查看审计日志，确认 command-logger 是否记录了命令

# 查看 Hook 配置
cat ~/.openclaw/openclaw.json | python3 -c "
import json, sys
cfg = json.load(sys.stdin)
hooks = cfg.get('hooks', {}).get('internal', {})
print('enabled:', hooks.get('enabled'))
print('entries:', hooks.get('entries'))
"

# 创建新会话触发 Hook
openclaw session new

# 查看审计日志最后几行
tail -5 ~/.openclaw/logs/config-audit.jsonl

预期结果：配置显示 Hook 已启用；新会话创建后日志中出现 boot-md 执行记录。

#练习 3：创建自定义 Cron 任务

1. 编辑 ~/.openclaw/cron/jobs.json，添加一个测试任务（5 分钟后执行）
2. 等待任务触发，检查 ~/.openclaw/cron/runs/ 下是否生成新的执行记录
3. 查看执行记录内容，确认任务成功运行

# 查看当前 Cron 配置
cat ~/.openclaw/cron/jobs.json | python3 -m json.tool

# 查看已有的执行记录
ls -lt ~/.openclaw/cron/runs/ | head -5

# 查看最新一条执行记录的内容
LATEST=$(ls -t ~/.openclaw/cron/runs/*.jsonl | head -1)
cat "$LATEST"

预期结果：能看到现有的定时任务配置和历史执行记录；理解 JSONL 格式的任务日志结构。

#练习 4（挑战）：编写完整巡检脚本

1. 参考 6.5 节示例，创建 ~/.openclaw/workspace/scripts/my-check.sh
2. 在脚本中至少包含 3 项检查（Gateway 状态、Skills 列表、磁盘空间）
3. 手动运行脚本并验证输出
4. （可选）将脚本注册为 Cron 任务

# 创建脚本目录
mkdir -p ~/.openclaw/workspace/scripts

# 创建脚本文件
cat > ~/.openclaw/workspace/scripts/my-check.sh << 'EOF'
#!/bin/bash
echo "=== 我的巡检脚本 ==="
echo "时间: $(date)"
openclaw daemon status
echo "已安装 Skills:"
ls ~/.openclaw/workspace/skills/
echo "磁盘使用:"
du -sh ~/.openclaw/
EOF

# 赋予执行权限并运行
chmod +x ~/.openclaw/workspace/scripts/my-check.sh
bash ~/.openclaw/workspace/scripts/my-check.sh

#常见问题 (FAQ)

#Q1: Cron 任务配置后不执行，怎么排查？

A: 按以下步骤排查：

1. 确认 Gateway 正在运行：openclaw daemon status
2. 检查 jobs.json 格式是否正确：python3 -m json.tool ~/.openclaw/cron/jobs.json
3. 确认 schedule 字段的 Cron 表达式格式正确
4. 查看 Gateway 日志中是否有错误信息：openclaw logs --follow
5. 检查 timezone 是否与系统时区一致

#Q2: Hook 配置正确但没有触发，如何解决？

A: 常见原因和解决方法：

• enabled 为 false：修改 ~/.openclaw/openclaw.json 将 hooks.internal.enabled 设为 true
• Hook 名称拼写错误：核对 entries 数组中的名称，必须与内置 Hook 名称完全一致
• Gateway 未重启：修改配置后运行 openclaw gateway stop && openclaw gateway start
• 查看错误日志：tail -50 ~/.openclaw/logs/config-audit.jsonl 检查是否有报错

#Q3: 脚本执行时报 "Permission denied" 错误？

A: 这是因为脚本缺少执行权限。有两种解决方式：

# 方式 1：直接用解释器运行（无需执行权限）
bash scripts/deploy.sh
python3 scripts/process.py

# 方式 2：添加执行权限后直接运行
chmod +x scripts/deploy.sh
./scripts/deploy.sh

#Q4: 如何查看某个 Cron 任务的历史执行记录？

A: Cron 执行记录保存在 ~/.openclaw/cron/runs/ 目录下，每次执行生成一个 JSONL 文件：

# 列出所有执行记录（按时间倒序）
ls -lt ~/.openclaw/cron/runs/

# 查看最新执行记录
cat $(ls -t ~/.openclaw/cron/runs/*.jsonl | head -1) | python3 -m json.tool

#Q5: web_fetch 抓取网页内容为空或报错？

A: 可能原因包括：目标网站拒绝非浏览器访问、网络连接问题、或 URL 格式错误。建议先用 curl 测试网络连通性：

# 测试网页是否可达
curl -sI https://example.com | head -5

#参考链接

#本章小结

本章系统介绍了 OpenClaw 的自动化命令与脚本集成能力：

• OpenClaw CLI 工具集：掌握了服务管理、配置读写、会话操作、诊断排错等核心命令
• Hook 钩子系统：理解了事件驱动机制，学会配置和验证 boot-md、command-logger 等内置 Hook
• Cron 定时任务：学会编写 Cron 表达式、配置周期性任务、查看执行记录
• 脚本与工具集成：掌握了本地脚本、web_fetch、McPorter MCP 等多种集成方式
• 实战巡检流程：完成了从脚本编写、定时调度到消息推送的完整自动化链路
• Shell 补全：配置了命令行自动补全，提升日常操作效率
• 遇到问题时，善用 openclaw doctor 进行一键诊断，并查阅 FAQ 获取解决方案

下一章：飞书集成与消息自动化