干货分享！OpenClaw 进阶配置与自动化运维实战手册

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

{
  // 核心配置区
  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 config validate --key agents.defaults.model 

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

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

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

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

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

# 4. 执行重启
openclaw gateway restart

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

[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

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

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

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

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

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

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

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

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

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

openclaw gateway start --verbose

# 实时跟踪日志
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: {
    redactPatterns: [
      "sk-[a-zA-Z0-9]{20,}", // OpenAI API Key 格式
      "Bearer [a-zA-Z0-9._-]+", // Bearer Token 格式
    ],
  },
}

openclaw gateway health 

openclaw gateway status 

openclaw gateway status --deep

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

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

[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

/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
}

[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"

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openclaw gateway restart --verbose

# 核心记忆

## 用户信息
- 姓名：
- 时区：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

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

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

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

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

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

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

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

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

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

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

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

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

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

## 平台格式

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

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

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

## 输出格式控制

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

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

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

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

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

# 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 

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

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

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

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

# 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  

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

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

# 3. 检查 session 状态 
openclaw sessions list

# 获取时间范围内的日志   
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  

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"   # 过滤关键词

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,
  },
}