arcabotai/clawfix
GitHub: arcabotai/clawfix
ClawFix 是一款 AI 辅助的 OpenClaw 运维诊断与安全修复工具，通过本地扫描与脱敏日志分析帮助用户一键定位并修复常见配置和运行时故障。
Stars: 5 | Forks: 0
# 🦞 ClawFix
[](https://github.com/arcabotai/clawfix/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/clawfix)
[](https://www.npmjs.com/package/clawfix)
[](LICENSE)
**AI 驱动的 OpenClaw 诊断与修复服务。**
一条命令修复损坏的 OpenClaw。无需 SSH 访问。在本地运行，发送经过脱敏处理的日志，并获取修复脚本。
## 快速开始
```
# 推荐 — npm + GitHub 上的可审计源
npx clawfix
# 检查将要收集的数据（不发送任何内容）
npx clawfix --dry-run
```
### 备选方案：curl
如果您愿意，可以先下载并检查脚本：
```
# 下载、检查，然后运行
curl -sSL clawfix.dev/fix > clawfix.sh
cat clawfix.sh # Read every line
shasum -a 256 clawfix.sh # Verify hash
curl -s clawfix.dev/fix/sha256 # Compare with published hash
bash clawfix.sh # Run after reviewing
```
## 使用与维护
ClawFix 是一个持续维护的开源运维工具，而不是一次性的演示。
于 2026 年 7 月 22 日验证：
- npm CLI 记录了[自 2 月 22 日以来的 1,175 次下载](https://api.npmjs.org/downloads/point/2026-02-22:2026-07-22/clawfix)，其中包括[过去 30 天内的 247 次下载](https://api.npmjs.org/downloads/point/2026-06-22:2026-07-21/clawfix)。
- 托管服务报告了[192 次已完成的诊断](https://clawfix.dev/api/stats)。
- 当前的 pull-request 和 `main` CI 在 Node.js 22 和 24 上运行测试，包括修复验证、基于 ShellCheck 的修复校验、生产环境依赖审计、npm 包检查以及容器冒烟测试。发布工作流在发布之前会重复 Node.js 24 测试、修复、审计和包检查。
维护记录公开在[更新日志](CHANGELOG.md)、[发布](https://github.com/arcabotai/clawfix/releases)、[议题](https://github.com/arcabotai/clawfix/issues)和[代码拉取请求](https://github.com/arcabotai/clawfix/pulls)中。
## 工作原理
1. **运行一条命令** — 诊断脚本会扫描您的 OpenClaw 配置、日志、插件、端口以及监听器所有权
2. **关联证据** — 在 AI 处理新问题之前，会先运行原生的配置验证、状态检查、Doctor、安全审计以及 49 种确定性模式
3. **审查并应用** — 您会获得一份带有注释的修复脚本。未经您的批准，不会执行任何操作
失败和警告会被计为问题。性能和质量的调整会作为可选的优化建议单独显示。
## 检测内容（49 种确定性模式）
- 💀 Gateway 崩溃（端口冲突、进程挂起、重启循环）
- 🧠 内存问题（Mem0 静默失败、缺少刷新、搜索损坏）
- 🌐 浏览器自动化（CDP 端口失败、扩展加载、headless 问题）
- 🔌 插件配置（损坏的插件、错误的设置）
- 💸 Token 浪费（过多的心跳包、无修剪、上下文冗余）
- 🍎 macOS 异常（Metal GPU 崩溃、Apple Silicon 问题）
- 🔧 服务管理器崩溃（launchd/systemd SIGTERM 恢复、崩溃循环）
- 👻 僵尸进程（PID 存在但端口未监听）
- 📜 错误日志膨胀（Chrome 扩展垃圾信息、握手风暴）
- 🐕 Gateway 看门狗建议（独立的健康检查）
- ⚡ 原生 Codex harness 漂移（PI 路由回退、session-store 权限、shell `CODEX_HOME`、fast tier、超时边界）
- 🧵 模型提供商前缀拼写错误（`codex/gpt-5.4` 与 `openai-codex/gpt-5.4` — 静默 403 + 回退循环）
- 🎣 被静默丢弃的 Discord 群组消息（带有空 `allowFrom` 的 `groupPolicy=allowlist`）
- 🔒 配置中的明文敏感信息（标记出本应是指向 `~/.openclaw/.env` 的 SecretRef 的字段）
- 🪪 无效的 `GH_TOKEN`/`GITHUB_TOKEN` 环境变量覆盖了正常工作的 `gh` 登录状态
- 📡 陈旧的自配对节点导致无休止的 `skills-remote` 探测超时
- 🌊 会话上下文溢出（>100 % 窗口，自动压缩失败）
- 🔐 FileVault 阻止无人值守的重启
- 📦 LaunchAgent plist 在 `.env` 迁移后带有陈旧的受管环境变量
- 🧩 OpenClaw/Node.js 引擎不兼容，包括失败的 `openclaw --version` 输出
- 🩺 来自原生 OpenClaw Doctor 的只读结构化 lint 模式的发现
- 🛡️ 带有凭据脱敏证据的原生 OpenClaw 安全审计发现
- 🚧 当另一个进程阻塞 OpenClaw 启动时的 Gateway 端口所有权
## 安全与透明度
我们非常重视安全。ClawFix 的设计围绕**知情同意**的原则 — 在发生任何事情之前，您会看到所有内容。
### 收集哪些数据
| 类别 | 数据 | 敏感？ |
|----------|------|-----------|
| 系统 | 操作系统类型、版本、架构 | 否 |
| 运行时 | Node.js 版本、npm 版本 | 否 |
| OpenClaw | 版本、运行时兼容性、schema 有效性、允许列表中的 gateway/服务状态 | 否 |
| Doctor | 检查 ID、严重程度、消息、配置路径和修复提示（最多 100 个发现） | 潜在低风险；使用 `--dry-run` 检查 |
| 安全审计 | 摘要、脱敏后的发现文本、修复提示、抑制计数 | 潜在低风险；使用 `--dry-run` 检查 |
| 端口 | 监听状态、进程名称、PID 和 endpoint | 低风险 |
| Codex | 预期的 OpenClaw Codex 主路径和 shell 匹配布尔值 | 否 |
| 配置 | 仅结构 — **所有敏感信息均已脱敏** | 已脱敏 |
| 日志 | 匹配错误/警告模式的最后 30 行 | 低风险 |
| 工作区 | 文件计数、存在性检查（SOUL.md 等） | 否 |
| 身份 | 主机名 **SHA-256 哈希**（仅前 8 个字符） | 已匿名化 |
### 不收集哪些内容
- ❌ API 密钥、token 或密码（全部自动脱敏）
- ❌ 文件内容（SOUL.md、AGENTS.md、内存文件、聊天记录）
- ❌ 环境变量值（跳过配置中的 `env` 块；Codex 检查仅发送匹配的布尔值）
- ❌ 真实主机名（仅发送简短的单向主机哈希）
- IP 地址仅临时用于限制滥用，不包含在诊断记录中
- 错误日志是非结构化的，可能包含脱敏程序无法识别的标识符；在同意之前使用 `--dry-run` 进行检查
### 验证工具
```
# 准确查看将要发送的内容（不发送任何内容）
npx clawfix --dry-run
# 显示完整的 payload，然后请求发送
npx clawfix --show-data
# 验证 curl 脚本哈希
curl -sSL clawfix.dev/fix | shasum -a 256
curl -s clawfix.dev/fix/sha256
```
### 设计决策
- **需要同意**：诊断数据仅在您在提示符下输入“y”后发送
- **修复脚本不会自动执行**：它们被保存到 `/tmp` 供您审查
- **无模型生成的 shell**：AI 输出仅供参考；可执行的修复来自经过审查的确定性代码片段
- **修复验证**：组合的确定性脚本必须通过 `bash -n`；托管构建还会运行 ShellCheck，并在验证器报错时关闭失败通道
- **反馈是可选的**：仅当使用 `CLAWFIX_SEND_FEEDBACK=1` 运行时，修复脚本才会报告结果
- **自动备份**：每个修复脚本在修改前都会备份 `openclaw.json`
- **开源**：[100% 的代码](https://github.com/arcabotai/clawfix) 都是公开的 — CLI、服务器、诊断脚本
- **使用 npx 而非 curl**：我们推荐 `npx clawfix` 作为主要方法，因为其源码在 [npm](https://www.npmjs.com/package/clawfix) 和 GitHub 上是可审计的
### CLI 选项
```
npx clawfix [options]
--dry-run Scan locally, show what would be collected, send nothing
--no-send Same as --dry-run
--json Machine-readable local scan; sends nothing
--server URL Use custom API server
--help, -h Show help
--version, -v Show version
```
## 自托管
不信任我们的服务器？运行您自己的：
```
git clone https://github.com/arcabotai/clawfix
cd clawfix
npm install
npm start
```
将 CLI 指向您的实例：
```
CLAWFIX_API=http://localhost:3001 npx clawfix
```
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `PORT` | `3001` | 服务器端口 |
| `AI_PROVIDER` | `openrouter` | 用于 OpenRouter 请求元数据的 AI 提供商标签 |
| `AI_MODEL` | `deepseek/deepseek-v4-flash` | 用于分析和聊天的 OpenRouter 模型 |
| `OPENROUTER_API_KEY` | — | OpenRouter API 密钥 |
| `AI_API_KEY` | — | 用于兼容 OpenAI 的 endpoint 的通用密钥覆盖 |
| `AI_BASE_URL` | `https://openrouter.ai/api/v1` | 兼容 OpenAI 的 API 基础 URL |
| `AI_MAX_TOKENS` | `3000` | 每次 AI 请求的最大生成 token |
| `AI_TIMEOUT_MS` | `90000` | 上游 AI 请求超时（以毫秒为单位） |
| `CLAWFIX_API_TOKEN` | — | AI endpoint 所需的 Bearer token；设置此项将启用经过身份验证的付费 AI |
| `ALLOW_PUBLIC_AI` | — | 设置为 `1` 以显式启用未经身份验证的付费 AI；默认情况下禁用（即使存在 AI 密钥也是如此） |
| `AI_DAILY_REQUEST_LIMIT` | `200` | 每个进程在付费 AI 诊断和聊天请求中的每日上限；在多个 replica 之间使用提供商支出上限或共享存储 |
| `AI_MAX_CONCURRENCY` | `4` | 共享的最大正在处理的付费 AI 请求数 |
| `DIAGNOSE_RATE_LIMIT` | `10` | 每个客户端在每个速率限制窗口内的诊断请求数 |
| `CHAT_RATE_LIMIT` | `30` | 每个客户端在每个速率限制窗口内的聊天请求数 |
| `RATE_LIMIT_WINDOW_MS` | `60000` | 每个客户端的速率限制窗口 |
| `DATABASE_URL` | — | 用于持久化的 PostgreSQL URL |
## OpenClaw 沙盒实验室
开发实验室会在一次性的 Blaxel 沙盒内配置公共 ClawFix 仓库和固定版本的 OpenClaw 发行版。它有意不上传您的本地工作区或 `.env` 文件。
```
# 创建保留的 sandbox，然后安装 OpenClaw 和公共 ClawFix
npm run lab:create
npm run lab:provision
# 检查版本和状态，或运行可逆的故障场景
npm run lab:status
npm run lab:scenarios
# 停止 keep-alive 进程，同时保留 sandbox 以供后续工作使用
npm run lab:stop
```
使用 `OPENCLAW_LAB_VERSION` 覆盖受测试的 OpenClaw 版本。默认固定为 `2026.6.11`，因为当前 Blaxel 基础镜像的 Node.js `24.11.1` 无法满足 OpenClaw `2026.7.1` 的引擎范围。
场景套件会在 `finally` 块中恢复更改的配置和进程。有关证据矩阵和推荐工具栈，请参阅[开源集成研究](docs/research/open-source-integrations.md)。
## API
| Endpoint | 方法 | 描述 |
|----------|--------|-------------|
| `/` | GET | 着陆页 |
| `/fix` | GET | 诊断 bash 脚本 |
| `/fix/sha256` | GET | 用于验证的脚本哈希 |
| `/api/diagnose` | POST | 提交诊断数据 |
| `/api/fix/:fixId` | GET | 获取修复结果 |
| `/api/stats` | GET | 服务统计信息 |
| `/api/feedback/:fixId` | POST | 报告修复是否有效 |
| `/results/:fixId` | GET | 基于 Web 的结果页面 |
## 定价
**免费。** 在我们研究什么值得收费的同时，每一项功能 — 模式匹配扫描、AI 分析、生成的
修复脚本 — 都是免费的。
我们以后可能会引入付费层级（可能针对大量的 AI 调用采用基于使用量的计费，
或者是托管监控的 SKU）。如果有任何变化，我们会提前发布公告，并为
今天使用该工具的用户提供老用户豁免。
## 维护者
ClawFix 由 [Luis Felipe Abarca](https://github.com/felirami) 和 Arca 的公共 [`arcabotai`](https://github.com/arcabotai) 账户维护。Felipe 编写了 [v0.9.1 修复安全大修](https://github.com/arcabotai/clawfix/pull/4)。[`CODEOWNERS`](.github/CODEOWNERS) 指定了这两个账户进行全仓库审查，而 Arca 的智能体身份以它们自己的公共作者身份进行贡献。
## 许可证
[MIT](LICENSE)
由 [Arca](https://arcabot.ai) (arcabot.eth) 制作 · 与 OpenClaw 无关
标签：AI辅助, GNU通用公共许可证, MITM代理, Node.js, 暗色界面, 测试用例, 自动化运维, 自定义脚本, 诊断工具, 请求拦截