OpenClaw 实战 11｜最佳实践：10 条从真实翻车提炼的 SOP + 推送二次确认硬规则原创

# 最佳实践：10 条从真实翻车提炼的 SOP + 推送二次确认硬规则

这一篇是整个 OpenClaw 系列的收尾——把前 10 篇里每个真实翻车，压成 10 条能直接落地的 SOP。每条都对应一个真实事故，每条都能用一句命令或一段配置兑现。

一句话总纲：OpenClaw 最佳实践 = "翻车 → 沉淀 SOP → 写进 AGENTS.md / 自动检查"的闭环。没有真实翻车背书的 SOP 都是空话。

# §1 那个没问就 push 的下午

我让 OpenClaw 帮我把一篇博客脱敏后提交。它干得很漂亮：读文件 → grep 敏感词 → 替换占位符 → git add → git commit，commit message 都写得很规范。然后——它直接 git push origin master 了，没问我。

问题是脱敏漏了一处（frontmatter 里一行凭证），等 Cloudflare Pages 触发构建、我才发现凭证已经公开。rotate 是来得及的，但那 7 分钟的窗口本不该存在。

根因不在脱敏，在 Agent 默认会"一气呵成"地执行你给的链式任务，包括最后那个不可逆的 push。这就是本文最硬的一条 SOP（SOP-10）：不可逆操作必须人类把关。下面 10 条，从这里展开。

# §2 三条贯穿全篇的心法

Token / 凭证单一来源——任何密钥只在一个地方存，所有引用点都从那里读。
日志归因必闭环——"看到日志在动" ≠ "功能在工作"，必须触发行为后看指标变化。
不可逆操作必确认——push / rm / restart / rotate 这 4 类，默认不让 Agent 自动执行。

# §3 10 条实战 SOP

# SOP-1：分清"热重载"和"必须重启"

事故：改了 openclaw.json 的 provider，supervisorctl status 显示 RUNNING，但新配置没生效、CLI 连不上——以为热重载，其实这类要重启。

规则：看你改什么——

热重载（不重启）：workspace markdown（AGENTS.md / HEARTBEAT.md / MEMORY.md）、plugins.entries 插件配置（如 dreaming 的 model）。
必须重启：gateway、models.providers、channel、TTS。

# 容器（supervisor）：改完 provider/gateway/TTS 后
supervisorctl reread && supervisorctl update && supervisorctl restart openclaw
# 裸机（systemd）：
systemctl --user daemon-reload && systemctl --user restart openclaw-gateway
# 之后看应用层 ready 日志，别只看进程状态

1
2
3
4
5

# SOP-2：Token / 凭证单一来源

事故：OPENCLAW_GATEWAY_TOKEN（env）和 gateway.auth.token（config）不一致 → CLI 报 unauthorized，Telegram 走降级轮询还能回消息（假象）。

规则：config 只引用 env，不写明文；API key 留在 agent sqlite，不往 openclaw.json 抄。

openclaw config set gateway.auth.token '${OPENCLAW_GATEWAY_TOKEN}'
# 最终 openclaw.json 里是： "token": "${OPENCLAW_GATEWAY_TOKEN}"

1
2

校验一致性（注意 config 读出来是脱敏占位，要读进程 env 比对）：

HASH_ENV=$(tr '\0' '\n' < /proc/$(pgrep -f openclaw-gateway)/environ | grep OPENCLAW_GATEWAY_TOKEN | cut -d= -f2 | sha256sum)
# 与 .env / supervisor conf 里的值对比 sha256

1
2

# SOP-3：日志归因闭环（触发-观测-计数）

事故：看到本地 TTS 服务 index-tts2（:8081）日志在刷 POST /v1/audio/speech，断定 Agent 在用它。错——那是 Kong 转发给别的服务的流量；Nova 实际用的是另一个自建 TTS（CosyVoice，:8082）。

规则：任何"日志显示 X 在工作"的结论，必须触发用户行为 → 看目标服务计数变化来证实。

before=$(grep -c "POST /v1/audio/speech" /workspace/index-tts2/service.log)
# …手动让 Agent 发一次语音…
after=$(grep -c "POST /v1/audio/speech" /workspace/index-tts2/service.log)
[ "$before" = "$after" ] && echo "index-tts2 没被调用（计数没变）"

1
2
3
4

# SOP-4：操作前先判定部署形态

事故：在某实例上跑 systemctl --user status openclaw-gateway 报 Unit not found，以为服务挂了、瞎改 5 处配置。其实那台是容器、用 supervisor 管。

规则：OpenClaw 有两套独立部署，命令不通用，动手前先判定：

部署	进程管理	重启命令	SSH
海外容器（OpenClaw 运行时容器）	supervisor	`sudo supervisorctl restart openclaw`	端口直落容器内
家用 NAS（裸机）	user systemd	`systemctl --user restart openclaw-gateway`	标准 22

# 黄金判定：哪个能成，就用哪套命令
ssh <host> "supervisorctl status openclaw 2>/dev/null || systemctl --user status openclaw-gateway"

1
2

⚠️ 两套部署各自一份 ~/.openclaw、各自的 provider/模型，互不相干。别把一套的请求发去另一套——那是真实踩过的归因错误。

# SOP-5：把行为约束写进 `AGENTS.md`（不是某份"人格文件"）

事故：Agent 截图后装懂、装了 memory-wiki 没读文档误判、凭证差点进 git——这些"默认行为不收敛"的问题，都需要在 OpenClaw 真实的指令文件 AGENTS.md 里显式写死边界。

澄清：OpenClaw 的工作区指令文件是 AGENTS.md（外加 HEARTBEAT.md 等）。网上流传的 "SOUL.md / IDENTITY.md / USER.md 五件套"是别的框架的概念，OpenClaw 没有——别照着创建一堆没人读的文件。

规则：AGENTS.md 至少写清 4 类约束：

## 行为边界（写进 AGENTS.md）
1. 能力诚实：工具失败（如 model does not support images）必须如实说"我做不到"，禁止脑补
2. 不可逆操作：push / rm -rf / 重启生产 / rotate 密钥，必须先问，不得自动执行
3. 凭证：只走 env / 600 文件，禁止写进任何 markdown / 对话 / git
4. 多环境：动手前先判定部署形态（supervisor vs systemd），远程命令先 export PATH

1
2
3
4
5

改完 AGENTS.md 无需重启（workspace 文件运行时动态读）。

# SOP-6：凭证 env 注入 + 600 + 不进 git

事故：装 freshrss-reader 时把 API 密码写进 skill 目录提交，进了 git 历史。

规则：

mkdir -p ~/.openclaw/secrets && chmod 700 ~/.openclaw/secrets
printf '%s' '<secret>' > ~/.openclaw/secrets/freshrss.pwd && chmod 600 ~/.openclaw/secrets/freshrss.pwd
printf '%s\n' '.openclaw/secrets/' '*.pwd' '*.key' >> ~/.gitignore
export FRESHRSS_API_PASSWORD=$(cat ~/.openclaw/secrets/freshrss.pwd)   # skill 里只引用变量

1
2
3
4

发布前扫一遍明文凭证（无输出才算过）：

grep -rnE '(api[_-]?password|secret|token)\s*[:=]\s*["'\'']?[A-Za-z0-9]{8,}' ~/.openclaw/workspace/skills/ 2>/dev/null

# SOP-7：装插件先 help/读文档再 enable

事故：openclaw plugins enable memory-wiki 后看到 wiki status 报"9 个报告"全是空的，误以为故障。其实那是监控仪表盘，ingest 内容前本就空。

规则：装任何插件先理解默认状态再 enable。

openclaw wiki status     # 0 pages / 9 reports：pages=用户内容(空,正常)，reports=监控仪表盘
# memory-wiki 默认 isolated 模式；3 种模式 isolated / bridge / unsafe-local

1
2

# SOP-8：多模态靠配 `imageModel`，不是换主模型

事故：主模型 qwen3-coder 不吃图片，让它看截图就脑补。

规则：OpenClaw 有模型角色——imageModel 是 image 工具的后端，主模型即便非视觉，配好 imageModel 就能借它读图：

{ "agents": { "defaults": { "imageModel": { "primary": "qwen3-vl-235b" } } } }

STT 是另一回事：sttModel 在 streaming.providers.<p>.model，要独立的 /v1/audio/transcriptions 端点，别套用识图的写法。

# SOP-9：多网卡环境 Tunnel 目标验证可达

事故：Cloudflare Tunnel 报 connection refused，后端却健康——OVS 桥接层让 Tunnel 指向的内网 IP 不可达。

规则：多网卡环境分别测内网/公网 IP，Tunnel 指向真正可达的那个。

curl -m 3 http://<内网IP>:3210; curl -m 3 http://<公网IP>:3210
ss -tlnp | grep 3210          # 确认实际监听在哪个地址
# 把 cloudflared ingress 的 service 改成可达 IP

1
2
3

# SOP-10：Skill 安装走 ClawHub + 启用前校验

事故：手动塞了个 skill，YAML frontmatter 缺 --- 分隔，OpenClaw 不识别。

规则：优先用 ClawHub 装（OpenClaw 的 skill 注册表），启用前跑校验。

# 装：自带 57 个 skill，不够再从 ClawHub 装
npx clawhub install <skill-name>          # → ~/.openclaw/workspace/skills/<name>
# 启用机制：装好 + skills.entries.<name>.enabled=true + 重启
# 校验 frontmatter（用内置 skill-creator 的校验脚本）
python3 ~/.openclaw/workspace/skills/skill-creator/scripts/quick_validate.py ~/.openclaw/workspace/skills/<name>/

1
2
3
4
5

frontmatter 必填 name + description（Agent 靠 description 判断要不要加载，写明确触发场景）。

# SOP-11：进程活着 ≠ 工作正常（4 通道验活）

事故：supervisorctl status 显示 RUNNING，但 CLI 全挂、Telegram 只是降级轮询。

规则：判断 Agent 真活着，4 通道 ping + 看应用层 ready 日志，不看进程状态。

openclaw cron list                                  # CLI 控制面通不通
curl -sf http://localhost:18789/health              # gateway 在听吗
# Telegram 发一句，看是否真回（不是降级模板）
supervisorctl tail -f openclaw | grep -i ready       # 应用层就绪
# 死循环（tool policy 抖动）→ 直接 restart，别等 Agent 自愈

1
2
3
4
5

# SOP-12：push 之前必须人类二次确认

事故：§1——Agent 自动 push，凭证短暂公开。

规则：push / rm -rf / 重启生产 / rotate 这 4 类不可逆操作，Agent 不得自动执行，写进 AGENTS.md 硬规则：

## 不可逆操作铁律（AGENTS.md）
以下绝不自动执行，必须先把变更摘要给我、等我点头：
1. git push / git push --force
2. rm -rf / 删文件 / 删库
3. 重启生产 gateway / 宿主机
4. 凭证 rotate / 密钥重生成

1
2
3
4
5
6

推送前 Agent 应当先给出可复核的摘要：

⚠️ 即将 git push origin master
- N files changed
- 敏感词扫描: ✅ CLEAN
- 是否确认？[y/N]

1
2
3
4

这正是本博客自己的发布流程：脱敏 → scan_leaks.py 必须 CLEAN → 人工确认 → push → 轮询线上。SOP-12 不是理论，是写这篇文章时正在用的规矩。

# §4 一张可跑的自检清单

#!/bin/bash
# openclaw_sop_check.sh —— 10 条 SOP 的快速自检（节选关键项）
echo "SOP-2 Token 单一来源:"
grep -q '${OPENCLAW_GATEWAY_TOKEN}' ~/.openclaw/openclaw.json && echo "  ✅ config 引用 env" || echo "  ❌ 可能写了明文"

echo "SOP-4 部署形态:"
ssh_cmd="supervisorctl status openclaw 2>/dev/null || systemctl --user status openclaw-gateway"
echo "  判定命令: $ssh_cmd"

echo "SOP-5/12 AGENTS.md 行为约束:"
for k in "不可逆操作" "凭证" "能力诚实"; do
  grep -q "$k" ~/.openclaw/workspace/AGENTS.md && echo "  ✅ $k" || echo "  ❌ 缺: $k"
done

echo "SOP-6 凭证卫生:"
stat -c '%a' ~/.openclaw/secrets 2>/dev/null | grep -q 700 && echo "  ✅ secrets 700" || echo "  ❌ secrets 权限"
grep -rqnE '(api[_-]?password|secret)\s*[:=]\s*["'\'']?[A-Za-z0-9]{8,}' ~/.openclaw/workspace/skills/ 2>/dev/null \
  && echo "  ❌ skills 里有明文凭证" || echo "  ✅ skills 无明文凭证"

echo "SOP-11 验活:"
curl -sf http://localhost:18789/health >/dev/null && echo "  ✅ gateway 健康" || echo "  ❌ gateway 不通"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# §5 复用规则（一句话带走）

OpenClaw 的最佳实践不是一份"宪法文件"，是 10 条带真实事故背书的 SOP——其中最该刻进 AGENTS.md 的是：不可逆操作，人类把关。

展开 3 条：

改配置先分清热重载 vs 重启（SOP-1），Token 单一来源（SOP-2），日志归因闭环（SOP-3）。
行为边界写进 AGENTS.md（SOP-5/12），凭证只进 env/600/不进 git（SOP-6）。
判定部署形态再动手（SOP-4），进程 RUNNING 不等于工作正常（SOP-11）。

# §6 系列收尾

OpenClaw 实战系列到这里告一段落（01 总览 → 11）。一句话串起来：OpenClaw 是一个 config 驱动、带自治后台、靠 gateway scope/token 守边界的 Agent 工作区——把它当"数字员工"养，而不是"装个软件"。后续如有新踩坑，继续往这个系列里补。

# §7 Agent 可直接解析的元数据块

{
  "_meta": {
    "doc_version": "2026-06-27",
    "article_id": "openclaw-11-best-practices",
    "profile_context": "any",
    "estimated_read_time": "14min"
  },
  "ten_sops": {
    "SOP-1": "分清热重载(workspace md/插件配置) vs 必须重启(gateway/provider/channel/TTS)",
    "SOP-2": "Token/凭证单一来源：config 用 ${ENV} 引用，key 留 sqlite",
    "SOP-3": "日志归因闭环：触发-观测-计数，'日志在动'≠'功能在工作'",
    "SOP-4": "操作前判定部署形态：容器+supervisor vs 裸机+systemd，命令不通用",
    "SOP-5": "行为约束写进真实的 AGENTS.md（不是 SOUL.md 五件套）",
    "SOP-6": "凭证 env 注入 + 600 + 不进 git，push 前扫明文",
    "SOP-7": "装插件先理解默认状态再 enable（memory-wiki 9 报告=仪表盘非故障）",
    "SOP-8": "多模态靠配 imageModel，不是换主模型；STT 走 streaming.providers",
    "SOP-9": "多网卡 Tunnel 目标验证可达",
    "SOP-10": "skill 走 ClawHub(npx clawhub install) + quick_validate 校验",
    "SOP-11": "进程 RUNNING≠工作正常，4 通道验活 + 看 ready 日志",
    "SOP-12": "push/rm/restart/rotate 必须人类二次确认，写进 AGENTS.md"
  },
  "irreversible_operations": ["git_push", "rm_rf", "restart_prod", "credential_rotate"],
  "real_instruction_file": "~/.openclaw/workspace/AGENTS.md（OpenClaw 没有 SOUL.md/IDENTITY.md/USER.md）",
  "verification": {
    "sop_check": "bash openclaw_sop_check.sh",
    "token_single_source": "grep '${OPENCLAW_GATEWAY_TOKEN}' openclaw.json",
    "credential_scan": "grep -rnE '(api_password|secret)[:=]' ~/.openclaw/workspace/skills/",
    "topology": "supervisorctl status openclaw || systemctl --user status openclaw-gateway"
  },
  "reusable_rule": "最佳实践不是宪法文件，是 10 条带事故背书的 SOP；最该刻进 AGENTS.md 的是：不可逆操作人类把关"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

AI Agent 使用指南：

当用户说"push / 删东西 / 重启生产" → SOP-12：先给摘要、等确认，不自动执行
当用户说"改了配置没生效" → SOP-1：分清该热重载还是该重启
当用户说"装 skill" → SOP-10：ClawHub + quick_validate
当用户说"两套 OpenClaw 搞混了" → SOP-4：先判定 supervisor vs systemd
当用户说"进程 RUNNING 但不正常" → SOP-11：4 通道验活
当用户说"要写 AGENTS.md / 问要不要建 SOUL.md" → SOP-5：OpenClaw 只有 AGENTS.md，行为约束写这里

#OpenClaw #AI Agent #最佳实践 #SOP #推送确认 #多环境隔离 #凭证管理

上次更新: 6/28/2026

← OpenClaw 实战 10｜扩展开发：Skill / Tool / Plugin 区分 + 完整安装流程 + 链路证伪调优 Hermes Agent 概述→

OpenClaw 实战 11｜最佳实践：10 条从真实翻车提炼的 SOP + 推送二次确认硬规则原创

# 最佳实践：10 条从真实翻车提炼的 SOP + 推送二次确认硬规则

# §1 那个没问就 push 的下午

# §2 三条贯穿全篇的心法

# §3 10 条实战 SOP

# SOP-1：分清"热重载"和"必须重启"

# SOP-2：Token / 凭证单一来源

# SOP-3：日志归因闭环（触发-观测-计数）

# SOP-4：操作前先判定部署形态

# SOP-5：把行为约束写进 AGENTS.md（不是某份"人格文件"）

# SOP-6：凭证 env 注入 + 600 + 不进 git

# SOP-7：装插件先 help/读文档再 enable

# SOP-8：多模态靠配 imageModel，不是换主模型

# SOP-9：多网卡环境 Tunnel 目标验证可达

# SOP-10：Skill 安装走 ClawHub + 启用前校验

# SOP-11：进程活着 ≠ 工作正常（4 通道验活）

# SOP-12：push 之前必须人类二次确认

# §4 一张可跑的自检清单

# §5 复用规则（一句话带走）

# §6 系列收尾

# §7 Agent 可直接解析的元数据块

# SOP-5：把行为约束写进 `AGENTS.md`（不是某份"人格文件"）

# SOP-8：多模态靠配 `imageModel`，不是换主模型