{"skill":{"slug":"safe-config-workflow-zh-cn","displayName":"Safe Config Workflow","summary":"提供安全修改 OpenClaw 配置的全流程管理，确保变更前确认、自动修复、备份对比及运行验证，保障系统稳定。","description":"# 安全配置流程 (Safe Config Workflow)\n\n## 用途\n\n安全修改 OpenClaw 配置文件，自动执行检查、修复、验证、学习反馈流程。\n\n## 触发条件\n\n当用户要求：\n- 修改配置\n- 更改 Gateway 设置\n- 调整渠道配置\n- 修改模型/会话/认证配置\n- 任何涉及 `~/.openclaw/openclaw.json` 的操作\n\n## 核心原则\n\n1. **先查文档** — https://docs.openclaw.ai/zh-CN\n2. **先参考 config-validator** — 修改前查阅 schema 和有效值\n3. **先确认** — 向用户确认修改内容和影响\n4. **不猜测** — 没文档依据就不做\n5. **要学习** — doctor --fix 后记录教训\n6. **要过滤** — doctor 输出由 AI 过滤，用户只看关键信息\n\n## 反馈策略（两种结合）\n\n| 问题类型 | 处理方式 | 示例 |\n|---|---|---|\n| **小问题**（拼写错误、格式问题） | 自己学习 + 记录 | 不麻烦用户，记录到 MEMORY.md |\n| **重要配置**（影响功能、渠道、认证） | 反馈用户 + 学习 | 让用户知情，避免再次犯错 |\n| **反复出现的错误** | 反馈 + 记录 + 总结 | 形成知识库，永久避免 |\n\n## 执行流程\n\n### 标准流程（99% 情况）\n\n```bash\n# 步骤 0: 查阅 config-validator（修改前参考）\n# 确认字段存在和有效值\n# 查看配置示例\n\n# 步骤 1: 修改配置（先向用户确认）\n# 确认模板：\n# 📋 配置修改确认\n# 修改内容：XXX\n# 原因：XXX\n# 影响：XXX\n# 风险：低/中/高\n# 文档依据：https://docs.openclaw.ai/zh-CN/XXX\n# 是否继续？是/否\n\n# 步骤 2: 检查 + 自动修复\nopenclaw doctor --fix\n# AI 内部过滤关键信息：\n# openclaw doctor --fix 2>&1 | grep -E \"Doctor changes|Normalized|Config overwrite|Backup|Invalid\"\n\n# 步骤 3: 对比备份（必须执行！）\ndiff ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak\n# AI 解读 diff，向用户说明修改内容\n\n# 步骤 4: 记录教训（重要！）\n# 把学到的正确配置值记录到 MEMORY.md\n\n# 步骤 5: 等待热重载\nsleep 3\n# 3 秒是合理的：热重载是进程内重启（SIGUSR1），官方设计为快速应用\n\n# 步骤 6: 验证 Gateway 状态\nopenclaw gateway status\n# 确认 Gateway 正常运行\n```\n\n### 排障流程（如果 Gateway 启动失败）\n\n```bash\n# Gateway 失败 ≠ 机器人瘫痪！\n# 诊断命令仍然可用，因为它们是检查文件系统，不依赖 Gateway RPC\n\n# 步骤 1: 查看日志，了解失败原因\nopenclaw logs --follow\n# 查看错误信息，例如：\n#   - Config validation failed: XXX\n#   - Port 18789 already in use\n#   - Invalid token format\n\n# 步骤 2: 根据日志手动修复配置\nnano ~/.openclaw/openclaw.json\n# 针对性修复发现的问题\n\n# 步骤 3: 再次尝试启动\nopenclaw gateway restart\n\n# 步骤 4: 再次验证\nopenclaw gateway status\n```\n\n## 输出格式\n\n### 修改前确认\n\n```\n📋 配置修改确认\n\n修改内容：XXX\n原因：XXX\n影响：XXX\n风险：低/中/高\n文档依据：https://docs.openclaw.ai/zh-CN/XXX\n\n是否继续？是/否\n```\n\n### doctor --fix 后反馈\n\n**AI 向用户反馈的格式（必须遵守）：**\n\n```\n✅ 配置检查完成\n\n【修复内容】\n- 字段：channels.telegram.streaming\n- 原值：\"invalid_test_value\"（无效）\n- 新值：\"off\"（有效）\n\n【备份位置】\n~/.openclaw/openclaw.json.bak\n\n【其他警告】（与配置无关，可选处理）\n- Node 版本警告：系统 Node 16.5.0，建议升级到 22+\n- 会话记录缺失：1/2 sessions 缺少 transcript\n```\n\n**小问题（不麻烦用户）：**\n```\n✅ 配置检查完成\n\ndoctor 输出：无问题 / 修复了 XXX（小问题，已自动修复）\n\n已记录到：MEMORY.md\n```\n\n**重要配置（反馈用户）：**\n```\n✅ 配置检查完成\n\n【修复内容】\n- 字段：XXX\n- 原值：\"XXX\"（无效）\n- 新值：\"XXX\"（有效）\n\n【学到的知识】\n- 正确值：XXX\n- 含义：XXX\n- 文档：https://docs.openclaw.ai/zh-CN/XXX\n\n⚠️ 注意：XXX（影响说明）\n\n已记录到：MEMORY.md\n```\n\n### 验证结果\n\n```\n✅ Gateway 状态正常\n\nRuntime: running\nRPC probe: ok\n```\n\n### 失败排障\n\n```\n❌ Gateway 启动失败\n\n错误日志：\nXXX（从 logs --follow 获取）\n\n已手动修复：XXX\n正在重启 Gateway...\n\n✅ Gateway 已恢复正常\n```\n\n## doctor --fix 输出解读规则（AI 必须遵守）\n\n### AI 职责：过滤并总结关键信息\n\n**AI 应该执行的过滤（内部处理，用户不需要看）：**\n```bash\nopenclaw doctor --fix 2>&1 | grep -E \"Doctor changes|Normalized|Config overwrite|Backup|Invalid\"\n```\n\n**AI 向用户反馈时明确分类：**\n- **修复项** — Doctor changes、Normalized、Config overwrite\n- **警告项** — Node 版本、会话记录、Skills 状态等\n\n**AI 必须执行的操作：**\n1. 过滤 doctor 输出，提取关键修复信息\n2. 对比备份文件，解读 diff\n3. 向用户反馈修复内容（字段、原值、新值）\n4. 记录教训到 MEMORY.md\n5. 等待 3 秒后验证 Gateway 状态\n\n## 安全规则\n\n1. **修改前必须查文档** — https://docs.openclaw.ai/zh-CN\n2. **修改前必须向用户确认** — 即使是你要求的\n3. **绝不猜测字段值** — 没文档依据就不做\n4. **修复后必须学习** — 记录到 MEMORY.md\n5. **Gateway 失败仍可排障** — 诊断命令不依赖 Gateway\n6. **输出必须过滤** — 用户只看关键信息，杂项由 AI 处理\n\n## 已知局限\n\n| 局限 | 说明 | 应对方案 |\n|---|---|---|\n| doctor 检测不出端口无效 | 端口号格式正确但值无效时 | 手动验证关键配置 |\n| Gateway 有保护机制 | 无效配置时自动回滚默认值 | 修复后验证配置已生效 |\n| Gateway 重启输出不清晰 | 只显示\"missing tool result\" | 查看 logs --follow 确认 |\n\n## 相关文档\n\n- 官方配置文档：https://docs.openclaw.ai/zh-CN/gateway/configuration\n- 官方 doctor 文档：https://docs.openclaw.ai/zh-CN/cli/doctor\n- 官方 Gateway 手册：https://docs.openclaw.ai/zh-CN/gateway/index.md\n- 官方故障排除：https://docs.openclaw.ai/zh-CN/gateway/troubleshooting\n- 官方 FAQ：https://docs.openclaw.ai/zh-CN/help/faq.md\n\n## 版本历史\n\n- v1.0 (2026-02-26) — 初始版本，包含完整流程和反馈策略\n- v1.1 (2026-02-26) — 更新测试验证后的流程，添加输出过滤规则和已知局限\n","tags":{"latest":"1.0.1","chinese":"1.0.0","config":"1.0.0","safety":"1.0.0","workflow":"1.0.0"},"stats":{"comments":0,"downloads":889,"installsAllTime":34,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1772122101393,"updatedAt":1778993462193},"latestVersion":{"version":"1.0.1","createdAt":1772123904256,"changelog":"GitHub 备份版本","license":null},"metadata":null,"owner":{"handle":"nicoxia","userId":"s17axyfdchcnt2xhsjxts9yax5885qty","displayName":"nicoxia","image":"https://avatars.githubusercontent.com/u/7669766?v=4"},"moderation":null}