OpenClaw 生产环境配置与 Cron 任务自动化运维实战

前言

本文档面向已将 OpenClaw 纳入生产运维体系的工程师，从运维视角系统阐述配置管理、定时任务、Gateway 运维、多渠道接入等生产环境关键议题。所有结论均基于 OpenClaw 官方文档与技术文档领域的实操经验，可直接用于生产环境部署。

本文默认读者已具备 OpenClaw 基础操作能力，了解 SOUL.md、USER.md、IDENTITY.md 等基础配置文件的作用，并熟悉 workspace 概念。

---

第一章：OpenClaw 生产环境配置原理

1.1 配置文件层级与加载机制

OpenClaw 的配置体系分为三个层级，由高到低依次覆盖：

第一层：用户配置文件

主配置文件位于 ~/.openclaw/openclaw.json，采用 JSON5 格式。它是所有配置项的入口，修改后通过 openclaw gateway restart 或配置热重载使其生效。配置文件路径的优先级为：--config CLI 参数 > OPENCLAW_CONFIG 环境变量 > ~/.openclaw/openclaw.json。

第二层：workspace 内配置

workspace 目录下的配置文件定义了 Agent 的行为规范。每次新 session 启动时，Agent 会自动加载这些文件：

• SOUL.md：Agent 性格定义，描述“你是一个什么样的助手”
• USER.md：用户信息，描述“你在帮谁”
• AGENTS.md：工作手册，描述“每次上班先做什么、任务怎么做、安全边界在哪里”
• IDENTITY.md：身份标识，包含名称、头像、emoji 等视觉身份信息

第三层：运行时配置覆盖

部分配置项可在运行时通过命令或 API 临时覆盖，如 /config 命令可查看并修改当前会话的部分参数。但运行时修改仅对当前会话有效，重启后即失效。

配置加载顺序验证方法：

openclaw gateway --verbose 2>&1 | grep -i "config\|workspace\|load"

该命令会输出配置加载的完整过程，你可依此观察到各层级文件的加载时机。

1.2 JSON5 配置格式规范

OpenClaw 采用 JSON5 作为配置文件格式，意味着在标准 JSON 基础上，它支持注释和尾随逗号。这一设计显著提升了配置文件的可维护性。

JSON5 特性示例：

{
  // 核心配置区
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "provider/claude-sonnet-4",
        fallbacks: ["provider/claude-haiku-4"],
      },
      // compaction 策略
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
        },
      },
    },
  },

  // Gateway 配置
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: { token: "your-secret-token" },
    reload: { mode: "hybrid" },
  },

  // 渠道配置
  channels: {
    discord: {
      token: "your-bot-token",
      allowFrom: ["server:123456789"],
      ackReaction: "👀",
    },
  },
}

配置路径规范：

OpenClaw 采用点号分隔的路径表达嵌套配置，如 agents.defaults.compaction.reserveTokensFloor。所有配置项均可通过完整路径访问。配置结构采用深合并策略，后续配置项会递归合并到已有配置中。

严格验证机制：

OpenClaw 执行严格的 Schema 验证。未知配置键或类型错误将直接导致 Gateway 启动失败。这一设计避免了因配置拼写错误引发的问题在后台隐式传播。验证失败时，系统会输出详细的错误信息，精准指出哪个配置键出了问题。

1.3 配置验证与诊断

OpenClaw 内置的 openclaw doctor 诊断工具，用于检查配置完整性和环境状态。你应在生产部署前和故障排查时执行它。

基础诊断命令：

openclaw doctor

输出包含以下检查项：

• 配置文件语法检查（JSON5 解析）
• 必填配置项检查
• API Key 格式验证
• workspace 目录权限检查
• 渠道连接性测试

深度诊断模式：

openclaw doctor --verbose

该模式会输出详细的检查过程，包括每个配置项的验证结果。对于配置项繁多的大型配置文件，深度模式能帮你精确定位问题。

单项配置验证：

在修改特定配置项后，可用以下命令验证配置语法：

openclaw config validate --key agents.defaults.model

健康状态检查：

openclaw gateway health
openclaw gateway status
openclaw gateway status --deep

health 命令执行存活性检查：建立 WebSocket 连接，发送 req:connect，并期望收到包含 hello-ok 的 res 响应。status 命令检查 supervisor 运行时状态和 RPC 可达性。--deep 参数会增加系统级扫描，包括磁盘使用率、内存占用、进程状态等。

1.4 配置热重载与安全重启

热重载机制：

OpenClaw Gateway 支持配置热重载，默认模式为 hybrid。在该模式下，Agent 配置变更会自动生效，而 Gateway 端口变更则需要手动重启。热重载监控的文件路径为 ~/.openclaw/openclaw.json。

热重载配置项：

{
  gateway: {
    reload: {
      mode: "hybrid", // hybrid | hot | restart | off
    },
  },
}

各模式行为如下：

• hybrid：Agent 配置自动热重载，Gateway 端口等需要重启
• hot：所有配置自动热重载，无需重启
• restart：配置文件变更后自动重启 Gateway
• off：禁用热重载，所有变更需手动重启

安全重启流程：

生产环境重启 Gateway 应遵循以下流程，以避免消息丢失：

# 1. 检查当前运行状态
openclaw gateway status

# 2. 检查是否有进行中的任务
openclaw cron list

# 3. 等待进行中的任务完成（可选）
# 如果有必须完成的任务，使用以下命令等待
sleep 30

# 4. 执行重启
openclaw gateway restart

# 5. 验证重启结果
openclaw gateway health
openclaw gateway status

重启前的预检清单：

• 确认 openclaw gateway status 显示所有渠道在线
• 确认 cron 任务无正在执行的任务
• 确认 ~/.openclaw/openclaw.json 语法正确
• 确认所有必填配置项已填写

进程保活配置：

生产环境应配置进程管理器，确保 Gateway 异常退出后自动恢复。推荐使用 systemd：

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/usr/local/bin/openclaw gateway start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

将该文件保存为 /etc/systemd/system/openclaw-gateway.service，然后执行：

sudo systemctl daemon-reload
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

---

第二章：Gateway 运维体系

2.1 Gateway 架构与端口管理

OpenClaw Gateway 是 OpenClaw 的核心组件，负责维持与各消息渠道的长连接，处理消息路由和 Agent 生命周期管理。Gateway 采用常驻进程设计，退出时返回非零状态码以便 supervisor 自动拉起。

端口优先级机制：

Gateway 监听端口的确定遵循以下优先级：

1. --port CLI 参数（最高优先级）
2. OPENCLAW_GATEWAY_PORT 环境变量
3. gateway.port 配置项
4. 默认端口 18789

默认配置下，WebSocket 控制平面绑定到 127.0.0.1:18789，同一端口同时提供 HTTP 控制接口、hooks 和 A2UI 管理界面。Canvas 文件服务器默认占用端口 18793。开发实例使用基础端口 19001，衍生端口依次为 19003（+2）和 19005（+4）。

端口配置示例：

{
  gateway: {
    port: 18789,
    bind: "loopback", // loopback | lan | tailnet
  },
  canvasHost: {
    port: 18793,
  },
}

bind 参数控制监听地址：

• loopback：仅监听 127.0.0.1，仅本地可访问
• lan：监听所有网络接口，局域网可访问
• tailnet：配合 Tailscale 使用

生产环境推荐 loopback，通过 SSH 隧道或 VPN 访问 Gateway 控制接口。如需直接从局域网访问，应配合 gateway.auth 做好认证和 trustedProxies 配置。

端口冲突检测：

启动前检测端口可用性：

ss -tlnp | grep 18789
# 或
netstat -tlnp | grep 18789

如果端口已被占用，会返回占用进程的 PID 和名称。

2.2 认证与访问控制

Gateway 默认启用认证，客户端连接时必须提供有效凭证。认证方式通过 gateway.auth.mode 配置：

{
  gateway: {
    auth: {
      mode: "token", // token | password
      token: "your-secret-token",
      password: "your-password",
      allowTailscale: false,
    },
  },
}

Token 认证：

客户端连接时需在 connect 参数中包含 token：

{
  connect: {
    params: {
      auth: {
        token: "your-secret-token",
      },
    },
  },
}

密码认证：

{
  connect: {
    params: {
      auth: {
        password: "your-password",
      },
    },
  },
}

多 Gateway 隔离：

安全设计假设每个 Gateway 独占一台宿主机。如果需要部署多个 Gateway 实例，必须确保：

• 端口不冲突（每个实例使用不同端口）
• 状态目录隔离（通过 --data-dir 参数）
• 配置文件独立

# 实例 1
openclaw gateway start --port 18789 --data-dir /var/lib/openclaw-instance1

# 实例 2
openclaw gateway start --port 18790 --data-dir /var/lib/openclaw-instance2

Tailscale 集成：

如果 gateway.auth.allowTailscale 设为 true，通过 Tailscale 身份验证的用户可免认证登录。这在 Tailscale 网络内提供了零摩擦的访问体验。

2.3 日志体系与调试

日志输出位置：

Gateway 日志默认输出到 stdout，生产环境应通过进程管理器重定向到日志文件。在 systemd 环境下，日志由 journald 管理，可通过 journalctl -u openclaw-gateway 查看。

默认日志文件路径为 /tmp/openclaw/openclaw-YYYY-MM-DD.log，可通过 logging.file 配置项修改。

日志级别配置：

{
  logging: {
    level: "info",      // 全局日志级别
    file: "/var/log/openclaw/gateway.log",
    consoleLevel: "info",  // 控制台日志级别
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: [],       // 自定义脱敏正则
  },
}

日志级别从低到高：debug、info、warn、error。生产环境通常使用 info，故障排查时临时切换到 debug。

调试模式启动：

openclaw gateway start --verbose

--verbose 参数会将 debug 日志同时输出到控制台，便于实时观察 Gateway 行为。该参数应仅用于故障排查，不建议长期使用。

日志查看命令：

# 实时跟踪日志
openclaw logs --follow

# 查看最近 100 行
openclaw logs --lines 100

# 过滤特定关键词
openclaw logs --grep "error\|warn" --lines 50

# 按时间范围查看
openclaw logs --since "2026-03-20 10:00:00" --until "2026-03-20 12:00:00"

敏感信息脱敏：

logging.redactSensitive 设为 tools 时，工具调用日志中的敏感信息（API Key、Token 等）会被自动脱敏。logging.redactPatterns 支持自定义脱敏规则：

{
  logging: {
    redactPatterns: [
      "sk-[a-zA-Z0-9]{20,}", // OpenAI API Key 格式
      "Bearer [a-zA-Z0-9._-]+", // Bearer Token 格式
    ],
  },
}

2.4 健康检查与监控

健康检查端点：

Gateway 提供两种健康检查：存活性（liveness）和就绪性（readiness）。

存活性检查确认 Gateway 进程正常运行：

openclaw gateway health

该命令通过 WebSocket 发送存活性探测，期望返回 hello-ok 响应。如果 Gateway 无响应或返回错误，说明进程可能处于异常状态。

就绪性检查确认 Gateway 已准备好处理请求：

openclaw gateway status

该命令调用健康检查端点，期望返回包含 ok: true 和渠道状态信息的响应。如果就绪性检查失败，即使进程在运行，Gateway 也不应接收新请求。

深度状态检查：

openclaw gateway status --deep

--deep 参数增加系统资源检查：

• 磁盘使用率（是否低于 90%）
• 内存使用情况
• Gateway 进程 CPU 占用
• 各渠道连接状态

Prometheus 监控集成：

通过配置 hooks 可将指标暴露给 Prometheus：

{
  hooks: {
    enabled: true,
    path: "/hooks",
    mappings: [{
      match: { path: "metrics" },
      action: "prometheus",
    }],
  },
}

或者直接通过 HTTP 控制接口获取状态：

curl -s http://127.0.0.1:18789/status | jq .

告警阈值建议：

• 磁盘使用率 > 85%：告警
• 内存使用率 > 90%：告警
• Gateway 进程 CPU > 80% 持续 5 分钟：告警
• 任意渠道离线：告警
• 健康检查连续失败 3 次：告警

2.5 服务管理与进程保活

进程保活架构：

生产环境必须配置进程管理器，确保 Gateway 异常退出后自动拉起。推荐的架构是 systemd 作为 primary supervisor，Gateway 作为被管理服务。

systemd 服务配置：

[Unit]
Description=OpenClaw Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
ExecStart=/usr/local/bin/openclaw gateway start --verbose
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
Environment=OPENCLAW_GATEWAY_PORT=18789

# 安全加固
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/openclaw /var/log/openclaw
PrivateTmp=true

[Install]
WantedBy=multi-user.target

该配置实现了：

• 自动重启：Gateway 异常退出后 10 秒内自动拉起
• 最小权限：使用专用用户运行，不使用 root
• 文件系统隔离：只允许写入指定目录
• 临时文件隔离：使用私有 /tmp

日志轮转配置：

通过 logrotate 管理日志文件大小：

/var/log/openclaw/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 openclaw openclaw
    sharedscripts
    postrotate
        systemctl reload openclaw-gateway > /dev/null 2>&1 || true
    endscript
}

启动顺序：

如果 Gateway 依赖其他服务（如数据库、Redis），应在 systemd unit 中通过 After 和 Wants 声明依赖关系：

[Unit]
Description=OpenClaw Gateway
After=network.target redis.service
Wants=redis.service

手动服务控制：

# 启动
sudo systemctl start openclaw-gateway

# 停止
sudo systemctl stop openclaw-gateway

# 重启
sudo systemctl restart openclaw-gateway

# 查看状态
sudo systemctl status openclaw-gateway

# 查看日志
sudo journalctl -u openclaw-gateway -f

平滑重启：

生产环境建议使用平滑重启，避免服务中断：

# 向 Gateway 发送重启信号（触发热重载）
openclaw gateway reload

# 或通过 API
curl -X POST http://127.0.0.1:18789/api/reload \
  -H "Authorization: Bearer your-token"

---

第三章：定时任务与自动化运维

3.1 三种调度类型对比

OpenClaw Cron 调度系统支持三种调度类型，适用于不同的时间触发场景。灵活运用它们是实现运维/DevOps/SRE自动化的关键。

at 类型：一次性定时任务

在指定时间点执行一次后自动删除。适用于会议提醒、生日提醒、一次性通知等场景。

{
  "name": "喝水提醒",
  "schedule": { "kind": "at", "at": "2026-03-20T16:00:00+08:00" },
  "payload": { "kind": "systemEvent", "text": "提醒：该喝水了！" },
  "sessionTarget": "main",
  "deleteAfterRun": true,
}

时间格式为 ISO 8601，建议始终包含时区信息（+08:00 表示北京时间）。如果不带时区，OpenClaw 默认使用 UTC 时间。

every 类型：固定间隔循环任务

按固定时间间隔重复执行，适用于心跳检测、状态轮询等场景。

{
  "name": "服务巡检",
  "schedule": { "kind": "every", "everyMs": 3600000 },
  "payload": { "kind": "agentTurn", "message": "检查服务状态" },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce" },
}

常用时间换算：

间隔	everyMs 值
5 分钟	300000
15 分钟	900000
30 分钟	1800000
1 小时	3600000
6 小时	21600000
24 小时	86400000

cron 类型：Cron 表达式调度

最灵活的调度方式，支持标准 5 字段 cron 表达式。适用于周期性报告、定时任务等复杂调度场景。

{
  "name": "每日早报",
  "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" },
  "payload": { "kind": "agentTurn", "message": "生成今日简报" },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce" },
}

字段顺序为：分 时 日 月 周

常用 cron 表达式示例：

表达式	含义
0 9 * * *	每天 9:00
0 9 * * 1	每周一 9:00
0 9,18 * * *	每天 9:00 和 18:00
*/30 * * * *	每 30 分钟
0 0 1 * *	每月 1 日 0:00
0 9 * * 1-5	工作日 9:00

时区配置的重要性：

tz 字段必须设置，否则默认使用 UTC 时间。一个常见的坑：你配置了 0 9 * * *（期望北京时间 9:00），但没有设置 tz，实际会在 UTC 1:00（北京时间 9:00）执行。这对于国内服务器通常是正确的，但对于海外服务器或容器时区配置不一致时，会导致难以察觉的调度偏差。

3.2 执行模式与会话管理

Cron 任务支持两种执行模式，决定了任务在什么会话环境中运行。

systemEvent 模式：主会话注入

将事件文本注入到主会话，在下次 heartbeat 时处理。适用于提醒、通知类场景。

{
  "payload": {
    "kind": "systemEvent",
    "text": "提醒：10 分钟后有会议"
  },
  "sessionTarget": "main",
  "wakeMode": "now",
}

sessionTarget: "main" 只能搭配 systemEvent 类型，不可混用。该模式复用主会话的上下文，因此可以访问 MEMORY.md 等主会话专属文件。

agentTurn 模式：独立会话执行

启动一个独立的 cron session 执行任务。适用于需要执行操作、生成报告等场景。

{
  "payload": {
    "kind": "agentTurn",
    "message": "生成今日项目报告",
    "model": "sonnet"
  },
  "sessionTarget": "isolated",
  "wakeMode": "next-heartbeat",
}

独立会话的 session key 格式为 cron:<jobId>。可以使用不同模型执行任务（model 参数），这为成本优化提供了空间。

会话目标组合限制：

sessionTarget	payload.kind	wakeMode	有效组合
main	systemEvent	now / next-heartbeat	有效
isolated	agentTurn	now / next-heartbeat	有效
main	agentTurn	-	无效组合
isolated	systemEvent	-	无效组合

如果配置了无效组合，Gateway 会在任务调度时报告错误。

wakeMode 参数：

• now：立即触发执行
• next-heartbeat：等待下一次 heartbeat 时执行

next-heartbeat 模式可以批量处理多个定时事件，减少模型调用次数。now 模式则立即执行，适用于有时间敏感性的任务。

3.3 任务状态存储与历史追溯

任务列表查看：

openclaw cron list

该命令列出所有已注册的定时任务，包括任务 ID、名称、调度表达式、下次执行时间、启用状态。

执行历史查看：

openclaw cron runs --id <任务ID>

该命令显示任务的执行历史，包括每次执行的开始时间、结束时间、执行状态（成功/失败）、执行时长。如果任务执行失败，会显示错误信息。

执行状态说明：

• pending：任务已调度，等待执行
• running：任务正在执行
• completed：任务执行成功
• failed：任务执行失败
• cancelled：任务被取消

任务启用/禁用：

禁用任务而不是删除任务是推荐的运维实践。禁用后的任务保留执行历史，可以随时重新启用。

openclaw cron edit <任务ID> --disable
openclaw cron edit <任务ID> --enable

手动触发执行：

用于测试任务配置或立即执行紧急任务：

openclaw cron run --id <任务ID> --force

--force 参数强制执行，忽略调度时间和禁用状态。

清理历史记录：

执行历史会占用存储空间，定期清理是必要的：

openclaw cron runs --id <任务ID> --clear

3.4 典型运维场景配置示例

场景一：每日科技新闻摘要

{
  "name": "每日早报",
  "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "搜索今天的科技和 AI 领域新闻热点，整理成 5 条简报。每条包含：标题、一句话摘要、来源链接。",
    "model": "haiku"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "telegram",
    "to": "user:123456789"
  }
}

该配置使用 Haiku 模型生成简报以控制成本，结果通过 Telegram 投送到指定用户。

场景二：服务器健康状态巡检

{
  "name": "服务巡检",
  "schedule": { "kind": "every", "everyMs": 3600000 },
  "payload": {
    "kind": "agentTurn",
    "message": "用 curl 检查以下服务是否在线：\n1. http://localhost:8080\n2. http://localhost:3000\n3. http://localhost:5432\n\n如果全部正常，不要通知。如果有服务离线，说明哪个服务、返回的错误码、可能的处理建议。",
    "model": "haiku"
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "announce" }
}

该配置实现了“静默正常”模式——服务正常时不会骚扰用户，只有异常时才发送通知。

场景三：每周项目周报生成

{
  "name": "项目周报",
  "schedule": { "kind": "cron", "expr": "0 10 * * 1", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "读取 memory/ 目录下最近 7 天的日志文件，整理成一份周报。周报包含：\n1. 本周完成的事项（按项目分类）\n2. 进行中的项目及进展\n3. 遇到的问题及解决方案\n4. 下周计划\n格式简洁，使用 bullet points。",
    "model": "sonnet"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "discord",
    "to": "channel:987654321"
  }
}

场景四：一次性提醒

通过自然语言告知 AI 创建，AI 会自动生成对应的 Cron 配置：

"帮我设置一个 20 分钟后的提醒：开会"

OpenClaw 会自动解析并创建类似以下配置：

{
  "name": "开会提醒",
  "schedule": {
    "kind": "at",
    "at": "2026-03-20T16:20:00+08:00"
  },
  "payload": {
    "kind": "systemEvent",
    "text": "开会时间到了"
  },
  "sessionTarget": "main",
  "deleteAfterRun": true
}

3.5 多渠道投递配置

投递模式：

Cron 任务的 delivery.mode 参数控制执行结果的投递方式：

模式	行为
announce	将执行摘要投送到指定渠道
none	仅内部执行，不发送通知

渠道投递配置：

{
  "delivery": {
    "mode": "announce",
    "channel": "discord",
    "to": "channel:987654321",
    "bestEffort": true
  }
}

to 参数格式：

• channel:<ID>：投送到指定频道
• user:<ID>：投送给指定用户
• group:<ID>：投送到指定群组

bestEffort 参数设为 true 时，投递失败不会重试，适合对可靠性要求不高的通知场景。

多渠道同时投递：

需要同时投送到多个渠道时，可创建多个 Cron 任务，或在任务消息中指定多个渠道：

{
  "name": "每日双渠道通知",
  "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "生成今日摘要，结果同时投送到 Discord 和 Telegram",
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "discord",
    "to": "channel:111111111"
  }
}

如果需要同时投送多个渠道，建议在消息中明确说明，Agent 会在执行后自动处理跨渠道投递。

---

第四章：记忆系统与上下文管理

4.1 Compaction 机制原理

OpenClaw 的 Compaction（压缩）机制是解决 AI 长期对话失忆问题的核心。当对话长度接近模型的上下文窗口限制时，OpenClaw 会自动将旧的对话内容压缩成摘要，释放 token 空间供后续对话使用。

触发条件：

Compaction 在以下条件满足时触发：

• 对话历史总 token 数接近模型上下文窗口上限
• 剩余 token 空间低于 reserveTokensFloor 阈值

压缩过程中，已压缩的对话会以摘要形式保留，未压缩的近期对话保持原样。压缩完成后，新对话便可继续无缝进行。

压缩策略配置：

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        strategy: "default",
      },
    },
  },
}

reserveTokensFloor 表示压缩后至少保留的最近对话 token 数。设为 20000 时，压缩后最近 20K token 的对话保持原样，更早的对话被压缩为摘要。

手动触发压缩：

用户可以通过命令手动触发压缩，并指定希望保留的重点内容：

/compact 重点保留技术决策和代码架构相关讨论

该命令会立即对当前对话进行压缩，指令中指定的内容将被优先保留。

4.2 memoryFlush 配置与阈值设计

memoryFlush 机制：

memoryFlush 是 Compaction 的增强功能，在触发压缩之前，先让 AI 将重要信息写入文件。开启后，AI 不会因为压缩而丢失关键记忆。

配置参数：

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
        },
      },
    },
  },
}

参数	含义	推荐值
enabled	是否开启压缩前自动保存	true
softThresholdTokens	距离压缩多少 token 时触发保存	4000

softThresholdTokens: 4000 意味着当对话剩余空间降至 4000 token 时，触发 memoryFlush。AI 会将重要信息写入文件，这些信息在压缩后仍可通过读取文件恢复。

阈值设计原则：

• softThresholdTokens 越小，触发越频繁，AI 有更多 token 用于正常对话
• softThresholdTokens 越大，触发越早，有更多时间准备保存内容
• 推荐值 4000 考虑了保存操作本身需要消耗的 token

验证 memoryFlush 生效：

开启 verbose 模式后，你可以在对话中看到 Auto-compaction complete 提示：

openclaw gateway restart --verbose

然后在对话中使用 /verbose 命令开启 verbose 模式。memoryFlush 执行时不会有额外提示（静默执行），只有在 compaction 完成后才会在 verbose 模式下看到提示。

4.3 记忆分层结构设计

分层架构概述：

OpenClaw 的记忆系统采用分层设计，不同层级的文件承担不同的记忆职能：

层级	文件	用途	更新频率
索引层	MEMORY.md	核心信息、能力概览、记忆索引	索引变化时
项目层	memory/projects.md	各项目当前状态与待办	项目有进展时
基础设施层	memory/infra.md	服务器、API、部署等配置速查	配置变更时
教训层	memory/lessons.md	踩过的坑，按严重程度分级	踩坑后
日志层	memory/YYYY-MM-DD.md	每日原始记录	每日或多日

索引层设计：

MEMORY.md 是记忆系统的入口，应保持精简（建议不超过 40 行）。内容应包含：

• 用户核心信息和偏好
• Agent 能力概览
• 记忆文件索引（指向其他记忆文件）
• 当前项目的关键上下文

示例结构：

# 核心记忆

## 用户信息
- 姓名：
- 时区：Asia/Shanghai
- 主要语言：中文

## 项目索引
- 项目A：memory/projects.md#project-a
- 项目B：memory/projects.md#project-b

## 最近重要上下文
- 2026-03：完成了系统重构，详见 memory/2026-03.md
- 当前主要任务：优化 Gateway 性能

## 教训索引
- 部署相关：memory/lessons.md#deploy
- 配置相关：memory/lessons.md#config

日志层设计：

日志文件命名格式为 memory/YYYY-MM-DD.md，按日期归档。日志应采用结构化格式，便于后续检索。

日志格式规范：

### [PROJECT:项目名] 标题

- **结论**: 一句话核心结论
- **文件变更**: 涉及的文件路径
- **教训**: 踩坑点和解决方案（如有）
- **标签**: #tag1 #tag2

好日志 vs 坏日志对比：

坏日志示例（流水账，信息密度低）：

### 部署
今天部署了项目。先试了直接跑，报错了。然后查了半天，发现是端口被占了。最后用 nginx 反代解决了问题。

好日志示例（结构化，高信息密度）：

### [PROJECT:MyApp] nginx 反代部署成功

- **结论**: 通过 nginx 反代部署成功，监听 80 端口
- **文件变更**: /etc/nginx/sites-available/myapp
- **教训**: 直接暴露端口不可行，必须走 nginx 反代
- **标签**: #myapp #deploy #nginx

好日志的判断标准：只看结论能否快速理解发生了什么事，不需要阅读正文。

4.4 向量检索与 Embedding 配置

memorySearch 机制：

OpenClaw 的 memorySearch 功能基于向量语义检索。当用户询问历史相关问题时，Agent 会调用 memorySearch 在记忆文件中进行语义搜索，返回最相关的内容。

SiliconFlow bge-m3 配置：

国内用户推荐使用 SiliconFlow 提供的免费 bge-m3 向量模型：

{
  memorySearch: {
    enabled: true,
    provider: "openai",
    remote: {
      baseUrl: "https://api.siliconflow.cn/v1",
      apiKey: "your-siliconflow-api-key",
    },
    model: "BAAI/bge-m3",
  },
}

bge-m3 模型优势：

• 完全免费，适合个人和小型团队
• 中英文双语支持优秀
• 向量维度 1024，精度和性能平衡良好
• 在中文语义理解任务上表现优异

获取 SiliconFlow API Key：

1. 访问 siliconflow.cn
2. 注册账号并完成认证
3. 进入控制台 → API Keys → 创建新 Key
4. 复制 Key 并配置到 openclaw.json

向量检索优化策略：

结构化日志的检索命中率显著高于非结构化文本。原因在于结构化日志的每个字段都有明确的语义标签，向量模型能够更准确地理解检索意图。

提高检索命中率的实践：

1. 标签规范化：为每个日志定义统一的标签体系，如 #deploy、#config、#bug
2. 关键词前置：在日志标题中包含核心关键词
3. 结论独立可读：结论字段应能独立表达完整语义，不依赖正文
4. 定期索引维护：删除过期日志，更新项目状态，保持索引新鲜

自动记忆维护：

通过 Heartbeat 任务实现自动记忆维护：

{
  "name": "记忆维护",
  "schedule": { "kind": "every", "everyMs": 604800000 }, // 7天
  "payload": {
    "kind": "agentTurn",
    "message": "读取 memory/heartbeat-state.json，检查 lastMemoryMaintenance 字段。如果距今 >= 7 天，执行以下维护任务：\n1. 读最近 7 天的 memory/YYYY-MM-DD.md 日志\n2. 提炼有价值的信息到对应文件（projects.md / lessons.md）\n3. 压缩已完成一次性任务的日志为一行结论\n4. 删除明显过期的信息\n5. 更新 heartbeat-state.json 的 lastMemoryMaintenance 为今天",
  },
  "sessionTarget": "isolated",
  "delivery": { "mode": "none" },
}

维护状态文件 memory/heartbeat-state.json：

{
  "lastMemoryMaintenance": "2026-03-01"
}

---

第五章：多渠道接入运维

5.1 Discord Bot 配置与 MESSAGE CONTENT INTENT

配置流程概述：

Discord Bot 接入需要以下步骤：创建应用 → 开启 Intent → 获取 Token → 配置权限 → 邀请到服务器 → 配置 openclaw.json。

第一步：创建 Discord 应用：

1. 访问 Discord Developer Portal（ https://discord.com/developers/applications ）
2. 点击 "New Application" → 输入应用名称 → 点击 "Create"
3. 在应用页面左侧点击 "Bot"
4. 点击 "Reset Token" → 确认 → 复制显示的 Token（只会显示一次）

第二步：开启 Privileged Gateway Intents：

这是 90% 新手踩坑的地方。MESSAGE CONTENT INTENT 必须开启，否则 Bot 收到消息时无法读取内容。

在 Bot 页面找到 "Privileged Gateway Intents" 部分：

• PRESENCE INTENT：读取用户在线状态（根据需要开启）
• SERVER MEMBERS INTENT：读取服务器成员列表（根据需要开启）
• MESSAGE CONTENT INTENT：读取消息内容（必须开启）

将需要的三项设置为 ON，点击 "Save Changes"。

第三步：配置 Bot 权限：

1. 左侧点击 "OAuth2" → "OAuth2 URL Generator"
2. Scopes 勾选：bot
3. Bot Permissions 勾选：
   • Send Messages
   • Read Message History
   • Add Reactions
   • Use Slash Commands
   • Embed Links（推荐）
4. 复制生成的 OAuth2 URL，在浏览器中打开并授权到目标服务器

第四步：获取服务器 ID：

1. Discord 客户端 → 设置 → 高级 → 开启 "开发者模式"
2. 右键服务器名称 → 复制服务器 ID

第五步：配置 openclaw.json：

{
  channels: {
    discord: {
      token: "your-bot-token",
      allowFrom: [
        "server:123456789012345678",
        "user:987654321098765432",
        "channel:111111111111111111",
      ],
      ackReaction: "👀",
      dm: {
        enabled: true,
        policy: "pairing",
      },
      guilds: {
        "123456789012345678": {
          historyLimit: 20,
          textChunkLimit: 2000,
        },
      },
    },
  },
}

allowFrom 格式说明：

格式	含义
server:<ID>	允许整个服务器
user:<ID>	允许特定用户
channel:<ID>	允许特定频道

可以组合使用，Bot 只响应来自允许来源的消息。

ackReaction 配置：

建议使用不常见的 emoji 作为已读确认，便于在大量消息中识别：

{
  channels: {
    discord: {
      ackReaction: "👀", // 已读确认 emoji
      removeAckAfterReply: false,
    },
  },
}

常见问题排查：

现象	原因	解决方案
Bot 在线但不回复	MESSAGE CONTENT INTENT 未开启	Developer Portal → Bot → 开启 → Save
Bot 完全不在线	Token 错误或 Gateway 未启动	检查 Token，openclaw status 查日志
只能在部分频道回复	Bot 在该频道缺少权限	确认 Bot 在频道有 Send Messages 权限
DM 不工作	dm.policy 设为 pairing 且未完成配对	设为 "open" 或完成配对流程

验证 Discord 连接：

openclaw gateway status

输出中应显示 Discord 渠道状态为在线。如果显示离线，检查：

1. Token 是否正确
2. MESSAGE CONTENT INTENT 是否开启
3. Bot 是否已被移除出服务器
4. Gateway 日志中的具体错误信息

5.2 Telegram Bot 接入

创建 Telegram Bot：

1. Telegram 搜索 @BotFather
2. 发送 /newbot
3. 按提示输入 Bot 名称和用户名
4. BotFather 会返回 Bot Token，格式类似：123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ

获取用户 ID：

1. Telegram 搜索 @userinfobot
2. 向该 Bot 发送任意消息
3. Bot 会返回你的用户 ID，格式类似：123456789

配置 openclaw.json：

{
  channels: {
    telegram: {
      botToken: "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
      allowFrom: ["123456789"],
      dm: {
        enabled: true,
        policy: "pairing",
      },
      historyLimit: 50,
      replyToMode: "first",
      linkPreview: true,
      streamMode: "partial",
    },
  },
}

dm.policy 选项：

值	含义
pairing	用户需要先完成配对流程
allowlist	只允许 allowFrom 列表中的用户
open	允许任何人使用
disabled	禁用 DM

Telegram + Discord 多渠道同时在线：

{
  channels: {
    discord: {
      token: "discord-bot-token",
      allowFrom: ["server:123456789"],
      ackReaction: "👀",
    },
    telegram: {
      botToken: "telegram-bot-token",
      allowFrom: ["123456789"],
    },
  },
}

多渠道配置时，消息路由自动处理——来自哪个渠道的请求，响应就发送到哪个渠道。

5.3 多渠道消息路由机制

路由规则：

OpenClaw 的消息路由基于以下规则：

1. 每条消息携带来源渠道标识
2. 路由决策根据消息来源和配置中的 bindings 确定目标 Agent
3. 响应总是发送到消息来源的同一渠道

多 Agent 绑定：

如果需要不同渠道或不同账号绑定不同的 Agent：

{
  agents: {
    list: [
      { id: "main", default: true, workspace: "~/.openclaw/workspace-main" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "main", match: { channel: "telegram", accountId: "personal" } },
    { agentId: "work", match: { channel: "telegram", accountId: "biz" } },
    { agentId: "main", match: { channel: "discord" } },
  ],
  channels: {
    telegram: {
      accounts: {
        personal: { botToken: "token1" },
        biz: { botToken: "token2" },
      },
    },
  },
}

跨渠道身份链接：

如果用户同时使用多个渠道并希望共享上下文：

{
  session: {
    identityLinks: [
      { key: "user-alice", channels: ["telegram:123456", "discord:987654"] },
    ],
  },
}

配置后，来自这两个渠道的消息会被识别为同一用户，共享会话历史。

5.4 平台格式适配规范

各平台格式支持差异：

格式	Discord	Telegram	WhatsApp
Markdown 表格	支持	不支持	不支持
代码块	支持	支持	不支持
粗体/斜体	支持	支持	支持
Emoji Reaction	支持	支持	支持
链接预览	自动	需要配置	不支持
互动按钮	不支持	支持	有限支持

格式适配规则配置：

在 AGENTS.md 中添加平台格式适配规范：

## 平台格式

### Discord
- 可以使用完整 Markdown
- 代码块使用 triple backtick 包裹
- 多链接使用 <> 包裹防止预览刷屏
- 支持 embed 格式

### Telegram
- 支持 Markdown（部分标签）
- 代码块使用 triple backtick 包裹
- 不支持 Markdown 表格，用 bullet list 代替
- 支持内联按钮

### WhatsApp
- 不支持 Markdown 表格，使用 bullet list
- 代码块使用 inline code（单反引号）
- 链接会自动转换，但不支持预览

输出格式动态调整：

AI 会根据消息来源自动调整输出格式。如果需要显式控制：

## 输出格式控制

当被要求“用表格展示”时：
- 如果是 Discord：用 Markdown 表格
- 如果是 Telegram 或 WhatsApp：用等宽字符模拟表格或改用 bullet list

---

第六章：配置速查与故障排查

6.1 核心配置参数速查表

Gateway 核心配置：

配置路径	作用	推荐值
gateway.port	WebSocket/HTTP 端口	18789
gateway.bind	监听地址	loopback
gateway.auth.mode	认证模式	token
gateway.auth.token	认证 Token	生产环境必填
gateway.reload.mode	热重载模式	hybrid

Agent 核心配置：

配置路径	作用	推荐值
agents.defaults.workspace	workspace 目录	~/.openclaw/workspace
agents.defaults.model.primary	主用模型	实际使用模型
agents.defaults.compaction.reserveTokensFloor	压缩后保留 token 数	20000
agents.defaults.compaction.memoryFlush.enabled	压缩前自动保存	true
agents.defaults.heartbeat.every	心跳间隔	30m
agents.defaults.heartbeat.activeHours	活跃时段	{"start":"08:00","end":"23:00"}

渠道配置速查：

渠道	必填配置	可选配置
Discord	token	allowFrom、ackReaction、guilds
Telegram	botToken	allowFrom、dmPolicy、historyLimit
WhatsApp	allowFrom（E.164 格式）	groupPolicy、sendReadReceipts
Slack	botToken、appToken	dm.enabled、channels

工具配置：

配置路径	作用	推荐值
tools.exec.enabled	允许执行 shell 命令	true
tools.web.search.enabled	允许网页搜索	true
tools.media.image.enabled	允许图片识别	true（需模型支持）
agents.defaults.sandbox.mode	沙箱模式	non-main（生产环境）

流式输出配置：

配置路径	作用	推荐值
agents.defaults.blockStreamingDefault	全局流式开关	"on"
agents.defaults.blockStreamingBreak	分块触发条件	"text_end"
agents.defaults.blockStreamingChunk.minChars	最小分块大小	200
agents.defaults.blockStreamingChunk.maxChars	最大分块大小	1500

6.2 常见故障诊断流程

故障一：Gateway 无法启动

诊断步骤：

# 1. 检查配置文件语法
openclaw doctor

# 2. 检查端口是否被占用
ss -tlnp | grep 18789

# 3. 查看详细错误日志
openclaw gateway start --verbose 2>&1

# 4. 检查日志文件
tail -100 /var/log/openclaw/gateway.log

常见原因：

• JSON5 语法错误（注释格式问题、尾随逗号问题）
• 端口被占用
• auth token 未设置但绑定到非 loopback 地址
• workspace 目录权限不足

故障二：渠道 Bot 不工作

通用诊断流程：

# 1. 检查渠道状态
openclaw gateway status

# 2. 查看渠道连接日志
openclaw logs --grep "discord\|telegram\|whatsapp" --lines 50

# 3. 测试渠道 API 连通性
# Discord: 检查 Bot 是否在线
# Telegram: curl https://api.telegram.org/bot<token>/getMe

Discord 专项检查：

1. 确认 MESSAGE CONTENT INTENT 已开启
2. 确认 Bot 未被服务器禁言或移除
3. 确认 Bot 在目标频道有 Send Messages 权限

Telegram 专项检查：

1. 确认 Bot Token 正确
2. 确认 Bot 未被 Ban
3. 确认用户 ID 在 allowFrom 列表中

故障三：Cron 任务不触发

诊断步骤：

# 1. 检查任务列表
openclaw cron list

# 2. 查看任务详情
openclaw cron list --verbose

# 3. 检查执行历史
openclaw cron runs --id <任务ID>

# 4. 检查调度器状态
openclaw gateway status

常见原因：

• 时区问题：未设置 tz 字段，默认使用 UTC
• 任务被禁用：enabled: false
• delivery.mode 问题：不设为 announce 时任务静默执行
• 调度器未运行：cron.enabled: false

故障四：AI 失忆

诊断步骤：

# 1. 检查 memoryFlush 配置
openclaw config get agents.defaults.compaction

# 2. 检查记忆文件是否存在
ls -la ~/.openclaw/workspace/memory/

# 3. 检查 memorySearch 是否配置
openclaw config get memorySearch

# 4. 查看 compaction 触发日志
openclaw logs --grep "compaction\|memoryFlush" --lines 50

常见原因：

• memoryFlush 未开启
• softThresholdTokens 设置过小
• 记忆文件写入权限问题
• memorySearch 未配置导致检索不到历史

故障五：消息无响应

诊断步骤：

# 1. 检查 allowFrom 配置
openclaw config get channels.<channel>.allowFrom

# 2. 检查消息是否被正确接收
openclaw logs --grep "message\|inbound" --lines 50

# 3. 检查 session 状态
openclaw sessions list

常见原因：

• 消息来源不在 allowFrom 列表
• DM policy 问题（pairing 模式未完成配对）
• 用户被禁言或 Bot 被拉黑

6.3 证据链式的结论验证

配置生效验证：

每个配置变更都应通过以下方式验证生效：

1. 重启验证：变更配置后执行 openclaw gateway restart，观察日志无错误输出
2. 状态验证：openclaw gateway status 显示所有渠道在线
3. 功能验证：实际测试配置的功能点（如发送消息测试 Cron 投递）

日志证据收集：

故障排查时，应收集以下日志作为证据：

# 获取时间范围内的日志
openclaw logs --since "2026-03-20 10:00:00" --until "2026-03-20 12:00:00" > /tmp/gateway-logs.txt

# 获取特定关键词日志
openclaw logs --grep "error\|warn" --lines 200 > /tmp/errors.txt

# 导出完整状态
openclaw gateway status --deep > /tmp/status.txt

配置回滚流程：

重大配置变更前，应先备份当前配置：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d-%H%M%S)

如需回滚：

# 查看备份列表
ls -la ~/.openclaw/openclaw.json.backup-*

# 回滚到指定备份
cp ~/.openclaw/openclaw.json.backup-20260320-143000 ~/.openclaw/openclaw.json

# 重启 Gateway
openclaw gateway restart

健康检查基准线：

建立正常运行时的基准数据，便于故障时对比：

# 记录基准状态
openclaw gateway status --deep > /tmp/status-baseline.txt

# 记录 Cron 任务列表
openclaw cron list > /tmp/cron-baseline.txt

---

附录一：配置清单

部署前检查清单

• [ ] 配置文件 JSON5 语法验证通过（openclaw doctor）
• [ ] Gateway 认证 Token 已设置
• [ ] workspace 目录权限正确
• [ ] 进程管理器已配置（systemd）
• [ ] 日志轮转已配置
• [ ] 所有渠道 Token/Key 已配置
• [ ] memorySearch 已配置（推荐 SiliconFlow bge-m3）
• [ ] 心跳活跃时段已设置（避免半夜打扰）

运维巡检清单

• [ ] openclaw gateway status 所有渠道在线
• [ ] openclaw cron list 无禁用任务异常
• [ ] 磁盘使用率 < 85%
• [ ] 日志文件大小正常，无积压
• [ ] 记忆文件定期更新

安全加固清单

• [ ] Gateway 绑定到 loopback
• [ ] 认证 Token 足够复杂
• [ ] allowFrom 限制最小必要范围
• [ ] 日志中无敏感信息泄露（检查 redactSensitive 配置）
• [ ] 定期更新 OpenClaw 版本

---

附录二：命令速查

Gateway 管理

openclaw gateway start          # 启动 Gateway
openclaw gateway restart       # 重启 Gateway
openclaw gateway stop           # 停止 Gateway
openclaw gateway reload        # 热重载配置
openclaw gateway health        # 存活性检查
openclaw gateway status        # 状态检查
openclaw gateway status --deep # 深度状态检查

日志管理

openclaw logs --follow         # 实时跟踪
openclaw logs --lines 100      # 最近 100 行
openclaw logs --grep "error"  # 过滤关键词

Cron 管理

openclaw cron list             # 任务列表
openclaw cron runs --id <ID>   # 执行历史
openclaw cron edit <ID> --disable # 禁用任务
openclaw cron edit <ID> --enable  # 启用任务
openclaw cron run --id <ID> --force  # 手动触发

配置管理

openclaw config validate        # 验证配置
openclaw config get <key>       # 获取配置项
openclaw doctor                 # 诊断检查

---

附录三：配置文件模板

{
  // Workspace 配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      repoRoot: "~/.openclaw/workspace",
      skipBootstrap: false,
      model: {
        primary: "provider/claude-sonnet-4",
        fallbacks: ["provider/claude-haiku-4"],
      },
      imageModel: "provider/claude-sonnet-4",
      timeoutSeconds: 600,
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
        },
      },
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "08:00",
          end: "23:00",
        },
      },
      blockStreamingDefault: "on",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 200,
        maxChars: 1500,
      },
    },
  },

  // Gateway 配置
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "your-secret-token",
    },
    reload: {
      mode: "hybrid",
    },
  },

  // 日志配置
  logging: {
    level: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // 渠道配置
  channels: {
    discord: {
      token: "your-discord-bot-token",
      allowFrom: ["server:your-server-id"],
      ackReaction: "👀",
      dm: {
        enabled: true,
        policy: "pairing",
      },
      historyLimit: 20,
      textChunkLimit: 2000,
    },
    telegram: {
      botToken: "your-telegram-bot-token",
      allowFrom: ["your-user-id"],
      dm: {
        enabled: true,
        policy: "pairing",
      },
      historyLimit: 50,
      replyToMode: "first",
      linkPreview: true,
      streamMode: "partial",
    },
  },

  // 向量检索配置
  memorySearch: {
    enabled: true,
    provider: "openai",
    remote: {
      baseUrl: "https://api.siliconflow.cn/v1",
      apiKey: "your-siliconflow-api-key",
    },
    model: "BAAI/bge-m3",
  },

  // 工具配置
  tools: {
    exec: {
      enabled: true,
    },
    web: {
      search: {
        enabled: true,
      },
    },
    media: {
      image: {
        enabled: true,
      },
    },
  },

  // Cron 配置
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
  },
}

---

文档版本：2026.03
参考来源：OpenClaw 官方文档（openclaw.cc）