Openclaw Config Audit
Audit and harden a local OpenClaw configuration: inventory (doctor, status, config validate, security audit, secrets audit, automations list), triage by severity x interaction impact, then apply batch fixes with readback. Produces an evidence-backed issue list.
OpenClaw 配置体检与加固
用于:主人说「审计/体检一下 OpenClaw 配置,看有没有问题、有没有可优化空间」;要加固本机 exec 权限、会话存储维护、~/.openclaw 状态目录;或读过体检报告后说「按顺序全修」。
产出:带证据的问题清单(严重度 × 是否改变交互)+ 每项改前/改后回读值 + 备份路径 + 未修项与出路 + 重启项(交主人)。
(provider/模型不可用与默认模型 → openclaw-model-health-triage;删 provider → openclaw-provider-removal;删插件/通道 → openclaw-plugin-removal;升级后的漂移 → openclaw-upgrade-impact-review;工作区文件整理 → workspace-declutter(本 skill 只做 ~/.openclaw 配置与状态面);字段/默认值取证 → openclaw-docs-grounding;OpenViking 记忆空白 / 没抽取 / 召回不到 → openviking-memory-triage;会话库 / 状态目录体量膨胀 → references/会话库膨胀分诊.md;网关运行时变慢 / 内存膨胀 / 越用越慢 / OOM 风险 / 每轮耗时高 → openclaw-gateway-performance-triage(那是运行时面:cgroup 口径、worker 泄漏、会话数驱动的 O(n) 投影开销、journalctl 信号,不在配置盘点范围内)。)
前置事实(实测,勿重踩)
- 盘点是四条命令 + 一个体量面:
openclaw doctor(update 历史警告 / cron / heap / relay)、openclaw status(channel · agents · sessions · tasks · backups · 心跳)、openclaw config validate、openclaw security audit(常见 0 critical / 若干 warn);定时任务清单用openclaw automations list,逐条openclaw automations show <id>/openclaw automations runs <id>读last error与运行历史;会话积压用openclaw sessions cleanup --dry-run(不带--enforce即 dry-run);体量du -sh ~/.openclaw/{backups,state,cache,media,logs}。 openclaw doctor --fix在本 agent 的 exec 里必然失败:它进 maintenance 阶段会检查进程树,回Doctor could not enter maintenance. Error: This command is running inside the gateway process tree (gateway PID <n>). … Run this command from a shell outside the gateway service.⇒ 只读openclaw doctor(不带--fix)能正常跑并给全量告警,诊断照做;--fix一律连停/起服务写成交付步骤交主人(systemctl --user stop openclaw-gateway→openclaw doctor --fix→systemctl --user start openclaw-gateway),不要反复重试自证必然的失败。- audit 的 warn 多是多租户通用加固,别照单全改:
security audit自己会打印 INFO「trust model: personal assistant(one trusted operator boundary)」。⇒ 分诊时把「单机单人信任下可接受」与「确实该收」分开,不是每条 warn 都是缺陷。 config patch对对象是递归合并、对标量/数组才是替换(本类最贵的一坑):把tools.exec.safeBinProfiles由 81 键改成 78 键的 patch 落下仍是 81 键且不报错;必须加--replace-path <dot.path>才整体替换。判据是回读键数,不是命令回执。- 配置改动一律先
--dry-run再落盘:回执N update(s) validated才是 schema 通过;落盘回执会写明是否需重启(Change will apply without restarting the gateway/Restart the gateway to apply)。改前cp openclaw.json /tmp/openclaw.json.pre-<说明>。 - ⚠️ 两条写入路径都只认回读、不认回执:
config patchCLI 与openclaw工具都实测过部分写入——后者一次请求改两个阈值,只应用了一个、整体仍回done、且只播报改成功的那一个(另一个静默跳过)。⇒ 工具回报里没点名的字段一律视为未确认;回读时顺带打印未涉及的兄弟字段,确认没被顺手改坏。 - 第三条写入路径:直接热编辑
~/.openclaw/openclaw.json(Gateway 监听该文件并自动应用,等价 Control UI 的 Direct edit;docs/gateway/configuration.md),也是openclaw工具不可用时的唯一出路。工具不可用实测两形态:OpenClaw change expired. No change.(改动待主人在 Control UI 批准而超时 —— 是过期不是被拒,可重发)与OpenClaw could not reach working inference … Token Plan 用量上限 (2056)。⚠️ 非法配置的热重载会被跳过、运行时保留上一份已接受配置(不会因此起不来,但改动也不生效)⇒ 热编辑后必须按openclaw-model-health-triage的「网关有效配置」读法复核,只回读文件不算数。 - 文件工具读
openclaw.json有截断陷阱:read每次只回 2000 行 / 50KB,长配置(实测 ~64KB)会被截在对象中间,JSON.parse报的位置恰好等于返回字节数 —— 那是截断、不是配置损坏;按offset/limit分页拼回再 parse,别据此报「配置文件坏了」。 - 工具白名单里的死条目要先验证再删:无插件匹配的条目(如
lobster)该删;但同一条告警里可能混着真在用的核心工具(如view_image)——逐条确认实际可用性,别整段清空。 - exec 策略落在两处,别只改一处:① 配置
tools.exec.mode(枚举deny|allowlist|ask|auto|full);② exec-approvals 存储(~/.openclaw/state/openclaw.sqlite#exec_approvals_config,读写走openclaw approvals get/set --file,含agents.<id>.security/ask/askFallback/autoAllowSkills/allowlist)。mode:"ask"的有效策略是security=allowlist + ask=on-miss + askFallback=allowlist(比字面更严:无人值守时回退成「只允许白名单」)。改完用openclaw approvals get读 Effective Policy 表核对,别只看 config。 - exec 审批结果是结构化字段,「denied」常是审查器故障而非策略拒绝:每条 exec 回执带
approvalReviews[]与approvalReviewOutcome。实测形态{label:"Guardian", status:"denied", riskLevel:"unknown", rationale:"exec reviewer completion failed: 429 … 已达到 Token Plan 用量上限"}而命令照常执行完(exitCode 0)。⇒ ① 读denied必须先看rationale:审查模型配额/限流失败时是 fail-open,命令仍放行,别当成策略拦截去「规避触发」;② 这是审批层静默降级(安全审查实际未生效),如实报主人(换额度充足或独立的审查模型),并说明命令仍会执行。 - 会话存储的维护配置在顶层
session.maintenance.*(不是agents.defaults.session.retention):mode(warn|enforce)、pruneAfter(默认 30d)、archiveDashboardAfter、maxEntries(默认 5000)、preserveRecent、resetArchiveRetention、maxDiskBytes(默认 10gb)、highWaterBytes、coldStorage。字段与默认值现取gateway config.schema.lookup session.maintenance,不背。 mode:"enforce"不等于在清理:只写 mode 而不写阈值 = 走默认,库再大也不触发(实测 439 条会话 / 1.1 GB 库,maxEntries 5000与maxDiskBytes 10gb都远未到)。症状是cleanup --dry-run回执beforeCount == afterCount、pruned 0、overBudget false—— 那是阈值没配,不是清理坏了。判据是 dry-run 的前后条数出现差值。- 回执里
archived与pruned语义相反,别当成同一件事:archived是 in-place 改元数据、保留全部 transcript、也不减小文件;pruned是删除可丢弃的自动化行且不可逆(实测一次收紧就pruned 165,全是subagent:*写手/审计子会话)。⇒ 收紧阈值前先让coldStorage把不活跃 transcript 外置完,再跑--enforce;顺序反了就是永久丢失。capped 0而afterCount仍高于maxEntries属正常(保护行不被解除);overBudget true但freedBytes 0也正常(预算是删除的触发器、不是压缩器)。 openclaw sessions archive对kind:"spawn-child"是假成功:回「Archived session …」,但活动列表、session_transcript_archives、session_transcript_cold_archives全无变化,只有updatedAt被刷(ageMs从 10d 变几十秒)。⇒ 清子代理/叶子会话直接用openclaw sessions delete --agent <id> --yes <key>…:真移除并归档转录到agents/<id>/sessions/*.jsonl.deleted.<ts>.<sha>.zst,并提示再跑openclaw memory forget --agent <id> --session <key>清索引。- 会话「分组」没有成员表:
state/openclaw.sqlite.session_groups只有(name, position, created_at, cwd, worktree),agent 库无成员表、会话 JSON 无 group 字段。⇒ 主人按「某分组里的过期会话」提问时只能按 label/spawnedCwd/title 关键词推断,并明说这是启发式,不得声称读到了归属。 - 清 cron 字段覆盖要用 CLI:
automations工具传payload.model: null不会清除(原值仍回读得到);改用openclaw automations edit <id> --clear-model(同类--clear-fallbacks/--clear-tools),改完automations get <id> --json回读。(cron get是多行 JSON,别用 grep 抓字段。) - 一批定时任务集体失败,先归因同一根因再逐条修:
doctor报「N automations have failed 3+ runs」而失败告警默认关闭(这可能就是唯一通知)。逐条openclaw automations show <id>读last error/diagnostic:实测多个记忆类 job 全是cron: job interrupted by gateway restart(另一独立形态是job execution timed out (last phase: tool-execution-started))。判「是不是 systemd 拉起的」用systemctl --user show openclaw-gateway -p NRestarts -p ExecMainStartTimestamp:NRestarts=0⇒ 不是 systemd 重启,重启来自进程内/外部机制,别默认按「服务崩溃」查。慢性失败会被调度器退避停跑(任务事实上静默停摆)。验证是否恢复:openclaw automations run <id>手动触发(回{ok:true,enqueued:true},status变running且last error清空),再用openclaw automations runs <id>读本次结果。- doctor 报的「N 个任务失败」不是全集,三类漏报要自己补:
① 执行失败 vs 投递失败是两回事。
lastRunStatus: "ok"/exitCode: 0不代表结果送达——同一份state里另有lastDeliveryStatus与lastDeliveryError,实测某 job 每天成功执行却天天投递失败(lastDeliveryError: "Delivering to Feishu requires target <chatId|user:openId|chat:chatId>"),doctor 完全不报这类失败。逐条读state时把这两个字段一并读出;announce+channel: "last"在飞书上不成立,须写实channel+to。 ② 「被重启打断」不算真失败:doctor 明说它把job interrupted by gateway restart也计入失败数。分诊时先按last error归类,重启打断的连续出现才值得查根因,偶发一次不算。 ③ 投递目标 open_id「跨应用」= 每天静默丢消息,且状态仍报 ok:飞书open_id是按应用命名空间的,别处存着的ou_…很可能不属于本 bot 应用,实测回lastDeliveryStatus: "not-delivered"+lastDeliveryError含feishu_code:99992361 / "open_id cross app",而同一份state的lastRunStatus仍是ok⇒ 「执行成功」与「送达」必须分别读。修法:真源是channels.feishu.allowFrom里那个 id(本 bot 应用认的),不是凭印象抄一份;改完必须用message工具实发一条验证(回messageId才算通),别等下一个排期才发现又没送达。 last phase: tool-execution-started超时:先比时长,再手动计时定性,别先改任务书:payload.timeoutSeconds与state.lastDurationMs摆一起看。lastDurationMs ≈ timeoutSeconds(实测 600144 vs 600)有两种成因,处理方式相反,用一条命令分开:把该 job 的脚本/命令原样手动跑一次计时。- 脚本手动跑很快(秒级)而 job 必撞上限 ⇒ 不是任务变慢,是cron ↔ gateway 锁自锁:任务体内(如体检脚本里的
openclaw cron list、openclaw memory status)再调openclawCLI,会与正在执行本任务的 gateway 进程抢同一把 cron 锁 ⇒ 子进程永等、job 卡到上限。对症是给脚本内每处openclaw ...加timeout N护栏(已验证:加timeout 25/timeout 40后脚本 15 秒内跑完),放宽timeoutSeconds有害——那只是让每次失败多烧一倍时间。 - 脚本手动跑也慢/确实要那么久 ⇒ 才是真的上限卡死,按原口径放宽
timeoutSeconds。consecutiveErrors持续累加会触发自动停用,越晚修越亏。
- 脚本手动跑很快(秒级)而 job 必撞上限 ⇒ 不是任务变慢,是cron ↔ gateway 锁自锁:任务体内(如体检脚本里的
- 第三种失败形态:
last error是「启动自检未在预算内完成」,与上面两种的处置方向相反:实测两条跑在 main 上的 job 回Agent main has not completed startup inspection and preparation. The 5 second foreground startup budget elapsed; inspection continues.⇒ 含义是该 agent 的启动自检没跑完,session 当时不可用,任务是被挡在门外而不是自己跑挂了。- 先分诊再归因,别默认它来自上两种:它既不是「被重启打断」也不是「任务体超时」,所以上面两条的处置(查 NRestarts / 给脚本内
openclaw …加timeout护栏 / 放宽timeoutSeconds)一条都不适用,照做只会白改。 - 「启动预算是被什么撑爆的」必须实测,别按体量猜——2026-10-16 本机实测的归因是 agent 数据库完整性门,不是技能数也不是记忆体量:取证入口是只读
openclaw doctor(不带--fix,见下条),它会打一行[state/agent-db] agent database integrity gate,字段含elapsedMs/phaseDurationsMs/integrityGateMs/thresholdMs/ 逐表integrityTableTimings。实测该机validation:6425ms、thresholdMs=1000,而前台预算只有 5 秒 ⇒ 校验本身超预算,会话因此长期不可用。慢在三张表:memory_embedding_cache2434ms、memory_index_chunks1241ms、trajectory_runtime_events719ms。 归因纪律不因此撤销:别的机器仍可能另有原因,以 doctor 那行的实测数字为准;automations list的 status 列只给 error / skipped,要给证就逐条automations show <id>读last error原句。别把「技能多 / 记忆大」当既定原因写进报告——与openclaw-gateway-performance-triage「库体量与配置体量都不是速度的代理指标」同一条纪律。 ⚠️ 「库大」不等于「碎片多」——归因到校验慢之后,还要先分清容量问题还是配置问题,否则主修法会选错。 2026-10-16 本机实测反例:openclaw doctor --session-sqlite compact全程成功,库 633 MB → 624 MB(只回收 9 MB / 1.4%),两条 error cron 依然 error。⇒ compact 对本形态无效。原因是session.maintenance.pruneAfter早已是"7d",库里 402 MB(64%)是transcript_events+trajectory_runtime_events这类真实会话与遥测数据,不是可回收的空闲页;pruneAfter已配 + 数据全是近 7 天的真实工作 ⇒ 这是容量问题、不是阈值或碎片问题。 ⇒ 禁止把 compact 当这一形态的主修法。分诊顺序:① 用dbstat归因最大表(命令见references/会话库膨胀分诊.md§A 判据 4);② 若最大表是真实会话/遥测数据且pruneAfter已收紧 ⇒ 无技术解,只能交主人三选一:缩短pruneAfter(真实丢弃历史,必须主人拍板)/把跑在该 agent 上的任务迁到别的 agent(不丢数据,推荐)/接受现状并如实报「未修及原因」。③ 只有freelist_count显示碎片可观时,compact 才是主修法。不要先假设「压小库就能过预算」——这与上一条的「体量不是速度代理指标」是同一条纪律的两种形态,一个防误归因、一个防误开方。 - ⚠️ 「已经跑了」不等于「做成了」——交接脚本后必须独立取证,不要凭主人一句确认就报成功。 2026-10-16 实测:主人说「已经跑了啊」,但维护日志里搜不到该次运行的任何一行(
grep -c "维护开始(v2)"回0),而gateway-restart.log显示 22:22:19action=stop interactive=0/ 22:24:52action=start interactive=0⇒ 只证明网关确实被非交互地停起过,不证明 compact 跑过、更不证明它有效(库只小 9 MB,且未出现 v2 日志)。判据:正向取证 = 日志里有该次运行的起止行 + 库体积给出前后两个值 +openclaw automations run <id>手动触发后last error清空。三者缺一即报「未确认」,别把「网关重启过」当「维护成功过」。 - 实测形态(逐条验过才登记,没验的不要替它断言根因):2026-10-16 同批 4 条 error 里,本轮实查 2 条 ——
Daily Skill Update (lunheng)回的就是本条的启动预算原句(last error与diagnostic同为The 5 second foreground startup budget elapsed;last delivery字段是unknown、而last delivery error装的是同一条错误 ⇒ 执行与投递同因失败);Memory Distillation (novelist)回的是泛化文案OpenClaw couldn't finish this reply. For details, open Settings → Logs,它尚未被归因,不能因为同批就并入启动预算一条;另两条(两个 Heartbeat)只验到 list 层状态、连automations show都没跑过。要坐实泛化文案那条,查openclaw logs或复跑openclaw automations run <id>看是否回落到同一句。\n⚠️ 「同批归因」的谨慎已被后续实测推翻:这两条的运行历史显示它们各自前 4 次都ok,且唯一那次 error 紧跟开机(详见下方开机窗口一条)⇒ 同批一起变红 ≠ 同一根因。分诊时逐条独立取证,不要因为一批 job 同时报错就套用同一个根因或同一个修法。 - 修法按实测归因选,且都要先拿到上一条的归因再谈:归因落在碎片多 / 校验慢 ⇒ 主修法是
openclaw doctor --session-sqlite compact(官方文档语义:WAL checkpoint +VACUUM+ 转auto_vacuum=INCREMENTAL)。⚠️ 但「库大」必须先拆成「碎片多」还是「真实数据多」再选修法——实测 compact 把 633 MB 压到 624 MB(仅回收 1.4%)时,两条 error cron 依然 error ⇒ 库里绝大部分是真实会话/遥测数据时 compact 无效;此时无技术解,只能交主人三选一(缩短pruneAfter丢历史 / 把任务迁到别的 agent / 接受现状)。归因与分诊顺序见上条与references/会话库膨胀分诊.md§A。文档给的标准序列是openclaw gateway stop→openclaw backup create --verify→doctor --session-sqlite compact --session-sqlite-all-agents→openclaw gateway start;⚠️ 但文档这条序列照抄会失败:对运行中的 operator 网关,gateway stop必须加--force,否则退出码 1 并拒绝执行(文档与gateway --help的示例都写的是裸命令)。整段需要停网关 ⇒ 交主人执行,本 agent 不自行 exec 重启;且不得在本网关托管的会话里后台发射该序列(停网关会连带杀掉本会话、事后无法汇报)。完整序列、脚本三条硬要求(校验退出码即中止 /trap … EXIT兜底拉起 / 确认网关真停)与审批层拒绝的正确处置,见references/会话库膨胀分诊.md§C-4。另一方向是调高该 agent 的启动自检预算或降低启动期读入量,在归因不是这两者时改它们是白改。改完用openclaw automations run <id>手动触发验证(同上条的验证口径)。 - ⚠️ 给「迁到别的 agent」之前,先量目标 agent 的库体量——迁移方向可能就是反的。 实测(2026-10-16):
main库 625 MB 而novelist库仅 21 MB(差 30 倍),启动预算超时的是main;此时若把novelist的任务「迁到 main」等于把能跑的 agent 推进死路。⇒ 本条三选一里的「迁到别的 agent」只有在目标 agent 库体量显著更小时才是解法;先ls -lh ~/.openclaw/agents/*/agent/openclaw-agent.sqlite逐个比,目标不比源小 ⇒ 报「无迁移这条路」,别把这个选项当成推荐项递给主人。库体量是本形态唯一可用的量化判据(session.maintenance.*只影响单个 agent,管不了别的库)。 - ⚠️ 「这个任务是不是真坏了」先看运行历史,再看
last error:automations runs <id>与开机时间一对,失败常只是开机补跑窗口的产物。 实测(2026-10-16)两条 job 各有 5 条历史,前 4 条ok、仅最新一条error,而那条 error 的runAtIso是15:58:06/16:00:36,uptime -s是15:57:16⇒ 失败发生在开机后 50 秒 / 3 分 20 秒,是关机期间积压的调度在网关启动瞬间集中补跑、撞上启动自检窗口,不是任务缺陷、也不需要迁移任何东西。⇒ ① 拿到一批 error job 先跑openclaw automations runs <id>(回entries[],每条含runAtIso/status/durationMs/error),看连续 ok 的长度——「长期 ok + 单条 error」与「连续 error」是两种病,前者多半是窗口撞车;② 再uptime -s对齐那条 error 的runAtIso,差值小于几分钟即判开机窗口;③ 这类结论的正确交付是「什么都不改,等下一次自然排期自证」,把 compact / 迁 agent / 缩pruneAfter三个动作全部收回——它们修的是一个并不存在的常驻故障。⚠️status与completionStatus是两个独立字段(实测同一 job 出现status=ok+completionStatus=failed与ok/succeeded两种组合),判成败以status+error为准,别只看completionStatus。⚠️automations runs的 JSON 顶层键是entries,不是runs/items;写解析脚本取错键会静默取到 0 条(实测两次都回空),从而误判「没有历史」。
- 先分诊再归因,别默认它来自上两种:它既不是「被重启打断」也不是「任务体超时」,所以上面两条的处置(查 NRestarts / 给脚本内
- doctor 报的「N 个任务失败」不是全集,三类漏报要自己补:
① 执行失败 vs 投递失败是两回事。
- 状态目录的旧快照能到几百 MB:
~/.openclaw/backups/实测含 339 MB 的main-agent-auth-*.sqlite(十几天前的库快照)。清理用gio trash(本机有/usr/bin/gio,禁用rm)。⚠️ trash 不释放磁盘空间(回收站与状态目录同盘)⇒ 报释放量用df前后对比而非du;且盘不紧张时不要把清理当优化项(实测 1007 G 用 30 G,清 1.5 G 收益近零)。完整清理判据与回收站再生项见workspace-declutter。 - 主人说「会话 / 状态目录到了 N G」时,先分诊再动手:那 1 GB 通常不在
agents/<id>/sessions/(实测库本体 1.1 GB 而sessions/仅 8.9 MB);碎片还是数据用只读pragma freelist_count判(实测 free 1.4 MB / total 1.04 GB ⇒ 碎片可忽略,先删数据再 VACUUM,直接 compact 只省 1.4 MB)。完整分诊、收紧配置、执行顺序(coldStorage → dry-run → enforce → compact)、残留类别与命令形态见references/会话库膨胀分诊.md。 - 插件自带的 SecretRef schema 可能与核心校验冲突:openviking 的
config.apiKey三种写法({source:file,id}/{source:file,provider,id}/{source:env,…})实测全被拒,schema lookup 声称允许 file 型而校验只认 env 型 ⇒ 属插件 bug。改不动也要如实报,把出路(升级插件 / 改${ENV}+ 环境变量)写进交付,不为「全绿」硬凑。 - 本 agent 永不 exec 重启本 Gateway:
Restart the gateway to apply的项集中列给主人(或走openclaw工具),不要用 exec 跑systemctl restart。同理需要停网关的离线维护(backup create/doctor --session-sqlite compact)整段交主人;本 agent 只给命令序列与理由。 - ⚠️
openclaw工具报Cannot find module …/tmp/plugin-captures/…时,先怀疑「清理时删过该目录」,而不是插件装坏。 实测(2026-10-17):config.set失败回执的 require stack 指向extensions/feishu/dist/index.js、缺失模块却在tmp/plugin-captures/下 ⇒ 故障面只有「用工具写配置」这一条,gateway 仍health OK、通道仍configured、插件本体在extensions/<id>/dist/完好;删后 40 分钟该目录未自行再生。⇒ 处置按 SKILL.md「第三条写入路径」直接热编辑openclaw.json绕过(只读 CLI 全部正常);不要去重装插件、也不要反复重试同一次工具调用。完整判据、指纹识别与恢复路径见references/会话库膨胀分诊.md§D。 - 明文密钥要跑
openclaw secrets audit --check,别只跑doctor:doctor的 Security 面板只点名openclaw.json里的models.providers.<id>.apiKey,这不是总数。secrets audit --check覆盖models.providers.*、state/openclaw.sqlite的 auth profile、各 agent 的models.json与 sqlite,回plaintext=/unresolved=/shadowed=/legacy=四个计数。⇒ 同一个 key 常在多处同时明文存在(同一 provider 在配置与 auth profile 里各有一份)⇒ 只改openclaw.json里那几处等于没改,会得到「看起来安全了」的假象。security audit的 warn 列表不含这一类,三条命令各报一面,缺一不可。 ⚠️secrets audit --check的扫描面不含插件级 config:plugins.entries.<id>.config.apiKey这类明文存放的值不进它的回执 ⇒ 报总数前自己再扫一遍plugins.entries下每个config的 key/token/secret 字段,把漏掉的并进计数;工具回执不是全集。扫描只输出路径与长度,不回显值——值一旦进终端历史就等于泄露。 - ⚠️
openclaw secrets store list会把env类型条目明文打印出来,而secret类型只显示掩码。 实测一次store list打印出两条真实密钥(*_AGENT_PLAN_API_KEY、EXA_API_KEY,均为env类型),主人把它们贴回对话即等于泄露到终端历史 + 对话记录。⇒ 排查密钥时不要把store list的原始输出转述或贴给主人;看到env类型条目就在报告里只写名称不写值,并提示主人在控制台轮换。排查用secrets audit --check(按路径报、不含值)替代store list。 store set的--value只对env类型生效;secret类型必须走掩码交互提示。openclaw secrets store set <NAME> --kind secret不带--value会弹掩码输入(值不进 shell history、不落盘、不经过 agent 上下文)⇒ 给主人的录入指令一律用不带--value的形式,并明确告知「不要把 key 贴进对话」。- ⚠️ 给主人的密钥模板里不要用
***当占位符——实测主人原样粘贴后,store import会把***识别成 OpenClaw 的脱敏占位符并拒绝写入(回contains a redaction placeholder/Skipped redacted value)。系统拦住了所以无损坏,但流程被打断。写模板时用<粘贴你的真实key>这类明确占位文字。 - 「密钥已在 store 但配置仍是明文」是常见形态,别当成没迁移过:实测库中
TEAMOROUTER_API_KEY等早已是[secret] write-only,而openclaw.json照旧明文 ⇒ 真正缺的是配置接线,不是搬运密钥。接线写法是内建来源store,不需要在secrets.providers里定义 provider(那里放的是自建file类型,二者不是一回事):{"source":"store","provider":"default","id":"ENTRY_NAME"}。⚠️ 顺序不可颠倒——配置先指向不存在的条目会让该 provider 直接变冷(调用失败)。先确认条目已入库,再改配置。secrets configure需要 TTY、agent 跑不了,接线那步交主人或走热编辑。 - JSON 批量改配置前先验证「往返同一性」:
json.dumps(d, ensure_ascii=False, indent=2)+"\n"与原文逐字节比对回IDENTICAL才动手,否则整份 66 KB 配置会被重排、diff 淹没真实改动。改完用diff <(json.tool 备份) <(json.tool 现文件) | grep -c '^<'确认删除/修改行为 0、只有新增行。(批量禁用技能走skills.entries.<name>.enabled=false,该字段就是禁用开关,与白名单排除是两套机制。) openclaw sessions delete不动cold/归档目录:实测删 10 条超期会话后活跃会话 66→56,但agents/<id>/sessions/cold/的 301 个文件 / 57 MB 一字未变;输出里的Archived transcript: …说明转录是归档不是删除,且仍可被记忆检索命中 ⇒ 还要跑openclaw memory forget --agent <id> --session <key>(仅本机跑,不接受--url转发)。⇒ 主人说「清掉 N 天以前的」若其真实目标是释放cold/那几十 MB,本命令达不到,须先讲清两者不是一回事再动手。- ⚠️
*.jsonl.deleted.*.zst不是删除残留,是 OpenClaw 托管的规范转录归档副本,清理时必须排除。 实测踩坑:看到agents/main/sessions/下 43 个*.jsonl.deleted.<ts>.<sha>.zst,按「已删会话的垃圾残留」清掉,事后openclaw update status回Missing 35 canonical transcript archive file(s); showing 5 example(s)+ 逐条Missing canonical transcript archive copy:⇒ 这些副本由迁移流程按规范路径管理。数据本体仍在 SQLite blob 里(官方回Canonical SQLite archive blobs remain retained),属警告非数据丢失,但副本不会自动重建。⇒ ① 清理sessions/时按模式排除.deleted.,别按「文件名像垃圾」判;② 事后自查跑openclaw update status看有没有Missing canonical transcript archive;③ 真正的删除残留是.tmp/.DS_Store/:Zone.Identifier之类,不带.deleted.。判据是文件名前缀 + update status 告警,不是主观的「看起来没用了」。 - ⚠️ 开方前先用一条独立命令验证「前提」本身,这步最容易省且最贵。 连续三次因未验证前提给出错方向:① 把启动自检超时归因成「空闲页没回收」并推荐 VACUUM,实测 compact 只回收 9 MB / 1.4%,证明库里是真实数据;② 未量目标 agent 库体量就推荐「把任务迁到 main」,而 main 正是超预算的那个(625 MB vs novelist 21 MB),方向反了;③ 断言「某大文件 110 K 在吃上下文」,
grep全配置零引用——它根本不注入,省的是磁盘不是延迟。⇒ 每条修法落地前先验证「它确实是我说的那个东西」:是否真被注入用grep查引用面、体量是否真是问题源用du/dbstat归因、迁移方向是否对用体量对比。实测值推翻假设时如实推翻并说明原判断错在哪,不要把错方案留在报告里等主人拍板。
步骤
- 盘点:四条命令 + 体量面,先出全景
跑前置事实里的 doctor / status / config validate / security audit / automations list(逐条 show / runs 读 last error)/ sessions cleanup --dry-run,再
du -sh状态目录各子目录。 完成判据:能逐条说出「哪些是告警、哪些是信息、体量重心在哪」,且每条告警都落到具体配置路径(如tools.exec.mode、browser.extensionRelay.allowLegacyAuth)。 - 分诊与排序:严重度 × 是否改变交互 每项标零行为影响(死引用 / 旧快照 / 冗余清单)/改变交互(exec 策略、工具面、自动归档)/信息性之一;档内按「收益 ÷ 风险」排,并把改变交互的排到最后。 完成判据:产出带档位的清单,读者一眼看出哪些可直接做、哪些要主人拍板。
- 分批修正:一组一 dry-run、一组一回读
逐条按前置事实的坑修:配置类先
--dry-run(对象整体替换记得--replace-path);状态类先备份或gio trash;凭据类先报后动。每批做完立即回读该路径实际值并记「改前 → 改后」。 完成判据:每批都有回读证据(键数 / 值 / 计数),不接受「命令回执成功」当完成;改不动的项如实登记为未修并写明原因与出路,不静默跳过、不硬凑。 - 交付:清单 + 重启项 + 记账
报告分「已修(含前后值)/未修(含原因与出路)/待主人拍板」三段;需重启才生效的项集中列出交主人;写当日
memory/YYYY-MM-DD.md(改了什么、备份在哪、还差什么)。 完成判据:主人拿到可复核的改动账本与重启清单;本 agent 未自行重启 gateway。
边界
- 只做本机配置与状态面(
~/.openclaw);工作区文件整理走workspace-declutter,provider / 插件 / 通道的增删走各自 removal 技能。 - 改变交互的加固(exec 策略、工具面、自动归档)须主人明确指令;只诊断时不得顺手改。
- 删除一律可恢复(
gio trash/ 移入备份目录 / 先cp),禁用rm。 - 结论只用实测值与回读值;引用体检报告的既有定性(含本文里的历史数字)前先重测。
成功样例
2026-09-20 全盘体检 +「依次全部修正」:doctor 报明文密钥 / lobster 死引用 / awk·jq·sed 在 safeBins / legacy relay;security audit 8 warn(exec=full、autoAllowSkills、插件版本未锁等)。修:旧快照 341 MB→1.2 MB(gio trash 9 个);alsoAllow 48→47(删死条目,view_image 经核验保留);safeBins 81→78 且 safeBinProfiles 必须 --replace-path 才同步降到 78;新增 session.maintenance{mode:enforce, archiveDashboardAfter:30d, preserveRecent:14d};automations edit --clear-model 清两个 job 的 model 覆盖;extensionRelay.allowLegacyAuth=false(需重启);tools.exec.mode full→ask + autoAllowSkills=false,有效策略 = allowlist + ask=on-miss。未修 1 项:openviking apiKey 明文——插件 schema 自相矛盾,三种 SecretRef 写法全拒,出路写进交付。
同日会话面:按「论衡」三组筛过期会话时先确认分组无成员表(只能启发式),命中 2 条 kind:"spawn-child" 的 failed 会话;sessions archive 假成功 → 改 sessions delete 真删并归档转录。
- Downloads
- 87All time
- Security audit
- Review
- Last updated
- 3d ago
- Current version
- v1.0.0
- License
- MIT-0
