Skill: nicoxia/safe-config-workflow-zh (version 1.0.0)

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

path: TEST-GUIDE.md
content: # Config Manager Skill 测试指南

## 测试目标

验证配置修改标准化流程的有效性，确保：
1. doctor --fix 能正确检测并修复配置错误
2. 热重载机制正常工作
3. Gateway 状态验证可靠
4. 排障流程在失败时可用

## 测试环境准备

```bash
# 1. 备份当前配置（安全起见）
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.test.backup

# 2. 确认 Gateway 当前状态正常
openclaw gateway status
# 预期：Runtime: running, RPC probe: ok
```

## 测试用例

### 测试 1：安全配置修改（无错误）

**目的：** 验证热重载正常工作

**步骤：**
```bash
# 1. 修改一个安全的配置项（比如添加注释或调整格式）
nano ~/.openclaw/openclaw.json

# 2. 运行 doctor 检查
openclaw doctor --fix

# 3. 等待热重载
sleep 3

# 4. 验证 Gateway 状态
openclaw gateway status
```

**预期结果：**
- doctor 输出：无问题
- Gateway 状态：running

---

### 测试 2：故意制造配置错误

**目的：** 验证 doctor --fix 能检测并修复错误

**步骤：**
```bash
# 1. 故意添加一个无效配置项
nano ~/.openclaw/openclaw.json
# 添加：
# "channels": {
#   "telegram": {
#     "streaming": "invalid_value_test"
#   }
# }

# 2. 运行 doctor 检查
openclaw doctor --fix

# 3. 查看 doctor 输出
# 应该显示修复了什么

# 4. 对比备份
diff ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 5. 验证 Gateway 状态
openclaw gateway status
```

**预期结果：**
- doctor 输出：修复了 channels.telegram.streaming 字段
- diff 显示：从 "invalid_value_test" 改回 "off"（或删除）
- Gateway 状态：running

---

### 测试 3：关键配置错误（Gateway 启动失败）

**⚠️ 警告：这会导致 Gateway 暂时无法运行，仅用于测试排障流程！**

**目的：** 验证 Gateway 失败后诊断命令仍可用，排障流程有效

**步骤：**
```bash
# 1. 备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.critical.backup

# 2. 故意修改关键配置（比如改端口为已占用的）
nano ~/.openclaw/openclaw.json
# 修改：
# "gateway": {
#   "port": 18789  # 改成已占用的端口，或者改一个无效值
# }

# 3. 运行 doctor 检查
openclaw doctor --fix
# 可能检测不出端口冲突

# 4. 强制 Gateway 重新加载（或重启）
openclaw gateway restart

# 5. 验证 Gateway 状态（应该失败）
openclaw gateway status
# 预期：Runtime: not running 或 RPC probe: failed

# 6. 查看日志
openclaw logs --follow
# 应该显示具体错误原因

# 7. 手动修复配置
nano ~/.openclaw/openclaw.json
# 改回正确的端口

# 8. 再次启动
openclaw gateway restart

# 9. 再次验证
openclaw gateway status
# 预期：Runtime: running, RPC probe: ok
```

**预期结果：**
- Gateway 启动失败后，诊断命令（doctor、logs、status）仍可用
- 日志显示具体错误原因
- 手动修复后 Gateway 恢复正常

---

### 测试 4：反馈策略验证

**目的：** 验证两种反馈策略（小问题自己学，重要问题反馈用户）

**步骤：**
```bash
# 1. 小问题测试（拼写错误）
# 修改一个明显的拼写错误，看是否自动修复并记录

# 2. 重要配置测试（影响功能）
# 修改渠道配置，看是否反馈用户并说明影响
```

**预期结果：**
- 小问题：自动修复，记录到 MEMORY.md，不麻烦用户
- 重要问题：反馈用户，说明影响，记录到 MEMORY.md

---

## 测试结果记录

### 测试日期

YYYY-MM-DD

### 测试者

主人 / AI 助手

### 测试用例结果

| 测试用例 | 预期结果 | 实际结果 | 状态 |
|---|---|---|---|
| 测试 1：安全配置修改 | Gateway 正常运行 | | ⬜ 通过 / ⬜ 失败 |
| 测试 2：doctor --fix 修复 | 正确检测并修复 | | ⬜ 通过 / ⬜ 失败 |
| 测试 3：排障流程 | 诊断命令可用，可恢复 | | ⬜ 通过 / ⬜ 失败 |
| 测试 4：反馈策略 | 小问题自学，重要反馈 | | ⬜ 通过 / ⬜ 失败 |

### 发现的问题

- 

### 改进建议

- 

---

## 恢复测试环境

测试完成后，恢复原始配置：

```bash
# 恢复配置
cp ~/.openclaw/openclaw.json.test.backup ~/.openclaw/openclaw.json

# 重启 Gateway
openclaw gateway restart

# 验证状态
openclaw gateway status
```

---

## 注意事项

1. **测试前务必备份配置** — 避免数据丢失
2. **测试 3 会导致 Gateway 暂时不可用** — 选择合适时间测试
3. **记录测试结果** — 用于改进流程
4. **测试后恢复环境** — 不影响正常使用


path: package.json
content: {
  "name": "safe-config-workflow",
  "version": "1.0.0",
  "description": "安全配置流程 - Safe workflow for modifying OpenClaw configuration",
  "keywords": [
    "openclaw",
    "skill",
    "chinese",
    "config",
    "safety",
    "workflow"
  ],
  "author": "Your Name",
  "license": "MIT",
  "openclaw": {
    "type": "skill",
    "language": "zh-CN"
  }
}


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)