openclaw-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenClaw Operations Runbook

OpenClaw 操作手册

Diagnose and fix real problems. Every command here is tested and works.

诊断并修复实际问题。此处的每个命令均经过测试且可用。

Quick Health Check

快速健康检查

Run this first when anything seems wrong. Copy-paste the whole block:

bash

echo "=== GATEWAY ===" && \
ps aux | grep -c "[o]penclaw" && \
echo "=== CONFIG JSON ===" && \
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null 2>&1 && echo "JSON: OK" || echo "JSON: BROKEN" && \
echo "=== CHANNELS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.channels | to_entries[] | "\(.key): policy=\(.value.dmPolicy // "n/a") enabled=\(.value.enabled // "implicit")"' && \
echo "=== PLUGINS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.plugins.entries | to_entries[] | "\(.key): \(.value.enabled)"' && \
echo "=== CREDS ===" && \
ls ~/.openclaw/credentials/whatsapp/default/ 2>/dev/null | wc -l | xargs -I{} echo "WhatsApp keys: {} files" && \
for d in ~/.openclaw/credentials/telegram/*/; do bot=$(basename "$d"); [ -f "$d/token.txt" ] && echo "Telegram $bot: OK" || echo "Telegram $bot: MISSING"; done && \
[ -f ~/.openclaw/credentials/bird/cookies.json ] && echo "Bird cookies: OK" || echo "Bird cookies: MISSING" && \
echo "=== CRON ===" && \
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.name): enabled=\(.enabled) status=\(.state.lastStatus // "never") \(.state.lastError // "")"' && \
echo "=== RECENT ERRORS ===" && \
tail -10 ~/.openclaw/logs/gateway.err.log 2>/dev/null && \
echo "=== MEMORY DB ===" && \
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) || ' chunks, ' || (SELECT COUNT(*) FROM files) || ' files indexed' FROM chunks;" 2>/dev/null

当出现任何问题时，首先运行以下命令。复制粘贴整个代码块：

bash

echo "=== GATEWAY ===" && \
ps aux | grep -c "[o]penclaw" && \
echo "=== CONFIG JSON ===" && \
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null 2>&1 && echo "JSON: OK" || echo "JSON: BROKEN" && \
echo "=== CHANNELS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.channels | to_entries[] | "\(.key): policy=\(.value.dmPolicy // "n/a") enabled=\(.value.enabled // "implicit")"' && \
echo "=== PLUGINS ===" && \
cat ~/.openclaw/openclaw.json | jq -r '.plugins.entries | to_entries[] | "\(.key): \(.value.enabled)"' && \
echo "=== CREDS ===" && \
ls ~/.openclaw/credentials/whatsapp/default/ 2>/dev/null | wc -l | xargs -I{} echo "WhatsApp keys: {} files" && \
for d in ~/.openclaw/credentials/telegram/*/; do bot=$(basename "$d"); [ -f "$d/token.txt" ] && echo "Telegram $bot: OK" || echo "Telegram $bot: MISSING"; done && \
[ -f ~/.openclaw/credentials/bird/cookies.json ] && echo "Bird cookies: OK" || echo "Bird cookies: MISSING" && \
echo "=== CRON ===" && \
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.name): enabled=\(.enabled) status=\(.state.lastStatus // "never") \(.state.lastError // "")"' && \
echo "=== RECENT ERRORS ===" && \
tail -10 ~/.openclaw/logs/gateway.err.log 2>/dev/null && \
echo "=== MEMORY DB ===" && \
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) || ' chunks, ' || (SELECT COUNT(*) FROM files) || ' files indexed' FROM chunks;" 2>/dev/null

File Map

文件结构

~/.openclaw/
├── openclaw.json                    # MAIN CONFIG — channels, auth, gateway, plugins, skills
├── openclaw.json.bak*               # Auto-backups (.bak, .bak.1, .bak.2 ...)
├── exec-approvals.json              # Exec approval socket config
│
├── agents/main/
│   ├── agent/auth-profiles.json     # Anthropic auth tokens
│   └── sessions/
│       ├── sessions.json            # SESSION INDEX — keys are like agent:main:whatsapp:+1234
│       └── *.jsonl                  # Session transcripts (one JSON per line)
│
├── workspace/                       # Agent workspace (git-tracked)
│   ├── SOUL.md                      # Personality, writing style, tone rules
│   ├── IDENTITY.md                  # Name, creature type, vibe
│   ├── USER.md                      # Owner context and preferences
│   ├── AGENTS.md                    # Session behavior, memory rules, safety
│   ├── BOOT.md                      # Boot instructions (autopilot notification protocol)
│   ├── HEARTBEAT.md                 # Periodic task checklist (empty = skip heartbeat)
│   ├── MEMORY.md                    # Curated long-term memory (main session only)
│   ├── TOOLS.md                     # Contacts, SSH hosts, device nicknames
│   ├── memory/                      # Daily logs: YYYY-MM-DD.md, topic-chat.md
│   └── skills/                      # Workspace-level skills
│
├── memory/main.sqlite               # Vector memory DB (Gemini embeddings, FTS5 search)
│
├── logs/
│   ├── gateway.log                  # Runtime: startup, channel init, config reload, shutdown
│   ├── gateway.err.log              # Errors: connection drops, API failures, timeouts
│   └── commands.log                 # Command execution log
│
├── cron/
│   ├── jobs.json                    # Job definitions (schedule, payload, delivery target)
│   └── runs/                        # Per-job run logs: {job-uuid}.jsonl
│
├── credentials/
│   ├── whatsapp/default/            # Baileys session: ~1400 app-state-sync-key-*.json files
│   ├── telegram/{botname}/token.txt # Bot tokens (one per bot account)
│   └── bird/cookies.json            # X/Twitter auth cookies
│
├── extensions/{name}/               # Custom plugins (TypeScript)
│   ├── openclaw.plugin.json         # {"id", "channels", "configSchema"}
│   ├── index.ts                     # Entry point
│   └── src/                         # channel.ts, actions.ts, runtime.ts, types.ts
│
├── identity/                        # device.json, device-auth.json
├── devices/                         # paired.json, pending.json
├── media/inbound/                   # Received images, audio files
├── media/browser/                   # Browser screenshots
├── browser/openclaw/user-data/      # Chromium profile (~180MB)
├── tools/signal-cli/                # Signal CLI binary
├── subagents/runs.json              # Sub-agent execution log
├── canvas/index.html                # Web canvas UI
└── telegram/
    ├── update-offset-coder.json     # {"lastUpdateId": N} — Telegram polling cursor
    └── update-offset-sales.json     # Reset these to 0 to replay missed messages

~/.openclaw/
├── openclaw.json                    # 主配置文件 — 渠道、认证、网关、插件、技能
├── openclaw.json.bak*               # 自动备份文件（.bak, .bak.1, .bak.2 ...）
├── exec-approvals.json              # 执行审批套接字配置
│
├── agents/main/
│   ├── agent/auth-profiles.json     # Anthropic 认证令牌
│   └── sessions/
│       ├── sessions.json            # 会话索引 — 键格式如 agent:main:whatsapp:+1234
│       └── *.jsonl                  # 会话记录（每行一个JSON对象）
│
├── workspace/                       # Agent工作区（Git跟踪）
│   ├── SOUL.md                      # 个性、写作风格、语气规则
│   ├── IDENTITY.md                  # 名称、角色类型、风格
│   ├── USER.md                      # 所有者上下文与偏好
│   ├── AGENTS.md                    # 会话行为、记忆规则、安全设置
│   ├── BOOT.md                      # 启动指令（自动操作通知协议）
│   ├── HEARTBEAT.md                 # 定期任务清单（空表示跳过心跳）
│   ├── MEMORY.md                    # 精选长期记忆（仅主会话加载）
│   ├── TOOLS.md                     # 联系人、SSH主机、设备别名
│   ├── memory/                      # 每日日志：YYYY-MM-DD.md，主题聊天日志
│   └── skills/                      # 工作区级技能
│
├── memory/main.sqlite               # 向量记忆数据库（Gemini嵌入、FTS5搜索）
│
├── logs/
│   ├── gateway.log                  # 运行时日志：启动、渠道初始化、配置重载、关闭
│   ├── gateway.err.log              # 错误日志：连接断开、API失败、超时
│   └── commands.log                 # 命令执行日志
│
├── cron/
│   ├── jobs.json                    # 任务定义（调度、负载、交付目标）
│   └── runs/                        # 每个任务的运行日志：{job-uuid}.jsonl
│
├── credentials/
│   ├── whatsapp/default/            # Baileys会话：约1400个app-state-sync-key-*.json文件
│   ├── telegram/{botname}/token.txt # Bot令牌（每个Bot账户一个）
│   └── bird/cookies.json            # X/Twitter认证Cookie
│
├── extensions/{name}/               # 自定义插件（TypeScript）
│   ├── openclaw.plugin.json         # {"id", "channels", "configSchema"}
│   ├── index.ts                     # 入口文件
│   └── src/                         # channel.ts, actions.ts, runtime.ts, types.ts
│
├── identity/                        # device.json, device-auth.json
├── devices/                         # paired.json, pending.json
├── media/inbound/                   # 接收的图片、音频文件
├── media/browser/                   # 浏览器截图
├── browser/openclaw/user-data/      # Chromium配置文件（约180MB）
├── tools/signal-cli/                # Signal CLI二进制文件
├── subagents/runs.json              # 子Agent执行日志
├── canvas/index.html                # Web画布UI
└── telegram/
    ├── update-offset-coder.json     # {"lastUpdateId": N} — Telegram轮询游标
    └── update-offset-sales.json     # 重置为0可重放遗漏的消息

Troubleshooting: WhatsApp

故障排查：WhatsApp

"I sent a message but got no reply"

"我发送了消息但没有收到回复"

This is the #1 issue. The message arrives but the bot doesn't respond. Check in this order:

bash

undefined

这是最常见的问题。消息已送达但机器人未响应。按以下顺序检查：

bash

undefined

1. Is the bot actually running?

1. 机器人是否真的在运行？

grep -i "whatsapp.*starting|whatsapp.*listening" ~/.openclaw/logs/gateway.log | tail -5

2. Check for 408 timeout drops (WhatsApp web disconnects frequently)

2. 检查408超时断开（WhatsApp网页版经常断开连接）

grep -i "408|499|retry" ~/.openclaw/logs/gateway.err.log | tail -10

If you see "Web connection closed (status 408). Retry 1/12" — this is normal,

如果看到"Web connection closed (status 408). Retry 1/12" — 这是正常现象，

it auto-recovers. But if retries reach 12/12, the session dropped completely.

会自动恢复。但如果重试次数达到12/12，则会话完全断开。

3. Check for cross-context messaging blocks

3. 检查跨上下文消息拦截

grep -i "cross-context.*denied" ~/.openclaw/logs/gateway.err.log | tail -10

Common: "Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal""

常见情况："Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal""

This means the agent was in a Signal session and tried to reply on WhatsApp.

这表示Agent处于Signal会话中，尝试在WhatsApp上回复。

FIX: The message needs to come through in the WhatsApp session context, not Signal.

修复方法：消息需要通过WhatsApp会话上下文发送，而非Signal。

4. Check the session exists for that contact

4. 检查该联系人的会话是否存在

5. Check if the sender is allowed

5. 检查发送者是否被允许

cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp | {dmPolicy, allowFrom, selfChatMode, groupPolicy}'

If dmPolicy is "allowlist" and the sender isn't in allowFrom, message is silently dropped.

如果dmPolicy为"allowlist"且发送者不在allowFrom列表中，消息会被静默丢弃。

6. Check if it's a group message (groups are disabled by default)

6. 检查是否为群组消息（默认禁用群组）

cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp.groupPolicy'

"disabled" means ALL group messages are ignored.

"disabled"表示所有群组消息都会被忽略。

7. Check for lane congestion (agent busy with another task)

7. 检查通道拥塞（Agent正忙于其他任务）

grep "lane wait exceeded" ~/.openclaw/logs/gateway.err.log | tail -5

If the agent is stuck on a long LLM call, new messages queue up.

如果Agent卡在长时间的LLM调用上，新消息会排队等待。

8. Check for agent run timeout

8. 检查Agent运行超时

grep "embedded run timeout" ~/.openclaw/logs/gateway.err.log | tail -5

Hard limit is 600s (10 min). If the agent's response takes longer, it's killed.

硬限制为600秒（10分钟）。如果Agent响应时间超过此限制，会被终止。

undefined

undefined

"WhatsApp fully disconnected"

"WhatsApp完全断开连接"

bash

undefined

bash

undefined

Check credential files exist (should be ~1400 files)

检查凭证文件是否存在（应约有1400个文件）

ls ~/.openclaw/credentials/whatsapp/default/ | wc -l

If 0 files: session was never created or got wiped

如果文件数为0：会话从未创建或已被清除

Fix: re-pair with

openclaw configure

修复方法：使用

openclaw configure

重新配对

Check for QR/pairing events

检查二维码/配对事件

Check for Baileys errors

检查Baileys错误

grep -i "baileys|DisconnectReason|logout|stream:error" ~/.openclaw/logs/gateway.err.log | tail -20

Nuclear fix: delete credentials and re-pair

终极修复：删除凭证并重新配对

rm -rf ~/.openclaw/credentials/whatsapp/default/

openclaw configure

---

---

Troubleshooting: Telegram

故障排查：Telegram

"Bots have issues / forget things"

"Bot出现问题/忘记内容"

Two separate problems that look the same:

bash

undefined

这是两个看似相同但不同的问题：

bash

undefined

1. Check for config validation errors (THE COMMON ONE)

1. 检查配置验证错误（最常见）

grep -i "telegram.*unrecognized|telegram.*invalid|telegram.*policy" ~/.openclaw/logs/gateway.err.log | tail -10

Known issue: the keys "token" and "username" under accounts are not recognized.

已知问题：accounts下的"token"和"username"键不被识别。

The correct field is "botToken", not "token".

正确的字段是"botToken"，而非"token"。

2. Check the actual config

2. 检查实际配置

cat ~/.openclaw/openclaw.json | jq '.channels.telegram'

Verify each bot has "botToken" (not "token") and "name" fields.

验证每个Bot都有"botToken"（而非"token"）和"name"字段。

3. Check polling status — bots die after getUpdates timeout

3. 检查轮询状态 — Bot在getUpdates超时后会停止运行

grep -i "telegram.*exit|telegram.*timeout|getUpdates" ~/.openclaw/logs/gateway.err.log | tail -10

"[telegram] [sales] channel exited: Request to 'getUpdates' timed out after 500 seconds"

This means the bot lost connection to Telegram's API and stopped listening.

这表示Bot与Telegram API的连接丢失，停止监听。

Fix: restart gateway —

openclaw gateway restart

修复方法：重启网关 —

openclaw gateway restart

4. Check the polling offset (if bot "forgets" or replays old messages)

4. 检查轮询偏移量（如果Bot"忘记"或重放旧消息）

cat ~/.openclaw/telegram/update-offset-coder.json cat ~/.openclaw/telegram/update-offset-sales.json

If lastUpdateId is stuck or 0, the bot will reprocess old messages.

如果lastUpdateId卡住或为0，Bot会重新处理旧消息。

To skip to latest: the gateway sets this automatically on restart.

要跳转到最新消息：网关重启时会自动设置此值。

5. Check if both bots are starting

5. 检查两个Bot是否都已启动

grep -i "telegram.*starting|telegram.*coder|telegram.*sales" ~/.openclaw/logs/gateway.log | tail -10

6. "Bot forgets" — this is usually a session issue, not Telegram

6. "Bot忘记内容" — 通常是会话问题，而非Telegram问题

Each Telegram user gets their own session in sessions.json.

每个Telegram用户在sessions.json中都有自己的会话。

Check if the session exists:

检查会话是否存在：

7. Check if compaction happened (context window pruned = "forgot")

7. 检查是否发生压缩（上下文窗口被修剪 = "忘记"）

SESS_ID="paste-session-id" grep '"compaction"' ~/.openclaw/agents/main/sessions/$SESS_ID.jsonl | wc -l

If compaction count > 0, old messages were pruned from context.

如果压缩次数>0，旧消息已从上下文中被修剪。

The agent's compaction mode is:

Agent的压缩模式为：

cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'

undefined

cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'

undefined

Telegram config fix template

Telegram配置修复模板

bash

undefined

bash

undefined

Correct Telegram config structure:

正确的Telegram配置结构：

cat ~/.openclaw/openclaw.json | jq '.channels.telegram = { "enabled": true, "accounts": { "coder": { "name": "Bot Display Name", "enabled": true, "botToken": "your-bot-token-here" }, "sales": { "name": "Sales Bot Name", "enabled": true, "botToken": "your-bot-token-here" } }, "dmPolicy": "pairing", "groupPolicy": "disabled" }' > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

---

cat ~/.openclaw/openclaw.json | jq '.channels.telegram = { "enabled": true, "accounts": { "coder": { "name": "Bot显示名称", "enabled": true, "botToken": "你的Bot令牌" }, "sales": { "name": "销售Bot名称", "enabled": true, "botToken": "你的Bot令牌" } }, "dmPolicy": "pairing", "groupPolicy": "disabled" }' > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

---

Troubleshooting: Signal

故障排查：Signal

"Signal RPC Failed to send message"

"Signal RPC 发送消息失败"

This blocks cron jobs and cross-channel notifications.

bash

undefined

这会阻止Cron任务和跨渠道通知。

bash

undefined

1. Check if signal-cli process is alive

1. 检查signal-cli进程是否存活

ps aux | grep "[s]ignal-cli"

2. Check the RPC endpoint

2. 检查RPC端点

grep -i "signal.*starting|signal.*8080|signal.*rpc" ~/.openclaw/logs/gateway.log | tail -10

Should see: "[signal] [default] starting provider (http://127.0.0.1:8080)"

应看到："[signal] [default] starting provider (http://127.0.0.1:8080)"

3. Check for connection instability

3. 检查连接稳定性

grep -i "HikariPool|reconnecting|SSE stream error|terminated" ~/.openclaw/logs/gateway.err.log | tail -10

"HikariPool-1 - Thread starvation or clock leap detected" = signal-cli internal DB issue

"HikariPool-1 - Thread starvation or clock leap detected" = signal-cli内部数据库问题

"SSE stream error: TypeError: terminated" = lost connection to signal-cli daemon

"SSE stream error: TypeError: terminated" = 与signal-cli守护进程的连接丢失

4. Check for rate limiting

4. 检查速率限制

grep -i "signal.*rate" ~/.openclaw/logs/gateway.err.log | tail -5

"Signal RPC -5: Failed to send message due to rate limiting"

5. Check for wrong target format

5. 检查目标格式是否错误

grep -i "unknown target" ~/.openclaw/logs/gateway.err.log | tail -5

"Unknown target "adi" for Signal. Hint: <E.164|uuid:ID|...>"

The agent must use phone numbers (+1...) or uuid: format, not names.

Agent必须使用电话号码（+1...）或uuid:格式，而非名称。

6. Fix profile name warning spam

6. 修复配置文件名称警告 spam

grep -c "No profile name set" ~/.openclaw/logs/gateway.err.log

If high count: run signal-cli updateProfile to set a name

如果数量较多：运行signal-cli updateProfile设置名称

7. Test signal-cli directly

7. 直接测试signal-cli

ACCT=$(cat ~/.openclaw/openclaw.json | jq -r '.channels.signal.account') echo "Account: $ACCT"

ACCT=$(cat ~/.openclaw/openclaw.json | jq -r '.channels.signal.account') echo "账户: $ACCT"

signal-cli -a $ACCT send -m "test" +TARGET_NUMBER

signal-cli -a $ACCT send -m "test" +目标号码

8. Check if the signal-cli daemon needs restart

8. 检查signal-cli守护进程是否需要重启

The gateway manages signal-cli as a subprocess.

网关将signal-cli作为子进程管理。

Restart the whole gateway: openclaw gateway restart

重启整个网关：openclaw gateway restart

---

---

Troubleshooting: Cron Jobs

故障排查：Cron任务

bash

undefined

bash

undefined

1. Overview of all jobs

1. 所有任务概览

cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "(.enabled | if . then "ON " else "OFF" end) (.state.lastStatus // "never" | if . == "error" then "FAIL" elif . == "ok" then "OK " else . end) (.name)"'

2. Failing jobs with error details

2. 带错误详情的失败任务

cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | select(.state.lastStatus == "error") | {name, error: .state.lastError, lastRun: (.state.lastRunAtMs | . / 1000 | todate), id}'

3. Read the actual run log for a failing job

3. 读取失败任务的实际运行日志

JOB_ID="paste-job-uuid-here" tail -20 ~/.openclaw/cron/runs/$JOB_ID.jsonl | python3 -c " import sys, json for line in sys.stdin: try: obj = json.loads(line) if obj.get('type') == 'message': role = obj['message']['role'] text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict)) if text.strip(): print(f'[{role}] {text[:300]}') except: pass "

JOB_ID="粘贴任务UUID" tail -20 ~/.openclaw/cron/runs/$JOB_ID.jsonl | python3 -c " import sys, json for line in sys.stdin: try: obj = json.loads(line) if obj.get('type') == 'message': role = obj['message']['role'] text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict)) if text.strip(): print(f'[{role}] {text[:300]}') except: pass "

4. Common cron failure causes:

4. 常见Cron任务失败原因：

- "Signal RPC -1" → Signal daemon down, see Signal section above

- "Signal RPC -1" → Signal守护进程已停止，查看上方Signal部分

- "gateway timeout after 10000ms" → gateway was restarting when cron fired

- "gateway timeout after 10000ms" → Cron触发时网关正在重启

- "Brave Search 429" → free tier rate limit hit (2000 req/month)

- "Brave Search 429" → 免费层速率限制触发（每月2000次请求）

- "embedded run timeout" → job took longer than 600s

- "embedded run timeout" → 任务耗时超过600秒

5. Next scheduled run times

5. 下一次计划运行时间

6. Disable a broken job temporarily

6. 暂时禁用有问题的任务

cat ~/.openclaw/cron/jobs.json | jq '(.jobs[] | select(.name == "JOB_NAME")).enabled = false' > /tmp/cron.json && mv /tmp/cron.json ~/.openclaw/cron/jobs.json

---

cat ~/.openclaw/cron/jobs.json | jq '(.jobs[] | select(.name == "任务名称")).enabled = false' > /tmp/cron.json && mv /tmp/cron.json ~/.openclaw/cron/jobs.json

---

Troubleshooting: Memory / "It Forgot"

故障排查：记忆 / "它忘记了内容"

The memory system has 3 layers. When the agent "forgets," one of these broke:

记忆系统分为3层。当Agent"忘记"内容时，其中某一层出现了问题：

Layer 1: Context window (within a session)

第一层：上下文窗口（会话内）

bash

undefined

bash

undefined

Check compaction count for a session (compaction = old messages pruned)

检查会话的压缩次数（压缩 = 旧消息被修剪）

grep -c '"compaction"' ~/.openclaw/agents/main/sessions/SESSION_ID.jsonl

grep -c '"compaction"' ~/.openclaw/agents/main/sessions/会话ID.jsonl

7 compactions = the agent has "forgotten" its earliest messages 7 times.

7次压缩表示Agent已"忘记"最早的消息7次。

Check compaction mode

检查压缩模式

cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'

"safeguard" = only compacts when hitting context limit

"safeguard" = 仅在达到上下文限制时进行压缩

undefined

undefined

Layer 2: Workspace memory files

第二层：工作区记忆文件

bash

undefined

bash

undefined

What daily memory files exist

存在哪些每日记忆文件

ls -la ~/.openclaw/workspace/memory/

What's in MEMORY.md (long-term curated)

MEMORY.md中的内容（精选长期记忆）

cat ~/.openclaw/workspace/MEMORY.md

Search memory files for something specific

在记忆文件中搜索特定内容

grep -ri "KEYWORD" ~/.openclaw/workspace/memory/

undefined

grep -ri "关键词" ~/.openclaw/workspace/memory/

undefined

Layer 3: Vector memory database (SQLite + Gemini embeddings)

第三层：向量记忆数据库（SQLite + Gemini嵌入）

bash

undefined

bash

undefined

What files are indexed

已索引哪些文件

sqlite3 ~/.openclaw/memory/main.sqlite "SELECT path, size, datetime(mtime/1000, 'unixepoch') as modified FROM files;"

How many chunks (text fragments) exist

存在多少个文本块（文本片段）

sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) FROM chunks;"

Search chunks by text (FTS5 full-text search)

通过文本搜索块（FTS5全文搜索）

sqlite3 ~/.openclaw/memory/main.sqlite "SELECT substr(text, 1, 200) FROM chunks_fts WHERE chunks_fts MATCH 'KEYWORD' LIMIT 5;"

sqlite3 ~/.openclaw/memory/main.sqlite "SELECT substr(text, 1, 200) FROM chunks_fts WHERE chunks_fts MATCH '关键词' LIMIT 5;"

Check embedding config

检查嵌入配置

sqlite3 ~/.openclaw/memory/main.sqlite "SELECT value FROM meta WHERE key='memory_index_meta_v1';" | python3 -m json.tool

Check for Gemini embedding rate limits (breaks indexing)

检查Gemini嵌入速率限制（会破坏索引）

grep -i "gemini.*batch.*failed|RESOURCE_EXHAUSTED|429" ~/.openclaw/logs/gateway.err.log | tail -10

"embeddings: gemini batch failed (2/2); disabling batch" = indexing degraded

"embeddings: gemini batch failed (2/2); disabling batch" = 索引性能下降

Rebuild memory index (re-index all workspace files)

重建记忆索引（重新索引所有工作区文件）

Delete the DB and restart gateway — it will rebuild:

删除数据库并重启网关 — 会自动重建：

rm ~/.openclaw/memory/main.sqlite && openclaw gateway restart

---

---

Searching Sessions

搜索会话

Find a person's conversations

查找某人的对话

bash

undefined

bash

undefined

Search session index by name (case-insensitive)

按名称搜索会话索引（不区分大小写）

undefined

undefined

Find sessions by channel

按渠道查找会话

bash

cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.value.lastChannel == "whatsapp") | "\(.value.sessionId) | \(.value.origin.label // .key)"'

bash

cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.value.lastChannel == "whatsapp") | "\(.value.sessionId) | \(.value.origin.label // .key)"'

Replace "whatsapp" with: signal, telegram, or check .key for cron sessions

将"whatsapp"替换为：signal、telegram，或检查.key字段查找Cron会话

undefined

undefined

Most recent sessions

Search message content across all sessions

跨所有会话搜索消息内容

bash

undefined

bash

undefined

Quick: find which session files contain a keyword

快速查找包含关键词的会话文件

grep -l "KEYWORD" ~/.openclaw/agents/main/sessions/*.jsonl

grep -l "关键词" ~/.openclaw/agents/main/sessions/*.jsonl

Detailed: show matching messages with timestamps

详细显示带时间戳的匹配消息

grep "KEYWORD" ~/.openclaw/agents/main/sessions/*.jsonl | python3 -c " import sys, json for line in sys.stdin: path, data = line.split(':', 1) try: obj = json.loads(data) if obj.get('type') == 'message': role = obj['message']['role'] text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict)) if text.strip(): sid = path.split('/')[-1].replace('.jsonl','')[:8] ts = obj.get('timestamp','')[:19] print(f'{ts} [{sid}] [{role}] {text[:200]}') except: pass " | head -30

undefined

grep "关键词" ~/.openclaw/agents/main/sessions/*.jsonl | python3 -c " import sys, json for line in sys.stdin: path, data = line.split(':', 1) try: obj = json.loads(data) if obj.get('type') == 'message': role = obj['message']['role'] text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict)) if text.strip(): sid = path.split('/')[-1].replace('.jsonl','')[:8] ts = obj.get('timestamp','')[:19] print(f'{ts} [{sid}] [{role}] {text[:200]}') except: pass " | head -30

undefined

Read a specific session transcript

读取特定会话记录

bash

undefined

bash

undefined

Last 30 messages from a session

会话的最后30条消息

tail -50 ~/.openclaw/agents/main/sessions/SESSION_ID.jsonl | python3 -c " import sys, json for line in sys.stdin: try: obj = json.loads(line) if obj.get('type') == 'message': role = obj['message']['role'] text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict)) if text.strip() and role != 'toolResult': print(f'[{role}] {text[:300]}') print() except: pass "

---

tail -50 ~/.openclaw/agents/main/sessions/会话ID.jsonl | python3 -c " import sys, json for line in sys.stdin: try: obj = json.loads(line) if obj.get('type') == 'message': role = obj['message']['role'] text = ''.join(c.get('text','') for c in obj['message'].get('content',[]) if isinstance(c,dict)) if text.strip() and role != 'toolResult': print(f'[{role}] {text[:300]}') print() except: pass "

---

Config Editing

配置编辑

Safe edit pattern

安全编辑模式

Always: backup, edit with jq, restart.

bash

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.manual
jq 'YOUR_EDIT_HERE' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json
openclaw gateway restart

始终遵循：备份、使用jq编辑、重启。

bash

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.manual
jq '你的编辑内容' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json
openclaw gateway restart

Common edits

常见编辑操作

bash

undefined

bash

undefined

Switch WhatsApp to allowlist

将WhatsApp切换为白名单模式

jq '.channels.whatsapp.dmPolicy = "allowlist" | .channels.whatsapp.allowFrom = ["+1XXXXXXXXXX"]' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

Enable WhatsApp autopilot (bot responds as you to everyone)

启用WhatsApp自动操作模式（机器人以你的身份回复所有人）

jq '.channels.whatsapp += {dmPolicy: "open", selfChatMode: false, allowFrom: ["*"]}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

Add number to Signal allowlist

将号码添加到Signal白名单

jq '.channels.signal.allowFrom += ["+1XXXXXXXXXX"]' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

Change model

更换模型

jq '.agents.defaults.models = {"anthropic/claude-sonnet-4": {"alias": "sonnet"}}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

Set concurrency

设置并发数

jq '.agents.defaults.maxConcurrent = 10 | .agents.defaults.subagents.maxConcurrent = 10' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

Disable a plugin

禁用插件

jq '.plugins.entries.imessage.enabled = false' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

undefined

jq '.plugins.entries.imessage.enabled = false' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

undefined

Restore from backup

从备份恢复

bash

undefined

bash

undefined

Latest backup

List all backups by date

按日期列出所有备份

ls -lt ~/.openclaw/openclaw.json.bak*

Validate JSON before restart

重启前验证JSON格式

python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null && echo "OK" || echo "BROKEN"

Nuclear reset

终极重置

openclaw configure

---

openclaw configure

---

Channel Security Modes

渠道安全模式

Mode	Behavior	Risk
`open` + `allowFrom: ["*"]`	Anyone can message, bot responds to all	HIGH — burns API credits, bot speaks as you
`allowlist` + `allowFrom: ["+1..."]`	Only listed numbers get through	LOW — explicit control
`pairing`	Unknown senders get a code, you approve	LOW — approval gate
`disabled`	Channel completely off	NONE

模式	行为	风险
`open` + `allowFrom: ["*"]`	任何人都可以发送消息，机器人回复所有消息	高 — 消耗API额度，机器人以你的身份发言
`allowlist` + `allowFrom: ["+1..."]`	仅列出的号码可以发送消息	低 — 明确控制
`pairing`	未知发送者会收到验证码，需你批准	低 — 批准门槛
`disabled`	渠道完全关闭	无

Check current security posture

检查当前安全状态

bash

cat ~/.openclaw/openclaw.json | jq '{
  whatsapp: {policy: .channels.whatsapp.dmPolicy, from: .channels.whatsapp.allowFrom, groups: .channels.whatsapp.groupPolicy, selfChat: .channels.whatsapp.selfChatMode},
  signal: {policy: .channels.signal.dmPolicy, from: .channels.signal.allowFrom, groups: .channels.signal.groupPolicy},
  telegram: {policy: .channels.telegram.dmPolicy, groups: .channels.telegram.groupPolicy, bots: [.channels.telegram.accounts | to_entries[] | "\(.key)=\(.value.enabled)"]},
  imessage: {enabled: .channels.imessage.enabled, policy: .channels.imessage.dmPolicy}
}'

bash

cat ~/.openclaw/openclaw.json | jq '{
  whatsapp: {policy: .channels.whatsapp.dmPolicy, from: .channels.whatsapp.allowFrom, groups: .channels.whatsapp.groupPolicy, selfChat: .channels.whatsapp.selfChatMode},
  signal: {policy: .channels.signal.dmPolicy, from: .channels.signal.allowFrom, groups: .channels.signal.groupPolicy},
  telegram: {policy: .channels.telegram.dmPolicy, groups: .channels.telegram.groupPolicy, bots: [.channels.telegram.accounts | to_entries[] | "\(.key)=\(.value.enabled)"]},
  imessage: {enabled: .channels.imessage.enabled, policy: .channels.imessage.dmPolicy}
}'

Workspace Files

工作区文件

File	What	When to edit
`SOUL.md`	Personality: tone, style ("no em dashes, lowercase casual")	To change how the bot talks
`IDENTITY.md`	Name (Jarvis), creature type, emoji	To rebrand
`USER.md`	Owner info, preferences	When user context changes
`AGENTS.md`	Operating rules: memory protocol, safety, group chat behavior, heartbeat instructions	To change bot behavior
`BOOT.md`	Startup instructions (autopilot notification protocol: WA → Signal)	To change what happens on boot
`HEARTBEAT.md`	Periodic checklist (empty = no heartbeat API calls)	To add/remove periodic tasks
`MEMORY.md`	Curated long-term memory (loaded only in main/direct sessions)	Bot manages this itself
`TOOLS.md`	Contacts, SSH hosts, device nicknames	To add local tool notes
`memory/*.md`	Daily raw logs, topic-specific chat logs	Bot writes automatically

文件	用途	编辑时机
`SOUL.md`	个性：语气、风格（如"不使用破折号，小写随意风格"）	更改机器人说话方式时
`IDENTITY.md`	名称（如Jarvis）、角色类型、表情符号	重新塑造机器人形象时
`USER.md`	所有者信息、偏好	用户上下文变化时
`AGENTS.md`	操作规则：记忆协议、安全设置、群组聊天行为、心跳指令	更改机器人行为时
`BOOT.md`	启动指令（自动操作通知协议：WA → Signal）	更改启动时的行为时
`HEARTBEAT.md`	定期任务清单（空表示跳过心跳API调用）	添加/删除定期任务时
`MEMORY.md`	精选长期记忆（仅在主/直接会话中加载）	机器人会自行管理此文件
`TOOLS.md`	联系人、SSH主机、设备别名	添加本地工具备注时
`memory/*.md`	每日原始日志、特定主题聊天日志	机器人会自动写入

Session JSONL Format

会话JSONL格式

Each

.jsonl

file has one JSON object per line. Types:

type	What
`session`	Session header: id, timestamp, cwd
`message`	Conversation turn: role (user/assistant/toolResult), content, model, usage
`custom`	Metadata: `model-snapshot` , `openclaw.cache-ttl`
`compaction`	Context window was pruned (old messages dropped)
`model_change`	Model was switched mid-session
`thinking_level_change`	Thinking level adjusted

Session index (

sessions.json

) keys:

Pattern:

agent:main:{channel}:{contact}

agent:main:cron:{job-uuid}

Fields:
```
sessionId
```
(UUID = filename),
```
lastChannel
```
,
```
origin.label
```
(human name),
```
origin.from
```
(canonical address),
```
updatedAt
```
(epoch ms),
```
chatType
```
(direct/group)

每个

.jsonl

文件每行包含一个JSON对象。类型如下：

类型	用途
`session`	会话头：ID、时间戳、当前工作目录
`message`	对话回合：角色（user/assistant/toolResult）、内容、模型、使用情况
`custom`	元数据： `model-snapshot` , `openclaw.cache-ttl`
`compaction`	上下文窗口被修剪（旧消息被删除）
`model_change`	会话中途更换了模型
`thinking_level_change`	思考级别已调整

会话索引（

sessions.json

）的键：

格式：

agent:main:{channel}:{contact}

或

agent:main:cron:{job-uuid}

字段：
```
sessionId
```
（UUID = 文件名）、
```
lastChannel
```
、
```
origin.label
```
（人名）、
```
origin.from
```
（标准地址）、
```
updatedAt
```
（毫秒时间戳）、
```
chatType
```
（direct/group）

Gateway Startup Sequence

网关启动序列

Normal startup takes ~3 seconds:

[heartbeat] started
[gateway] listening on ws://127.0.0.1:18789
[browser/service] Browser control service ready
[hooks] loaded 3 internal hook handlers (boot-md, command-logger, session-memory)
[whatsapp] [default] starting provider
[signal] [default] starting provider (http://127.0.0.1:8080)
[telegram] [coder] starting provider
[telegram] [sales] starting provider
[whatsapp] Listening for personal WhatsApp inbound messages.
[signal] signal-cli: Started HTTP server on /127.0.0.1:8080

If any line is missing, that component failed to start. Check

gateway.err.log

正常启动约需3秒：

[heartbeat] started
[gateway] listening on ws://127.0.0.1:18789
[browser/service] Browser control service ready
[hooks] loaded 3 internal hook handlers (boot-md, command-logger, session-memory)
[whatsapp] [default] starting provider
[signal] [default] starting provider (http://127.0.0.1:8080)
[telegram] [coder] starting provider
[telegram] [sales] starting provider
[whatsapp] Listening for personal WhatsApp inbound messages.
[signal] signal-cli: Started HTTP server on /127.0.0.1:8080

如果缺少任何一行，表示该组件启动失败。请检查

gateway.err.log

。

Known Error Patterns

已知错误模式

Error	Meaning	Fix
`Web connection closed (status 408)`	WhatsApp web timeout, auto-retries up to 12x	Usually self-heals. If reaches 12/12, restart gateway
`Signal RPC -1: Failed to send message`	signal-cli daemon lost connection	Restart gateway
`Signal RPC -5: Failed to send message due to rate limiting`	Signal rate limit	Wait and retry, reduce message frequency
`No profile name set` (signal-cli WARN)	Floods logs, harmless	`signal-cli -a +ACCOUNT updateProfile --given-name "Name"`
`Cross-context messaging denied`	Agent tried to send across channels	Not a bug — security guardrail. Message must originate from correct channel session
`getUpdates timed out after 500 seconds`	Telegram bot lost polling connection	Restart gateway
`Unrecognized keys: "token", "username"`	Wrong config keys for Telegram bots	Use `botToken` not `token` in openclaw.json
`RESOURCE_EXHAUSTED` (Gemini 429)	Embedding rate limit	Reduce workspace file churn, or upgrade Gemini quota
`lane wait exceeded`	Agent blocked on long LLM call	Wait, or restart if stuck > 2 min
`embedded run timeout: timeoutMs=600000`	Agent response exceeded 10 min	Break task into smaller pieces
`gateway timeout after 10000ms`	Gateway unreachable during restart window	Cron fired while gateway was down — transient

错误	含义	修复方法
`Web connection closed (status 408)`	WhatsApp网页版超时，自动重试最多12次	通常会自行恢复。如果达到12/12次重试，重启网关
`Signal RPC -1: Failed to send message`	signal-cli守护进程连接丢失	重启网关
`Signal RPC -5: Failed to send message due to rate limiting`	Signal速率限制	等待后重试，降低消息发送频率
`No profile name set` (signal-cli警告)	日志被大量填充，无实际危害	`signal-cli -a +账户 updateProfile --given-name "名称"`
`Cross-context messaging denied`	Agent尝试跨渠道发送消息	这不是bug — 是安全防护机制。消息必须来自正确的渠道会话
`getUpdates timed out after 500 seconds`	Telegram Bot轮询连接丢失	重启网关
`Unrecognized keys: "token", "username"`	Telegram Bot的配置键错误	在openclaw.json中使用 `botToken` 而非 `token`
`RESOURCE_EXHAUSTED` (Gemini 429)	嵌入速率限制	减少工作区文件变动，或升级Gemini配额
`lane wait exceeded`	Agent被长时间LLM调用阻塞	等待，或如果卡住超过2分钟则重启
`embedded run timeout: timeoutMs=600000`	Agent响应超过10分钟限制	将任务拆分为更小的部分
`gateway timeout after 10000ms`	重启窗口期间网关不可达	Cron在网关关闭时触发 — 临时问题

Extending OpenClaw

扩展OpenClaw

OpenClaw has 4 extension layers. Each solves a different problem:

Layer	What	Where	How to add
Skills	Knowledge + workflows the agent loads on demand	`/opt/homebrew/lib/node_modules/openclaw/skills/` or `~/.openclaw/workspace/skills/`	`clawdhub install <slug>` or `npx add-skill <repo>`
Extensions	Custom channel plugins (TypeScript)	`~/.openclaw/extensions/{name}/`	Create `openclaw.plugin.json` + TypeScript source
Channels	Messaging platforms (built-in)	`openclaw.json → channels.` + `plugins.entries.`	Configure in openclaw.json, add credentials
Cron jobs	Scheduled autonomous tasks	`~/.openclaw/cron/jobs.json`	Agent creates them via tool, or edit jobs.json directly

OpenClaw有4个扩展层。每个层解决不同的问题：

层	用途	位置	添加方式
技能	Agent按需加载的知识与工作流	`/opt/homebrew/lib/node_modules/openclaw/skills/` 或 `~/.openclaw/workspace/skills/`	`clawdhub install <slug>` 或 `npx add-skill <repo>`
扩展	自定义渠道插件（TypeScript）	`~/.openclaw/extensions/{name}/`	创建 `openclaw.plugin.json` + TypeScript源码
渠道	内置消息平台	`openclaw.json → channels.` + `plugins.entries.`	在openclaw.json中配置，添加凭证
Cron任务	定时自主任务	`~/.openclaw/cron/jobs.json`	Agent通过工具创建，或直接编辑jobs.json

Skills: ClawdHub Ecosystem

技能：ClawdHub生态系统

Skills are the primary way to extend what the agent knows and can do. They're markdown files with optional scripts/assets that get loaded into context when relevant.

bash

undefined

技能是扩展Agent能力的主要方式。它们是带有可选脚本/资源的markdown文件，在相关时会被加载到上下文中。

bash

undefined

Search for skills (vector search across the registry)

搜索技能（跨注册表的向量搜索）

clawdhub search "postgres optimization" clawdhub search "image generation"

Browse latest skills

浏览最新技能

clawdhub explore

Install a skill

安装技能

clawdhub install supabase-postgres-best-practices clawdhub install nano-banana-pro

Install a specific version

安装特定版本

clawdhub install my-skill --version 1.2.3

List what's installed

列出已安装的技能

clawdhub list

Update all installed skills

更新所有已安装的技能

clawdhub update --all

Update a specific skill

更新特定技能

clawdhub update my-skill clawdhub update my-skill --force # overwrite local changes


**Currently installed skills (bundled with OpenClaw):**

| Category | Skills |
|---|---|
| **Messaging** | discord, slack, imsg, wacli, voice-call |
| **Social/Web** | bird (X/Twitter), blogwatcher, github, trello, notion |
| **Google** | gog, google-workspace-mcp, goplaces, local-places |
| **Media** | nano-banana-pro (Gemini image gen), openai-image-gen, video-frames, gifgrep, pixelation, sag (TTS), openai-whisper, sherpa-onnx-tts, songsee, camsnap |
| **Coding agents** | coding-agent (Codex/Claude Code/Pi), ccbg (background runner), tmux |
| **Productivity** | apple-notes, apple-reminders, bear-notes, things-mac, obsidian, himalaya (email) |
| **Smart home** | openhue (Philips Hue), eightctl (Eight Sleep), sonoscli, blucli (BluOS) |
| **Dev tools** | github, worktree, starter, desktop, supabase-postgres-best-practices, superdesign |
| **Content** | remotion-best-practices, remotion-fastest-tech-stack, humanizer, summarize, market, buildinpublic |
| **Meta** | skill-creator, clawdhub, find-skills, add-skill, model-usage, session-logs, recentplans, canvas |

clawdhub update my-skill clawdhub update my-skill --force # 覆盖本地更改


**当前已安装的技能（与OpenClaw捆绑）：**

| 分类 | 技能 |
|---|---|
| **消息** | discord, slack, imsg, wacli, voice-call |
| **社交/网络** | bird (X/Twitter), blogwatcher, github, trello, notion |
| **Google** | gog, google-workspace-mcp, goplaces, local-places |
| **媒体** | nano-banana-pro (Gemini图像生成), openai-image-gen, video-frames, gifgrep, pixelation, sag (TTS), openai-whisper, sherpa-onnx-tts, songsee, camsnap |
| **编码Agent** | coding-agent (Codex/Claude Code/Pi), ccbg (后台运行器), tmux |
| **生产力** | apple-notes, apple-reminders, bear-notes, things-mac, obsidian, himalaya (邮件) |
| **智能家居** | openhue (Philips Hue), eightctl (Eight Sleep), sonoscli, blucli (BluOS) |
| **开发工具** | github, worktree, starter, desktop, supabase-postgres-best-practices, superdesign |
| **内容** | remotion-best-practices, remotion-fastest-tech-stack, humanizer, summarize, market, buildinpublic |
| **元技能** | skill-creator, clawdhub, find-skills, add-skill, model-usage, session-logs, recentplans, canvas |

Creating Your Own Skill

创建自己的技能

A skill is just a folder with a

SKILL.md

my-skill/
├── SKILL.md              # Required: YAML frontmatter + markdown instructions
├── scripts/              # Optional: executable scripts
├── references/           # Optional: docs loaded on demand
└── assets/               # Optional: templates, images

SKILL.md format:

markdown

---
name: my-skill
description: What this does and WHEN to trigger it. The description is the primary
  trigger — the agent reads this to decide whether to load the full skill.
---

技能只是一个包含

SKILL.md

的文件夹：

my-skill/
├── SKILL.md              # 必填：YAML前置元数据 + markdown指令
├── scripts/              # 可选：可执行脚本
├── references/           # 可选：按需加载的文档
└── assets/               # 可选：模板、图片

SKILL.md格式：

markdown

---
name: my-skill
description: 该技能的用途及触发时机。描述是主要的触发条件 — Agent会读取此内容来决定是否加载完整技能。
---

My Skill

我的技能

Instructions go here. Only loaded AFTER the skill triggers. Keep under 500 lines. Split large content into references/ files.


**Key principle: the context window is a shared resource.** Only include what the agent doesn't already know. Prefer concise examples over verbose explanations.

```bash

指令写在这里。仅在技能触发后加载。内容保持在500行以内。将大内容拆分为references/文件夹中的文件。


**核心原则：上下文窗口是共享资源。** 仅包含Agent不知道的内容。优先使用简洁示例而非冗长解释。

```bash

Publish to ClawdHub

发布到ClawdHub

clawdhub login clawdhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0

clawdhub login clawdhub publish ./my-skill --slug my-skill --name "我的技能" --version 1.0.0

Or publish to GitHub for npx add-skill

或发布到GitHub以使用npx add-skill

(see add-skill skill for details)

（详情请查看add-skill技能）

undefined

undefined

Multi-Agent Orchestration

多Agent编排

OpenClaw can spawn other AI agents (Codex, Claude Code, Pi) as background workers. This is how you run parallel coding tasks, reviews, or any work that benefits from multiple agents.

The pattern:

bash pty:true background:true workdir:/path command:"agent 'task'"

bash

undefined

OpenClaw可以生成其他AI Agent（Codex、Claude Code、Pi）作为后台工作者。这适用于运行并行编码任务、代码审查或任何受益于多Agent协作的工作。

模式：

bash pty:true background:true workdir:/path command:"agent '任务'"

bash

undefined

Spawn Codex to build something (background, auto-approve)

生成Codex来构建项目（后台运行，自动批准）

bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a REST API for todos'"

Returns sessionId for tracking

返回sessionId用于跟踪

Spawn Claude Code on a different task

生成Claude Code处理另一个任务

bash pty:true workdir:~/other-project background:true command:"claude 'Refactor the auth module'"

Monitor all running agents

监控所有运行中的Agent

process action:list

Check output of a specific agent

查看特定Agent的输出

process action:log sessionId:XXX

Send input if agent asks a question

如果Agent提问，发送输入

process action:submit sessionId:XXX data:"yes"

Kill a stuck agent

终止卡住的Agent

process action:kill sessionId:XXX


**Parallel PR reviews:**
```bash

process action:kill sessionId:XXX


**并行PR审查：**
```bash

Fetch all PR refs

获取所有PR引用

git fetch origin '+refs/pull//head:refs/remotes/origin/pr/'

Launch one agent per PR

为每个PR启动一个Agent

bash pty:true workdir:~~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'" bash pty:true workdir:~~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"


**Parallel issue fixing with git worktrees:**
```bash
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

bash pty:true workdir:/tmp/issue-78 background:true command:"codex --yolo 'Fix issue #78: description. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"codex --yolo 'Fix issue #99: description. Commit and push.'"

Auto-notify when agent finishes:

bash

bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Your task.

When completely finished, run: openclaw gateway wake --text \"Done: summary\" --mode now'"


**使用Git工作树并行修复问题：**
```bash
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

bash pty:true workdir:/tmp/issue-78 background:true command:"codex --yolo 'Fix issue #78: 描述。提交并推送。'"
bash pty:true workdir:/tmp/issue-99 background:true command:"codex --yolo 'Fix issue #99: 描述。提交并推送。'"

Agent完成时自动通知：

bash

bash pty:true workdir:~/project background:true command:"codex --yolo exec '你的任务。

完成后，运行：openclaw gateway wake --text \"完成：摘要\" --mode now'"

Adding a New Channel

添加新渠道

Channels are messaging platforms the agent can communicate through. Built-in: WhatsApp, Signal, Telegram, iMessage, Discord, Slack.

Enable a built-in channel:

bash

undefined

渠道是Agent可以用来通信的消息平台。内置渠道：WhatsApp、Signal、Telegram、iMessage、Discord、Slack。

启用内置渠道：

bash

undefined

1. Enable the plugin

1. 启用插件

jq '.plugins.entries.discord.enabled = true' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

2. Add channel config

2. 添加渠道配置

jq '.channels.discord = {enabled: true, dmPolicy: "pairing", groupPolicy: "disabled"}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

3. Add credentials (channel-specific)

3. 添加凭证（渠道特定）

4. Restart gateway

4. 重启网关

openclaw gateway restart


**Build a custom channel extension:**

~/.openclaw/extensions/{name}/ ├── openclaw.plugin.json # {"id": "name", "channels": ["name"], "configSchema": {...}} ├── package.json # Standard npm package ├── index.ts # Entry point └── src/ ├── channel.ts # Inbound message handling + outbound send ├── actions.ts # Tool actions the agent can invoke ├── runtime.ts # Lifecycle: start, stop, health check ├── config-schema.ts # JSON schema for plugin config └── types.ts # TypeScript types


```bash

openclaw gateway restart


**构建自定义渠道扩展：**

~/.openclaw/extensions/{name}/ ├── openclaw.plugin.json # {"id": "name", "channels": ["name"], "configSchema": {...}} ├── package.json # 标准npm包 ├── index.ts # 入口文件 └── src/ ├── channel.ts # 入站消息处理 + 出站发送 ├── actions.ts # Agent可以调用的工具操作 ├── runtime.ts # 生命周期：启动、停止、健康检查 ├── config-schema.ts # 插件配置的JSON schema └── types.ts # TypeScript类型定义


```bash

List installed extensions

列出已安装的扩展

ls ~/.openclaw/extensions/

View extension manifests

查看扩展清单

cat ~/.openclaw/extensions/*/openclaw.plugin.json | jq .

Check extension source files

检查扩展源码文件

find ~/.openclaw/extensions/ -name ".ts" -not -path "/node_modules/*"

undefined

find ~/.openclaw/extensions/ -name ".ts" -not -path "/node_modules/*"

undefined

Cross-Channel Communication

跨渠道通信

The agent can receive on one channel and send on another, but there are guardrails:

bash

undefined

Agent可以在一个渠道接收消息并在另一个渠道发送，但有防护机制：

bash

undefined

Check cross-context settings

检查跨上下文设置

cat ~/.openclaw/openclaw.json | jq '.tools.message.crossContext'

allowAcrossProviders: true = agent CAN send across channels

allowAcrossProviders: true = Agent可以跨渠道发送消息

marker.enabled: false = no "[via Signal]" prefix on cross-channel messages

marker.enabled: false = 跨渠道消息不添加"[via Signal]"前缀

If you see "Cross-context messaging denied" errors:

如果看到"Cross-context messaging denied"错误：

The agent tried to send from a session bound to channel A to channel B.

Agent尝试从绑定到渠道A的会话发送到渠道B。

This is a security feature. To allow it:

这是安全功能。要允许此操作：

jq '.tools.message.crossContext.allowAcrossProviders = true' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json


**BOOT.md notification protocol** (already configured):
The agent receives WhatsApp messages, responds on WhatsApp, then sends a notification summary to Signal. This is the primary cross-channel pattern — autopilot on one channel, control center on another.

jq '.tools.message.crossContext.allowAcrossProviders = true' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json


**BOOT.md通知协议**（已配置）：
Agent接收WhatsApp消息，在WhatsApp上回复，然后将通知摘要发送到Signal。这是主要的跨渠道模式 — 在一个渠道启用自动操作，在另一个渠道作为控制中心。

Canvas: Web UI for Connected Devices

Canvas：连接设备的Web UI

Push HTML/games/dashboards to connected Mac/iOS/Android nodes:

bash

undefined

将HTML/游戏/仪表板推送到连接的Mac/iOS/Android节点：

bash

undefined

Check canvas config

检查Canvas配置

cat ~/.openclaw/openclaw.json | jq '.canvasHost // "not configured"'

cat ~/.openclaw/openclaw.json | jq '.canvasHost // "未配置"'

List connected nodes

列出连接的节点

openclaw nodes list

Present HTML content on a node

在节点上展示HTML内容

canvas action:present node:<node-id> target:http://localhost:18793/moltbot/canvas/my-page.html

Canvas files live in:

Canvas文件位于：

ls ~/.openclaw/canvas/

undefined

ls ~/.openclaw/canvas/

undefined

Voice Calls

语音通话

Initiate phone calls via Twilio/Telnyx/Plivo:

bash

undefined

通过Twilio/Telnyx/Plivo发起电话通话：

bash

undefined

Check if voice-call plugin is enabled

检查voice-call插件是否启用

cat ~/.openclaw/openclaw.json | jq '.plugins.entries["voice-call"] // "not configured"'

cat ~/.openclaw/openclaw.json | jq '.plugins.entries["voice-call"] // "未配置"'

CLI usage

CLI用法

openclaw voicecall call --to "+15555550123" --message "Hello" openclaw voicecall status --call-id <id>

undefined

openclaw voicecall call --to "+15555550123" --message "你好" openclaw voicecall status --call-id <id>

undefined

Cron: Scheduled Autonomous Tasks

Cron：定时自主任务

bash

undefined

bash

undefined

View all jobs

查看所有任务

cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | {name, enabled, schedule: .schedule, channel: .payload.channel, to: .payload.to}'

Job schedule types:

任务调度类型：

"kind": "at", "atMs": <epoch> — one-shot at specific time

"kind": "at", "atMs": <时间戳> — 在特定时间执行一次

"kind": "every", "everyMs": <ms> — recurring interval

"kind": "every", "everyMs": <毫秒> — 按固定间隔重复执行

Job delivery targets:

任务交付目标：

channel + to fields determine where results go (signal, whatsapp, telegram)

channel + to字段决定结果发送到哪里（signal, whatsapp, telegram）

sessionTarget: "isolated" = fresh context each run (no memory of previous runs)

sessionTarget: "isolated" = 每次运行使用全新上下文（不保留之前运行的记忆）

To add a job, the agent creates it via tool, or edit jobs.json:

添加任务：Agent通过工具创建，或直接编辑jobs.json：

See existing jobs as templates in ~/.openclaw/cron/jobs.json

参考~/.openclaw/cron/jobs.json中的现有任务作为模板

---

---

License

许可证

MIT

openclaw-config

Original

Translation

OpenClaw Operations Runbook

OpenClaw 操作手册

Quick Health Check

快速健康检查

File Map

文件结构

Troubleshooting: WhatsApp

故障排查：WhatsApp

"I sent a message but got no reply"

"我发送了消息但没有收到回复"

1. Is the bot actually running?

1. 机器人是否真的在运行？

2. Check for 408 timeout drops (WhatsApp web disconnects frequently)

2. 检查408超时断开（WhatsApp网页版经常断开连接）

If you see "Web connection closed (status 408). Retry 1/12" — this is normal,

如果看到"Web connection closed (status 408). Retry 1/12" — 这是正常现象，

it auto-recovers. But if retries reach 12/12, the session dropped completely.

会自动恢复。但如果重试次数达到12/12，则会话完全断开。

3. Check for cross-context messaging blocks

3. 检查跨上下文消息拦截

Common: "Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal""

常见情况："Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal""

This means the agent was in a Signal session and tried to reply on WhatsApp.

这表示Agent处于Signal会话中，尝试在WhatsApp上回复。

FIX: The message needs to come through in the WhatsApp session context, not Signal.

修复方法：消息需要通过WhatsApp会话上下文发送，而非Signal。

4. Check the session exists for that contact

4. 检查该联系人的会话是否存在

5. Check if the sender is allowed

5. 检查发送者是否被允许

If dmPolicy is "allowlist" and the sender isn't in allowFrom, message is silently dropped.

如果dmPolicy为"allowlist"且发送者不在allowFrom列表中，消息会被静默丢弃。

6. Check if it's a group message (groups are disabled by default)

6. 检查是否为群组消息（默认禁用群组）

"disabled" means ALL group messages are ignored.

"disabled"表示所有群组消息都会被忽略。

7. Check for lane congestion (agent busy with another task)

7. 检查通道拥塞（Agent正忙于其他任务）

If the agent is stuck on a long LLM call, new messages queue up.

如果Agent卡在长时间的LLM调用上，新消息会排队等待。

8. Check for agent run timeout

8. 检查Agent运行超时

Hard limit is 600s (10 min). If the agent's response takes longer, it's killed.

硬限制为600秒（10分钟）。如果Agent响应时间超过此限制，会被终止。

"WhatsApp fully disconnected"

"WhatsApp完全断开连接"

Check credential files exist (should be ~1400 files)

检查凭证文件是否存在（应约有1400个文件）

If 0 files: session was never created or got wiped

如果文件数为0：会话从未创建或已被清除

Fix: re-pair with openclaw configure

修复方法：使用openclaw configure重新配对

Check for QR/pairing events

检查二维码/配对事件

Check for Baileys errors

检查Baileys错误

Nuclear fix: delete credentials and re-pair

终极修复：删除凭证并重新配对

rm -rf ~/.openclaw/credentials/whatsapp/default/

rm -rf ~/.openclaw/credentials/whatsapp/default/

openclaw configure

openclaw configure

Troubleshooting: Telegram

故障排查：Telegram

"Bots have issues / forget things"

"Bot出现问题/忘记内容"

1. Check for config validation errors (THE COMMON ONE)

1. 检查配置验证错误（最常见）

Known issue: the keys "token" and "username" under accounts are not recognized.

已知问题：accounts下的"token"和"username"键不被识别。

The correct field is "botToken", not "token".

正确的字段是"botToken"，而非"token"。

2. Check the actual config

2. 检查实际配置

Verify each bot has "botToken" (not "token") and "name" fields.

验证每个Bot都有"botToken"（而非"token"）和"name"字段。

3. Check polling status — bots die after getUpdates timeout

Fix: re-pair with
`openclaw configure`

修复方法：使用
`openclaw configure`
重新配对

Fix: restart gateway —
`openclaw gateway restart`

修复方法：重启网关 —
`openclaw gateway restart`