melkhamesey2/openclaw-runtime-stabilizer

# OpenClaw Runtime 稳定器 这是一个公开的工程工件、可靠性案例研究，以及用于 OpenClaw runtime/session-store 事故的只读验证工具包。 本仓库记录了本地 AI agent runtime 在发生 session-store 不一致、dashboard session 冲突、孤立 session 条目以及 runtime/config 漂移后，进行的真实稳定化工作流。公开版本侧重于安全诊断、可复现的文档记录、证据脱敏、回滚规范、操作验证以及基于 mock 的只读工具。 ## 目标 runtime 本仓库中记录的工作是针对以下环境执行的： ``` OpenClaw 2026.6.8 ``` 除非在其他版本上重新验证，否则所有具体的 runtime 假设都应视为仅适用于 OpenClaw `2026.6.8` 版本。 参见 [`docs/TARGET_RUNTIME.md`](docs/TARGET_RUNTIME.md)。 ## 为什么这很重要 本地 AI agent runtime 是有状态系统。当 session、registry、dashboard、compaction artifact 和 runtime bundle 发生不同步（漂移）时，即使 transcript 仍存在于磁盘上，其结果也可能看起来像是数据丢失。安全的修复工作流必须优先保留数据，在修改状态之前进行验证，并避免破坏性的重置操作。 ## 范围 此公开版本包含： - 事故分析和执行摘要 - 目标 runtime/版本说明 - 针对类似症状的故障排查矩阵 - 只读 session-store 分析器 - 用于安全测试的 mock session-store 环境 - 稳定化方案的架构说明 - 回滚和验证策略 - 公开发布的脱敏策略 - 已脱敏的证据摘要 - 安全环境文档示例 本仓库特意**不**发布私有 transcript、原始本地日志、特定于机器的路径、主机名、token 或一键式破坏性修复操作。 ## 安装 环境要求： - Node.js 20 或更高版本 - npm 克隆并安装： ``` git clone https://github.com/melkhamesey2/openclaw-runtime-stabilizer.git cd openclaw-runtime-stabilizer npm install ``` 目前没有外部 runtime 依赖项。`npm install` 作为标准项目设置步骤以及为了未来的兼容性，仍然是有用的。 ## 运行只读验证器 针对内置的安全 mock 数据集运行： ``` npm run verify:mock ``` 等效的直接命令： ``` node tools/verify-readonly.mjs examples/mock-session-store ``` 验证器会打印一份 JSON 报告。它不会写入、删除、重命名、修复或更改任何文件。 若要执行完整的项目检查： ``` npm run check ``` `check` 工作流使用 npm 生命周期钩子： - `precheck` 运行本地自检。 - `check` 运行只读 mock 验证。 - `postcheck` 重复自检，使得自动化边界清晰明确。 当前的 npm 脚本： | 脚本 | 用途 | | --- | --- | | `npm run verify -- ` | 在指定的 session-store 目录上运行验证器。 | | `npm run verify:mock` | 在内置的 mock fixture 上运行验证器。 | | `npm run check` | 运行带有前置/后置钩子的完整只读验证工作流。 | ## 大文件处理 该分析器专为大型 JSONL transcript 文件设计。它使用流式文件读取进行 transcript 哈希处理，并逐行进行 JSONL 验证，而不是将整个 transcript 文件加载到内存中。 实用的大文件选项： ``` node tools/verify-readonly.mjs examples/mock-session-store --large-file-bytes 1048576 node tools/verify-readonly.mjs examples/mock-session-store --max-jsonl-line-bytes 1048576 ``` - `--large-file-bytes` 控制报告中何时将 transcript 标记为大文件模式。 - `--max-jsonl-line-bytes` 限制对异常庞大的单行 JSONL 进行深度 JSON 验证时的字节上限。 ## 快速阅读路径 1. [`docs/TARGET_RUNTIME.md`](docs/TARGET_RUNTIME.md) 2. [`docs/EXECUTIVE_SUMMARY.md`](docs/EXECUTIVE_SUMMARY.md) 3. [`docs/TROUBLESHOOTING_MATRIX.md`](docs/TROUBLESHOOTING_MATRIX.md) 4. [`examples/mock-session-store/README.md`](examples/mock-session-store/README.md) 5. [`src/session-store-analyzer.mjs`](src/session-store-analyzer.mjs) 6. [`tools/verify-readonly.mjs`](tools/verify-readonly.mjs) 7. [`docs/INCIDENT_TIMELINE.md`](docs/INCIDENT_TIMELINE.md) 8. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) 9. [`docs/OPERATIONAL_VERIFICATION.md`](docs/OPERATIONAL_VERIFICATION.md) 10. [`docs/ROLLBACK_POLICY.md`](docs/ROLLBACK_POLICY.md) 11. [`docs/REDACTION_POLICY.md`](docs/REDACTION_POLICY.md) 12. [`evidence/SANITIZED_EVIDENCE_SUMMARY.md`](evidence/SANITIZED_EVIDENCE_SUMMARY.md) ## 仓库结构图 ``` . ├── README.md ├── LICENSE ├── NOTICE ├── SECURITY.md ├── CONTRIBUTING.md ├── package.json ├── docs/ │ ├── ARCHITECTURE.md │ ├── EXECUTIVE_SUMMARY.md │ ├── FINAL_REPORT_AR.md │ ├── INCIDENT_TIMELINE.md │ ├── OPERATIONAL_VERIFICATION.md │ ├── PROJECT_STATUS.md │ ├── REDACTION_POLICY.md │ ├── RELEASE_NOTES.md │ ├── REPOSITORY_MAP.md │ ├── ROADMAP.md │ ├── ROLLBACK_POLICY.md │ ├── TARGET_RUNTIME.md │ └── TROUBLESHOOTING_MATRIX.md ├── evidence/ │ └── SANITIZED_EVIDENCE_SUMMARY.md ├── examples/ │ ├── redacted-environment.example │ └── mock-session-store/ │ ├── README.md │ ├── sessions.json │ └── transcripts/ ├── src/ │ ├── README.md │ └── session-store-analyzer.mjs ├── tools/ │ ├── README.md │ └── verify-readonly.mjs └── .github/ ├── workflows/ │ └── docs-check.yml └── ISSUE_TEMPLATE/ └── safe-incident-report.md ``` ## 当前发布状态 `v0.2.1` 是一个公开文档和只读验证版本。它专为审查、学习、事故对比、安全操作规划、基于 mock 的验证、npm 自动化以及具备大文件感知能力的 transcript 检查而设计。 ## 安全立场 本项目是防御性的，并专注于可靠性。它不是绕过工具包、漏洞利用项目或破坏性补丁集合。默认规则是：先进行检查，保留数据，验证哈希，并且绝不将删除 transcript 作为第一响应。 ## 建议的 GitHub topics ``` openclaw local-ai ai-agents runtime-reliability incident-response state-repair session-store rollback-safety redaction windows nodejs ```

标签：AI运行时, GNU通用公共许可证, MITM代理, Node.js, 可靠性, 故障排查, 时序数据库, 暗色界面, 状态管理, 系统运维, 自定义脚本