Openclaw Config

文件映射

~/.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/                       # 代理工作区 (git 追踪)
│   ├── SOUL.md                      # 个性、写作风格、语气规则
│   ├── IDENTITY.md                  # 名称、生物类型、氛围
│   ├── USER.md                      # 所有者上下文和偏好
│   ├── AGENTS.md                    # 会话行为、内存规则、安全
│   ├── BOOT.md                      # 启动说明 (自动驾驶通知协议)
│   ├── HEARTBEAT.md                 # 定期检查表 (空 = 跳过心跳)
│   ├── MEMORY.md                    # 精选长期记忆 (仅主会话)
│   ├── TOOLS.md                     # 联系人、SSH 主机、设备昵称
│   ├── memory/                      # 每日日志: YYYY-MM-DD.md, topic-chat.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 # 机器人令牌 (每个机器人账户一个)
│   └── 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              # 子代理执行日志
├── canvas/index.html                # Web Canvas UI
└── telegram/
    ├── update-offset-coder.json     # {"lastUpdateId": N} — Telegram 轮询游标
    └── update-offset-sales.json     # 重置为 0 以重放丢失的消息

故障排除：WhatsApp

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

这是第一个要检查的问题。消息已到达，但机器人没有响应。按此顺序检查：

# 1. 机器人是否真的在运行？
grep -i "whatsapp.*starting\|whatsapp.*listening" ~/.openclaw/logs/gateway.log | tail -5

# 2. 检查 408 超时断开 (WhatsApp 网络经常断开)
grep -i "408\|499\|retry" ~/.openclaw/logs/gateway.err.log | tail -10
# 如果看到 "Web connection closed (status 408). Retry 1/12" — 这是正常的，
# 它会自动恢复。但如果重试达到 12/12，会话就完全断开了。

# 3. 检查跨上下文消息阻止
grep -i "cross-context.*denied" ~/.openclaw/logs/gateway.err.log | tail -10
# 常见情况: "Cross-context messaging denied: action=send target provider "whatsapp" while bound to "signal""
# 这意味着代理在 Signal 会话中，却尝试在 WhatsApp 上回复。
# 修复: 消息需要在 WhatsApp 会话上下文中发送，而不是 Signal。

# 4. 检查该联系人是否存在会话
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("whatsapp")) | "\(.key) | \(.value.origin.label // "?")"'

# 5. 检查发送者是否被允许
cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp | {dmPolicy, allowFrom, selfChatMode, groupPolicy}'
# 如果 dmPolicy 是 "allowlist" 且发送者不在 allowFrom 中，消息会被静默丢弃。

# 6. 检查是否是群消息 (群聊默认禁用)
cat ~/.openclaw/openclaw.json | jq '.channels.whatsapp.groupPolicy'
# "disabled" 意味着所有群消息都被忽略。

# 7. 检查通道拥堵 (代理正忙于其他任务)
grep "lane wait exceeded" ~/.openclaw/logs/gateway.err.log | tail -5
# 如果代理卡在长时间的 LLM 调用中，新消息会排队。

# 8. 检查代理运行超时
grep "embedded run timeout" ~/.openclaw/logs/gateway.err.log | tail -5
# 硬限制是 600 秒 (10 分钟)。如果代理响应时间超过此限制，会被强制终止。

"WhatsApp 完全断开连接"

# 检查凭证文件是否存在 (应该约 1400 个文件)
ls ~/.openclaw/credentials/whatsapp/default/ | wc -l

# 如果 0 个文件: 会话从未创建或被清除
# 修复: 通过 `openclaw configure` 重新配对

# 检查 QR/配对事件
grep -i "pair\|link\|qr\|scan\|logged out" ~/.openclaw/logs/gateway.log | tail -10

# 检查 Baileys 错误
grep -i "baileys\|DisconnectReason\|logout\|stream:error" ~/.openclaw/logs/gateway.err.log | tail -20

# 终极修复: 删除凭证并重新配对
# rm -rf ~/.openclaw/credentials/whatsapp/default/
# openclaw configure

故障排除：电报

"机器人有问题/忘记事情"

两个看起来相同但独立的问题：

# 1. 检查配置验证错误 (最常见的)
grep -i "telegram.*unrecognized\|telegram.*invalid\|telegram.*policy" ~/.openclaw/logs/gateway.err.log | tail -10
# 已知问题: accounts 下的 "token" 和 "username" 键不被识别。
# 正确的字段是 "botToken"，不是 "token"。

# 2. 检查实际配置
cat ~/.openclaw/openclaw.json | jq '.channels.telegram'
# 验证每个机器人有 "botToken" (不是 "token") 和 "name" 字段。

# 3. 检查轮询状态 — 机器人在 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"
# 这意味着机器人失去了与 Telegram API 的连接并停止监听。
# 修复: 重启网关 — `openclaw gateway restart`

# 4. 检查轮询偏移 (如果机器人"忘记"或重放旧消息)
cat ~/.openclaw/telegram/update-offset-coder.json
cat ~/.openclaw/telegram/update-offset-sales.json
# 如果 lastUpdateId 卡住或为 0，机器人会重新处理旧消息。
# 跳到最新消息: 网关重启时会自动设置。

# 5. 检查两个机器人是否都在启动
grep -i "telegram.*starting\|telegram.*coder\|telegram.*sales" ~/.openclaw/logs/gateway.log | tail -10

# 6. "机器人忘记" — 这通常是会话问题，不是 Telegram 问题
# 每个 Telegram 用户在 sessions.json 中都有自己的会话。
# 检查会话是否存在:
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.key | test("telegram")) | "\(.key) | \(.value.origin.label // "?")"'

# 7. 检查是否发生了压缩 (上下文窗口被修剪 = "忘记")
SESS_ID="粘贴会话-id"
grep '"compaction"' ~/.openclaw/agents/main/sessions/$SESS_ID.jsonl | wc -l
# 如果压缩计数 > 0，旧消息已从上下文中修剪。
# 代理的压缩模式是:
cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'

Telegram 配置修复模板

# 正确的 Telegram 配置结构:
cat ~/.openclaw/openclaw.json | jq '.channels.telegram = {
  "enabled": true,
  "accounts": {
    "coder": {
      "name": "机器人显示名称",
      "enabled": true,
      "botToken": "你的机器人令牌"
    },
    "sales": {
      "name": "销售机器人名称",
      "enabled": true,
      "botToken": "你的机器人令牌"
    }
  },
  "dmPolicy": "pairing",
  "groupPolicy": "disabled"
}' > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

故障排除：信号

"信号 RPC 发送消息失败"

这会阻止 cron 作业和跨通道通知。

# 1. 检查 signal-cli 进程是否存活
ps aux | grep "[s]ignal-cli"

# 2. 检查 RPC 端点
grep -i "signal.*starting\|signal.*8080\|signal.*rpc" ~/.openclaw/logs/gateway.log | tail -10
# 应该看到: "[signal] [default] starting provider (http://127.0.0.1:8080)"

# 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 内部数据库问题
# "SSE stream error: TypeError: terminated" = 与 signal-cli 守护进程失去连接

# 4. 检查速率限制
grep -i "signal.*rate" ~/.openclaw/logs/gateway.err.log | tail -5
# "Signal RPC -5: Failed to send message due to rate limiting"

# 5. 检查目标格式是否正确
grep -i "unknown target" ~/.openclaw/logs/gateway.err.log | tail -5
# "Unknown target "adi" for Signal. Hint: <E.164|uuid:ID|...>"
# 代理必须使用电话号码 (+1...) 或 uuid: 格式，而不是名称。

# 6. 修复个人资料名称警告垃圾邮件
grep -c "No profile name set" ~/.openclaw/logs/gateway.err.log
# 如果计数很高: 运行 signal-cli updateProfile 设置名称

# 7. 直接测试 signal-cli
ACCT=$(cat ~/.openclaw/openclaw.json | jq -r '.channels.signal.account')
echo "Account: $ACCT"
# signal-cli -a $ACCT send -m "test" +目标号码

# 8. 检查 signal-cli 守护进程是否需要重启
# 网关将 signal-cli 作为子进程管理。
# 重启整个网关: openclaw gateway restart

故障排除：Cron 作业

# 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. 失败的任务及错误详情
cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | select(.state.lastStatus == "error") | {name, error: .state.lastError, lastRun: (.state.lastRunAtMs | . / 1000 | todate), id}'

# 3. 读取失败任务的实际运行日志
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. 常见 cron 失败原因:
#    - "Signal RPC -1" → Signal 守护进程宕机，见上方 Signal 部分
#    - "gateway timeout after 10000ms" → cron 触发时网关正在重启
#    - "Brave Search 429" → 免费套餐速率限制 (2000 次请求/月)
#    - "embedded run timeout" → 任务运行超过 600 秒

# 5. 下次计划运行时间
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | select(.enabled) | "\(.name): \((.state.nextRunAtMs // 0) | . / 1000 | todate)"'

# 6. 临时禁用故障任务
cat ~/.openclaw/cron/jobs.json | jq '(.jobs[] | select(.name == "任务名称")).enabled = false' > /tmp/cron.json && mv /tmp/cron.json ~/.openclaw/cron/jobs.json

故障排除：内存/"它忘记了"

记忆系统有 3 层。当代理"忘记"时，其中之一就坏了：

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

# 检查会话的压缩次数 (压缩 = 旧消息被修剪)
grep -c '"compaction"' ~/.openclaw/agents/main/sessions/SESSION_ID.jsonl
# 7 次压缩 = 代理已经"忘记"最早的消息 7 次。

# 检查压缩模式
cat ~/.openclaw/openclaw.json | jq '.agents.defaults.compaction'
# "safeguard" = 仅在接近上下文限制时压缩

第 2 层：工作区内存文件

# 存在哪些每日内存文件
ls -la ~/.openclaw/workspace/memory/

# MEMORY.md 中的内容 (长期精选)
cat ~/.openclaw/workspace/MEMORY.md

# 在内存文件中搜索特定内容
grep -ri "关键词" ~/.openclaw/workspace/memory/

第 3 层：向量内存数据库（SQLite + Gemini 嵌入）

# 哪些文件被索引
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT path, size, datetime(mtime/1000, 'unixepoch') as modified FROM files;"

# 存在多少文本块 (文本片段)
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT COUNT(*) FROM chunks;"

# 通过文本搜索文本块 (FTS5 全文搜索)
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT substr(text, 1, 200) FROM chunks_fts WHERE chunks_fts MATCH '关键词' LIMIT 5;"

# 检查嵌入配置
sqlite3 ~/.openclaw/memory/main.sqlite "SELECT value FROM meta WHERE key='memory_index_meta_v1';" | python3 -m json.tool

# 检查 Gemini 嵌入速率限制 (会破坏索引)
grep -i "gemini.*batch.*failed\|RESOURCE_EXHAUSTED\|429" ~/.openclaw/logs/gateway.err.log | tail -10
# "embeddings: gemini batch failed (2/2); disabling batch" = 索引降级

# 重建内存索引 (重新索引所有工作区文件)
# 删除数据库并重启网关 — 它会重建:
# rm ~/.openclaw/memory/main.sqlite && openclaw gateway restart

搜索会话

查找某人的对话

# 按名称搜索会话索引 (不区分大小写)
cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.value.origin.label // "" | test("名称"; "i")) | "\(.value.sessionId) | \(.value.lastChannel) | \(.value.origin.label)"'

按频道查找会话

cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r 'to_entries[] | select(.value.lastChannel == "whatsapp") | "\(.value.sessionId) | \(.value.origin.label // .key)"'
# 将 "whatsapp" 替换为: signal、telegram，或检查 .key 获取 cron 会话

最近的会话

cat ~/.openclaw/agents/main/sessions/sessions.json | jq -r '[to_entries[] | {id: .value.sessionId, updated: .value.updatedAt, label: (.value.origin.label // .key), ch: (.value.lastChannel // "cron")}] | sort_by(.updated) | reverse | .[:10][] | "\(.updated | . / 1000 | todate) | \(.ch) | \(.label)"'

在所有会话中搜索消息内容

# 快速: 查找包含关键词的会话文件
grep -l "关键词" ~/.openclaw/agents/main/sessions/*.jsonl

# 详细: 显示匹配的消息及时间戳
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

阅读特定的会话记录

# 会话的最后 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
"

配置编辑

安全编辑模式

始终：备份、使用 jq 编辑、重新启动。

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

常见编辑

# 将 WhatsApp 切换为允许列表
jq '.channels.whatsapp.dmPolicy = "allowlist" | .channels.whatsapp.allowFrom = ["+1XXXXXXXXXX"]' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# 启用 WhatsApp 自动驾驶 (机器人像你一样回复所有人)
jq '.channels.whatsapp += {dmPolicy: "open", selfChatMode: false, allowFrom: ["*"]}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# 添加号码到 Signal 允许列表
jq '.channels.signal.allowFrom += ["+1XXXXXXXXXX"]' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

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

# 设置并发
jq '.agents.defaults.maxConcurrent = 10 | .agents.defaults.subagents.maxConcurrent = 10' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

# 禁用插件
jq '.plugins.entries.imessage.enabled = false' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json

从备份恢复

# 最新备份
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json

# 按日期列出所有备份
ls -lt ~/.openclaw/openclaw.json.bak*

# 重启前验证 JSON
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null && echo "OK" || echo "损坏"

# 终极重置
openclaw configure

通道安全模式

检查当前的安全状况

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

工作区文件

会话 JSONL 格式

每个 .jsonl 文件每行都有一个 JSON 对象。类型：

会话索引 (sessions.json) 键：

• 模式：agent:main:{channel}:{contact} 或 agent:main:cron:{job-uuid}
• 字段：sessionId (UUID = 文件名)、lastChannel、origin.label (人名)、origin.from (规范地址)、updatedAt (纪元毫秒)、chatType (直接/组)

网关启动顺序

正常启动大约需要 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。

已知错误模式

扩展 OpenClaw

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

技能：ClawdHub 生态系统

技能是扩展代理知识和能力的主要方式。它们是带有可选脚本/资源的 Markdown 文件，在相关时加载到上下文中。

# 搜索技能 (跨注册表向量搜索)
clawdhub search "postgres optimization"
clawdhub search "image generation"

# 浏览最新技能
clawdhub explore

# 安装技能
clawdhub install supabase-postgres-best-practices
clawdhub install nano-banana-pro

# 安装特定版本
clawdhub install my-skill --version 1.2.3

# 列出已安装的技能
clawdhub list

# 更新所有已安装的技能
clawdhub update --all

# 更新特定技能
clawdhub update my-skill
clawdhub update my-skill --force  # 覆盖本地更改

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

创建你自己的技能

技能只是一个带有 SKILL.md 的文件夹：

my-skill/
├── SKILL.md              # 必需: YAML frontmatter + Markdown 指令
├── scripts/              # 可选: 可执行脚本
├── references/           # 可选: 按需加载的文档
└── assets/               # 可选: 模板、图片

SKILL.md 格式：

---