OpenClaw配置管理最佳实践

OpenClaw configuration management best practices and common pitfalls. Use when: (1) User needs to modify OpenClaw configuration, (2) User asks about config paths or structure, (3) User encountered config errors, (4) Adding new providers or channels, (5) Before making any config changes - to avoid common mistakes like wrong paths or direct JSON editing.

Security Scan

The skill is an instruction-only configuration guidance document that is consistent with its stated purpose and does not request extra credentials, installs, or unexpected privileges.

Purpose & Capability

Name and description match the content: the skill provides guidance and examples for viewing and patching OpenClaw configuration. It does not declare unrelated requirements (no binaries, env vars, or installs).

Instruction Scope

SKILL.md limits instructions to reading and patching configuration using gateway commands, consulting a path reference, and validating changes. It does not instruct the agent to read arbitrary system files, collect unrelated data, or call external endpoints beyond the documented gateway CLI commands.

Install Mechanism

No install spec and no code files—instruction-only skills are lowest-risk for disk writes or arbitrary code execution.

Credentials

The skill requests no environment variables, credentials, or config paths. The reference file includes placeholder examples (apiKey, tokens) which are appropriate examples for a config guide and do not imply the skill needs those secrets itself.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request permanent presence or modifications to other skills or system-wide settings.

Assessment

This is a guidance-only skill for safely editing OpenClaw config—it appears coherent and low-risk. Before applying changes: always back up your configuration, prefer gateway config.patch over full apply, and validate with gateway config.get. Never paste real secrets into public chat logs; if you must include tokens in a patch, apply them in a secure environment or use the gateway's secret storage. If you want extra assurance, test changes in a staging instance first.

OpenClaw 配置管理指南

本技能提供 OpenClaw 配置管理的最佳实践，帮助避免常见错误。

⚠️ 黄金法则

永远不要用 write 或 edit 直接修改配置文件！

❌ 错误方式：

• 直接编辑 ~/.openclaw/openclaw.json
• 猜测配置路径（如 plugins.entries.discord.botToken）
• 裸写 JSON 没有验证

✅ 正确方式：

• 使用 gateway config.get 查看当前配置
• 使用 gateway config.patch 做增量修改
• 修改后用 gateway config.get 验证

📋 配置前检查清单

每次修改配置前，按此顺序执行：

1. 读取现有配置

   gateway config.get
   

   目的：确认当前结构，避免猜测路径

2. 确认正确路径 参考 references/common-paths.md 查找正确的配置项路径 原则：不确定时，宁可多看一眼，不要盲猜

3. 使用 patch 修改

   gateway config.patch
   {
     "channels": {
       "discord": {
         "enabled": true,
         "token": "YOUR_TOKEN"
       }
     }
   }
   

4. 验证修改结果

   gateway config.get
   

   确认修改生效，无语法错误

🔥 常见错误案例

错误 1：Discord Token 路径错误

// ❌ 错误路径
{
  "plugins": {
    "entries": {
      "discord": {
        "botToken": "xxx"  // 错误！
      }
    }
  }
}

// ✅ 正确路径
{
  "channels": {
    "discord": {
      "token": "xxx"  // 正确！
    }
  }
}

错误 2：直接覆盖整个配置

// ❌ 危险！会丢失其他所有配置
gateway config.apply
{ ...新配置... }

// ✅ 安全！只修改指定部分
gateway config.patch
{ ...部分配置... }

📚 参考资源

• 配置路径速查表: 见 references/common-paths.md
  • 包含常用配置项的正确路径
  • Provider 配置路径
  • Channel 配置路径
  • Agent 默认配置路径

🛠️ 配置管理命令

命令	用途
gateway config.get	查看当前完整配置
gateway config.patch	增量修改配置（推荐）
gateway config.apply	完全替换配置（危险）
gateway config.schema	查看配置 JSON Schema

💡 最佳实践总结

1. 先读后写 - 永远不要假设配置结构
2. 用 patch 不用 apply - 避免意外覆盖
3. 验证闭环 - 修改后必须验证
4. 参考速查表 - 不确定路径时查 common-paths.md
5. 不要猜测 - 看到实际配置再动手

---

记住：配置错误会导致 OpenClaw 无法启动，务必谨慎！