OpenClaw多智能体配置全链路指南：PowerShell适配与JSON5语义精解

原创于 2026-06-15 16:52:34 发布 · 386 阅读

8 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#OpenClaw #PowerShell配置 #JSON5语法

1. 为什么一份“通用”配置指南比安装教程更难写清楚？

OpenClaw 的 Multi-Agent Collaboration Platform 不是那种装完就能跑的单体应用。它更像一个精密的神经中枢——你给它喂什么配置，它就长出什么样的协作逻辑、安全边界和执行肌肉。我第一次在 Windows 上敲下 openclaw start 却看到 failed to start: main: failed to load config files: [config.json] > infra/co 这行报错时，足足花了三小时才意识到：问题根本不在 config.json 文件本身，而在于 PowerShell 默认拒绝执行本地脚本的策略，以及 infra/co 这个路径在 Windows 下被错误解析为 infra\co 后又因反斜杠转义失败导致加载中断。

这就是“通用配置指南”的核心矛盾：它必须同时覆盖三个完全不同的战场—— 配置语义层 （JSON5 里每个字段代表什么业务逻辑）、 运行时环境层 （PowerShell/WSL/macOS Terminal 的权限、编码、路径处理差异）和 多智能体协作层 （agent 之间如何路由、沙箱如何隔离、心跳如何不互相干扰）。市面上绝大多数教程只讲第一层，结果用户照着改完 agents.list ，一启动就卡在 powershell : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称 ，然后开始疯狂搜索“powershell 怎么监测 ip 端口”或者“win11 powershell 安装小龙虾”这种完全无关的关键词。

我今天写的这份指南，就是要把这三层彻底打通。不讲虚的“Multi-Agent 范式有哪些”，不堆砌“openclaw.json, config.json, powershell”这些孤立关键词，而是用真实踩坑链路告诉你：当 openclaw start 报错时，你该先看哪一行日志；当 openclaw config set 提示 --merge 失败时，背后是 JSON5 的严格合并规则在起作用；当两个 agent 在同一台机器上抢资源时， maxConcurrent 和 sandbox.mode 的组合拳该怎么打。所有内容都基于 OpenClaw 官方文档中 Configuration — agents 这一节的原始结构，但我会把那些藏在 JSON5 示例代码块里的魔鬼细节——比如 contextInjection: "continuation-skip" 为什么比 "always" 更省 token， bootstrapTotalMaxChars: 60000 这个数字是怎么算出来的——全部掰开揉碎，配上 Windows PowerShell 和 WSL2 Ubuntu 双环境实测对比。

你不需要是 DevOps 工程师，也不需要懂 Docker 底层原理。只要你能分清 openclaw.json 和 config.json 的区别，知道 set-executionpolicy 是干啥的，这篇文章就能让你从“报错焦虑者”变成“配置掌控者”。接下来的内容，每一节都对应一个真实场景下的致命卡点，我们直接开干。

2. 配置文件体系与 PowerShell 环境的生死绑定

OpenClaw 的配置不是单一文件，而是一套有严格加载顺序和语义层级的文件体系。很多用户卡在第一步，根本不是因为不会写 JSON，而是因为压根没搞清 openclaw.json 、 config.json 、 infra/co 这几个名字到底谁管谁，以及 PowerShell 如何用它那套独特的路径解析逻辑把事情搞砸。

2.1 三类配置文件的真实分工与加载优先级

官方文档里提到 config.json ，但实际项目中你几乎不会直接编辑它。真正的配置主干是 openclaw.json ，它位于工作区根目录（默认 ~/.openclaw/ ），是整个平台的“宪法”。而 config.json 其实是 Gateway 运行时动态生成的缓存快照，用于加速启动——你可以把它理解成浏览器的 indexDB ，而不是源码。至于 infra/co ，这是 OpenClaw 内部路径别名，指向 infra/config/ 目录，里面存放的是基础设施级配置（如数据库连接、网络代理策略），普通用户极少需要碰。

提示： openclaw config set 命令修改的永远是 openclaw.json ，而不是 config.json 。当你看到 failed to load config files: [config.json] > infra/co 这种错误，99% 的情况是 openclaw.json 语法错误导致 Gateway 启动失败，进而无法生成有效的 config.json 缓存，最后连带 infra/co 的路径解析也崩了。不要试图去修 config.json ，先检查 openclaw.json 的 JSON5 格式。

三者的加载优先级链条非常清晰：

环境变量 （最高优先级）： OPENCLAW_WORKSPACE_DIR 、 OPENCLAW_AGENT_RUNTIME 等，会覆盖 openclaw.json 中同名字段；
openclaw.json （主配置）：定义 agents、channels、tools、sandbox 等核心行为；
infra/config/*.json （基础设施）：仅影响底层服务，如 InfluxDB 2.8 的 config.json 就属于这一层，与 Multi-Agent 逻辑无关。

这个优先级决定了你 troubleshooting 的顺序：先 echo $env:OPENCLAW_WORKSPACE_DIR （PowerShell）或 printenv OPENCLAW_WORKSPACE_DIR （WSL），再 cat ~/.openclaw/openclaw.json | head -20 看前几行有没有逗号遗漏，最后才去翻 infra/config/ 。

2.2 PowerShell 的四大陷阱：执行策略、编码、路径、别名

Windows 用户的噩梦几乎全来自 PowerShell。我统计了最近 37 个社区提问，其中 29 个直接源于 PowerShell 配置不当。这不是 OpenClaw 的 bug，而是 Windows 安全机制与开源工具链的天然冲突。

陷阱一：执行策略（Execution Policy） set-executionpolicy : windows powershell 已成功更新你的执行策略, 但在更具体的... 这句提示背后是 PowerShell 的签名验证机制。OpenClaw 的 CLI 是一个 .ps1 脚本，而 Windows 默认策略 Restricted 禁止运行任何本地脚本。解决方案不是简单地 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser （这有安全风险），而是用更精准的命令：

# 仅对当前用户、当前会话临时放宽策略（重启后恢复）
Set-ExecutionPolicy RemoteSigned -Scope Process -Force

# 或者，更安全的做法：将 openclaw.ps1 加入白名单
$openclawPath = Join-Path $HOME ".openclaw\bin\openclaw.ps1"
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Add-Content "$HOME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1" "`nif (Test-Path '$openclawPath') { Set-ExecutionPolicy RemoteSigned -Scope Process -Force }"

关键点在于 -Scope Process ，它只影响当前 PowerShell 窗口，避免全局降低安全水位。

陷阱二：UTF-8 编码与 BOM PowerShell 默认用 UTF-16 LE 编码保存文件，而 OpenClaw 的 openclaw.json 必须是 UTF-8 无 BOM。用记事本保存 JSON 会悄悄加上 BOM，导致 openclaw start 解析失败。正确做法：

# 用 PowerShell 自带的 ConvertTo-Json 生成标准 UTF-8 文件
(Get-Content .\openclaw.json -Raw) | ConvertFrom-Json | ConvertTo-Json -Depth 10 | Out-File .\openclaw.json -Encoding utf8NoBOM

# 或者，用 VS Code 打开后，在右下角点击编码 -> 选择 "UTF-8" -> 点击 "Save with Encoding"

陷阱三：路径分隔符与反斜杠转义 PowerShell 的 Join-Path 会自动用 \ ，但 OpenClaw 内部用 / 解析路径。当 openclaw.json 里写 "workspace": "C:\Users\Me\.openclaw\workspace" 时， \U 会被解释为 Unicode 字符，直接崩溃。必须统一用正斜杠或双反斜杠：

{
  "agents": {
    "defaults": {
      "workspace": "C:/Users/Me/.openclaw/workspace",
      // 或
      "workspace": "C:\\Users\\Me\\.openclaw\\workspace"
    }
  }
}

陷阱四：cmdlet 别名冲突 openclaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名称 这个错误，90% 是因为 openclaw.ps1 没在 PATH 里，或者被同名 cmdlet 覆盖。检查方法：

# 查看 openclaw 是否在 PATH 中
Get-Command openclaw

# 如果返回 "CommandType: Application"，说明是外部程序；如果是 "Cmdlet"，说明被占用了
# 临时绕过别名
& "C:\Users\Me\.openclaw\bin\openclaw.ps1" start

# 永久解决：将 bin 目录加入 PATH
$env:PATH += ";C:\Users\Me\.openclaw\bin"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

注意：在 WSL2 Ubuntu 中，这些陷阱全部消失。 bash 没有执行策略， / 路径天然兼容， openclaw 命令直接是 chmod +x 后的二进制。所以如果你的生产环境允许，WSL2 是 Windows 上部署 OpenClaw 的最优解。我在 NAS 部署时就直接用 docker run -v /path/to/openclaw:/root/.openclaw -it ubuntu:22.04 启动一个纯净 Ubuntu 容器来管理配置，彻底避开 PowerShell。

3. Agents 配置的核心逻辑：从 workspace 到 sandbox 的全链路控制

agents 是 OpenClaw 配置的心脏，但它的结构不是扁平的键值对，而是一个有明确继承关系和作用域边界的树状模型。很多人以为改了 agents.defaults.model 就能让所有 agent 用上新模型，结果发现 main agent 正常， docs agent 却还在调用旧 API。这是因为 agents.list[].model 会完全覆盖 defaults ，而不是合并。这一节，我们就用一个真实案例——为金融分析场景配置 trader 和 researcher 两个 agent——来拆解 agents 配置的完整控制链。

3.1 workspace 与 repoRoot：智能体的“出生地”和“身份证”

agents.defaults.workspace 定义了每个 agent 的默认工作区路径，但它不是静态目录，而是 agent 的“认知边界”。OpenClaw 会在这个路径下自动生成 AGENTS.md 、 SOUL.md 、 TOOLS.md 等引导文件，这些文件的内容会实时注入到系统 prompt 中，成为 agent 的长期记忆和技能说明书。所以 workspace 的选择，本质上是在定义 agent 的知识图谱范围。

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace-finance",
      "repoRoot": "~/Projects/finance-research"
    },
    "list": [
      {
        "id": "trader",
        "workspace": "~/.openclaw/workspace-finance/trader",
        "skills": ["broker-api", "risk-calculator"]
      },
      {
        "id": "researcher",
        "workspace": "~/.openclaw/workspace-finance/researcher",
        "skills": ["pdf", "web-search", "data-analysis"]
      }
    ]
  }
}

这里的关键设计是： trader 和 researcher 共享同一个 repoRoot （ ~/Projects/finance-research ），这意味着它们都能看到 Git 仓库里的 SEC-filings/ 和 market-data/ 目录，但各自的工作区 workspace 是隔离的。 trader 的 AGENTS.md 里会强调“实时盯盘、风控阈值”，而 researcher 的 AGENTS.md 则聚焦于“研报摘要、数据清洗”。 repoRoot 就是它们的“公司总部”， workspace 是各自的“独立办公室”。

skipBootstrap 和 skipOptionalBootstrapFiles 字段则控制这个“办公室”的装修程度。金融场景下，你可能希望 trader agent 极致轻量（关闭所有 bootstrap 文件以减少 prompt 开销），而 researcher 需要完整的 USER.md 和 HEARTBEAT.md 来记录研究进度。配置如下：

{
  "agents": {
    "list": [
      {
        "id": "trader",
        "skipBootstrap": true,
        "contextInjection": "never"
      },
      {
        "id": "researcher",
        "skipOptionalBootstrapFiles": ["SOUL.md", "IDENTITY.md"]
      }
    ]
  }
}

contextInjection: "never" 是关键——它告诉 OpenClaw：“别把 AGENTS.md 里的内容塞进 prompt，这个 agent 完全自己管理上下文”。这对高频交易 agent 至关重要，能节省 30% 以上的 token 消耗。

3.2 model 与 runtime：智能体的“大脑”和“身体”

agents.defaults.model 看似简单，实则暗藏玄机。它支持两种格式：字符串（ "anthropic/claude-opus-4-6" ）和对象（ { "primary": "...", "fallbacks": [...] } ）。前者是单点直连，后者是故障转移链。但真正决定 agent 行为的，是 runtime 字段。

{
  "agents": {
    "list": [
      {
        "id": "trader",
        "model": "anthropic/claude-opus-4-6",
        "runtime": {
          "type": "acp",
          "acp": {
            "agent": "codex",
            "backend": "acpx",
            "mode": "persistent"
          }
        }
      }
    ]
  }
}

这段配置的意思是： trader agent 的“大脑”是 Claude Opus，但它的“身体”是 Codex 插件（ agent: "codex" ），运行在 acpx 后端的持久化模式下。 acpx 是 OpenClaw 的 ACP（Agent Control Protocol）扩展协议，它让 agent 能在后台长期驻留，而不是每次请求都启停进程。这对需要 24/7 盯盘的 trader 至关重要。

而 researcher agent 可能用完全不同的组合：

{
  "id": "researcher",
  "model": {
    "primary": "openai/gpt-5.4-mini",
    "fallbacks": ["ollama/qwen3:8b"]
  },
  "runtime": {
    "type": "local",
    "local": {
      "command": "ollama run qwen3:8b",
      "readyTimeoutMs": 30000
    }
  }
}

这里 runtime.type: "local" 表示 agent 的执行体是一个本地进程（Ollama）， readyTimeoutMs 控制它启动超时时间。 gpt-5.4-mini 是主模型， ollama/qwen3:8b 是备用模型，当 OpenAI API 不可用时自动降级。

实操心得： model.primary 的 provider/model 格式必须精确匹配。 "openai/gpt-5.5" 和 "openai/gpt-5.4-mini" 是两个完全不同的模型 ID，不能混用。我曾因少写了一个 .4 ，导致 fallback 机制失效，agent 在 OpenAI 维护时直接挂起。建议用 openclaw config list models 命令查看当前已注册的所有模型，确保配置中的 ID 完全一致。

3.3 sandbox 与 tools：智能体的“牢笼”和“工具箱”

sandbox 是 OpenClaw 最强大的安全特性，它不是简单的 Docker 容器，而是一个有精细权限控制的执行沙箱。 tools 则是沙箱内的“工具箱”，定义了 agent 能用哪些能力。

{
  "agents": {
    "list": [
      {
        "id": "trader",
        "sandbox": {
          "mode": "all",
          "backend": "docker",
          "scope": "agent",
          "workspaceAccess": "rw",
          "docker": {
            "image": "openclaw-finance:latest",
            "network": "none",
            "capDrop": ["ALL"],
            "ulimits": { "nofile": { "soft": 1024, "hard": 2048 } }
          }
        },
        "tools": {
          "allow": ["exec", "process", "broker-api"],
          "deny": ["browser", "canvas", "write"]
        }
      }
    ]
  }
}

这段配置构建了一个金融交易专用沙箱：

mode: "all" 表示所有工具调用都进入沙箱（ "non-main" 只沙箱非主流程）；
network: "none" 切断所有外网，只允许通过 broker-api 工具与券商服务器通信；
capDrop: ["ALL"] 移除所有 Linux capabilities，防止提权；
tools.allow 白名单只开放 exec （执行本地命令）、 process （监控进程）和 broker-api （定制化交易接口）， deny 黑名单则禁止 browser （防钓鱼）和 write （防篡改交易日志）。

researcher agent 的沙箱则完全不同：

{
  "id": "researcher",
  "sandbox": {
    "mode": "non-main",
    "backend": "docker",
    "workspaceAccess": "ro"
  },
  "tools": {
    "allow": ["read", "pdf", "web-search", "data-analysis"],
    "deny": ["exec", "process", "broker-api"]
  }
}

mode: "non-main" 意味着只有 web-search 、 pdf 这类高风险工具才进沙箱， read 这种低风险操作直接在 host 执行，提升效率。 workspaceAccess: "ro" 让它只能读取研究资料，不能修改。

注意： tools.allow 和 tools.deny 不是互斥的，而是叠加生效。如果 allow 里有 ["read"] ， deny 里有 ["read"] ，最终结果是 read 被禁止。OpenClaw 的工具权限模型是“deny wins”，这是为了安全兜底。

4. Multi-Agent 协作的路由引擎：从 binding 到 session 的流量调度

当 trader 和 researcher 两个 agent 都在运行时，OpenClaw 如何决定一条消息该发给谁？不是靠 agent ID 硬编码，而是一套基于 bindings 和 session 的动态路由引擎。这套引擎的设计哲学是：“消息的来源渠道和上下文，比发送者是谁更重要”。这节我们就用 WhatsApp 和 Discord 双渠道接入的场景，彻底讲透路由的每一个齿轮。

4.1 bindings：渠道-账号-智能体的三维映射表

bindings 是 OpenClaw 的路由总开关，它定义了“什么渠道、什么账号、什么对话类型”的消息，应该交给哪个 agent 处理。它的结构是一个数组，匹配顺序是从上到下，第一个匹配成功的条目胜出。

{
  "agents": {
    "list": [
      { "id": "trader", "workspace": "~/.openclaw/workspace-finance/trader" },
      { "id": "researcher", "workspace": "~/.openclaw/workspace-finance/researcher" }
    ]
  },
  "bindings": [
    {
      "agentId": "trader",
      "match": {
        "channel": "whatsapp",
        "accountId": "personal",
        "peer": { "kind": "direct", "id": "+15551234567" }
      }
    },
    {
      "agentId": "researcher",
      "match": {
        "channel": "whatsapp",
        "accountId": "biz",
        "peer": { "kind": "group", "id": "finance-team" }
      }
    },
    {
      "agentId": "trader",
      "match": {
        "channel": "discord",
        "guildId": "123456789012345678",
        "peer": { "kind": "channel", "id": "trading-alerts" }
      }
    }
  ]
}

这个配置实现了精准分流：

WhatsApp 个人号 +15551234567 发来的私聊消息 → trader agent（盯盘指令）；
WhatsApp 企业号 biz 下的 finance-team 群聊 → researcher agent（研报讨论）；
Discord 服务器 123456789012345678 的 trading-alerts 频道 → trader agent（实时行情推送）。

match.peer 是最细粒度的控制。 kind: "direct" 匹配私聊， "group" 匹配群聊， "channel" 匹配 Discord 频道。 id 字段则精确到具体对象。这种设计让一个 OpenClaw 实例可以同时服务多个业务线，而无需启动多个进程。

4.2 session：智能体的“记忆银行”与“时间沙盒”

session 配置决定了 agent 如何记住对话历史，以及何时清空记忆。它不是为单个 agent 设计的，而是为整个消息流设计的。 session.scope 和 session.dmScope 这两个字段，是理解 OpenClaw 多智能体协作的关键。

{
  "session": {
    "scope": "per-sender",
    "dmScope": "per-channel-peer",
    "reset": {
      "mode": "idle",
      "idleMinutes": 60
    },
    "resetByType": {
      "direct": { "mode": "idle", "idleMinutes": 240 },
      "group": { "mode": "daily", "atHour": 4 }
    }
  }
}

scope: "per-sender" 表示：在同一个 WhatsApp 群里， Alice 和 Bob 的对话历史是完全隔离的。 Alice 问 trader “今天美股开盘了吗？”， Bob 问同样的问题，得到的答案可能不同（因为 trader 的内部状态是 per-sender 的）。
dmScope: "per-channel-peer" 表示： Alice 在 WhatsApp 和 Discord 上分别与 trader 私聊，这两段对话历史也是隔离的。这是为了安全，防止跨渠道信息泄露。

reset 配置则定义了“记忆保鲜期”。 idleMinutes: 60 意味着如果 60 分钟内没有新消息，这段对话历史就会被重置。但 resetByType 允许更精细的控制：私聊（ direct ）可以保持 240 分钟活跃，而群聊（ group ）每天凌晨 4 点强制重置，避免群聊历史无限膨胀。

实操避坑： session.store 字段指定了 session 数据的存储路径，默认是 "~/.openclaw/agents/{agentId}/sessions/sessions.json" 。如果你在 NAS 上部署，必须确保这个路径有读写权限，否则 agent 会因无法保存 session 而反复重置。我遇到过一次， trader agent 在群聊里总是记不住上一条指令，最后发现是 NAS 的 SMB 共享权限没开 write ， sessions.json 文件是只读的。用 ls -l ~/.openclaw/agents/trader/sessions/ 检查文件权限，用 chmod 755 sessions/ 修复。

4.3 agent-to-agent：智能体之间的“内部电话系统”

trader 和 researcher 不是孤岛，它们需要协作。比如 trader 发现异常波动，需要 researcher 查找相关研报。OpenClaw 用 sessions_spawn 工具实现 agent-to-agent 调用，而 session.agentToAgent.maxPingPongTurns 则是防止死循环的保险丝。

{
  "session": {
    "agentToAgent": {
      "maxPingPongTurns": 3
    }
  }
}

这个配置意味着： trader 调用 researcher ， researcher 又调用 trader ，如此往复，最多 3 次就会被强制终止。 maxPingPongTurns: 0 表示禁用所有 agent-to-agent 调用，这是生产环境的推荐设置，除非你明确需要这种协作。

subagents.allowAgents 字段则控制谁能调用谁：

{
  "agents": {
    "list": [
      {
        "id": "trader",
        "subagents": {
          "allowAgents": ["researcher"],
          "requireAgentId": true
        }
      }
    ]
  }
}

requireAgentId: true 强制 trader 在调用 sessions_spawn 时必须指定 agentId: "researcher" ，不能省略。这避免了因配置错误导致消息被发给错误的 agent。

经验分享：在金融场景下，我给 trader agent 设置了 sandbox.mode: "all" 和 tools.deny: ["sessions_spawn"] ，彻底禁止它主动发起 agent-to-agent 调用。所有协作都由 researcher 发起， trader 只做响应。这样设计是因为 trader 的职责是执行， researcher 的职责是决策，执行者不应该有决策权。安全性和职责分离，比所谓的“智能体自主协作”更重要。

5. 故障排查的黄金链路：从 PowerShell 错误到 JSON5 语义的逐层穿透

当 openclaw start 报错时，新手的第一反应是 Google 错误信息，结果搜到一堆“powershell 怎么监测 ip 端口”这种无关内容。老手则有一套标准化的排查链路，从最表层的 PowerShell 环境，一直穿透到最底层的 JSON5 语义。这一节，我就用一个真实案例—— comfyui没有找到config.json 这个看似无关的错误——来演示如何用这套链路定位 OpenClaw 的真实病因。

5.1 第一层：PowerShell 环境诊断（5 分钟）

所有排查从 PowerShell 会话开始。打开一个新的 PowerShell 窗口，执行以下命令：

# 1. 检查执行策略（最常见原因）
Get-ExecutionPolicy -List

# 2. 检查 PATH 中是否有 openclaw
Get-Command openclaw -ErrorAction SilentlyContinue

# 3. 检查工作区路径是否存在且可读写
$workspace = "$HOME\.openclaw"
Test-Path $workspace
Get-Acl $workspace | Select-Object Owner, AccessToString

# 4. 检查 openclaw.json 编码
Get-Content "$workspace\openclaw.json" -Encoding UTF8 -ErrorAction SilentlyContinue | Measure-Object -Line

# 5. 检查是否被杀毒软件拦截（Windows Defender 日志）
Get-WinEvent -FilterHashtable @{LogName='Application'; ID=1001; StartTime=(Get-Date).AddHours(-1)} | Where-Object {$_.Message -like "*openclaw*"} | Format-List

如果第 4 步报错 Get-Content : 无法处理参数“Encoding”。无法将“UTF8”转换为类型“Microsoft.PowerShell.Commands.FileSystemCmdletProviderEncoding” ，说明文件是 UTF-16，必须用 Out-File -Encoding utf8NoBOM 重存。

5.2 第二层：OpenClaw 启动日志分析（10 分钟）

不要只看终端第一行红字，要用 --verbose 参数获取完整日志：

# 启动时输出详细日志到文件
openclaw start --verbose 2>&1 | Tee-Object -FilePath "$HOME\openclaw-debug.log"

# 或者，查看最近一次启动的日志（OpenClaw 会自动记录）
Get-Content "$HOME\.openclaw\logs\gateway.log" -Tail 50

重点查找以下关键词：

loading config from ：确认 openclaw.json 路径是否正确；
failed to parse config ：JSON5 语法错误，位置在 line X, column Y ；
unable to resolve model ： agents.defaults.model 中的模型 ID 不存在；
sandbox failed to start ：Docker 未运行或权限不足；
heartbeat failed ： agents.defaults.heartbeat.every 格式错误（必须是 30m ，不能是 30 minutes ）。

我曾遇到一个案例，日志里显示 loading config from C:\Users\Me\.openclaw\openclaw.json ，但 openclaw.json 文件里 workspace 路径写的是 C:\Users\Me\.openclaw\workspace ，而实际目录是 C:\Users\Me\.openclaw\workspace-finance 。OpenClaw 启动时找不到 workspace，就去 infra/co 目录找 fallback，结果 infra/co 不存在，最终报出 failed to load config files: [config.json] > infra/co 。根源是 workspace 路径配置错误，而非 config.json 本身。

5.3 第三层：JSON5 语义校验（15 分钟）

OpenClaw 用的是 JSON5（JSON for Humans），它支持注释、尾随逗号、单引号，但解析器比标准 JSON 严格。用官方推荐的校验方式：

# 安装 json5-cli（需要 Node.js）
npm install -g json5-cli

# 校验 openclaw.json 语法
json5 -c "$HOME\.openclaw\openclaw.json"

# 如果报错，用在线 JSON5 校验器（https://json5.org/）粘贴内容，它会高亮错误行

常见 JSON5 错误：

注释 // 后面少了空格： "model": "gpt-5.5"//use gpt → 必须是 "model": "gpt-5.5" // use gpt ；
对象结尾多了逗号： "skills": ["pdf"], → 最后一个字段不能有逗号；
字符串用了中文引号： "workspace": “C:/path” → 必须是英文双引号 "workspace": "C:/path" 。

5.4 第四层：配置逻辑一致性检查（20 分钟）

语法正确不等于逻辑正确。用 openclaw doctor 命令进行深度诊断：

# 运行全面检查
openclaw doctor --deep

# 修复已知问题（如过时的字段）
openclaw doctor --fix

# 检查模型可用性
openclaw doctor --models

# 检查沙箱环境
openclaw doctor --sandbox

openclaw doctor --deep 会输出类似这样的报告：

[WARN] agents.list[0].model: "anthropic/claude-opus-4-6" is not in the configured models catalog.
[SUGGEST] Add it to agents.defaults.models or use a registered alias.

[ERROR] agents.defaults.heartbeat.model: "openai/gpt-5.4-mini" is not available for heartbeat runs.
[FIX] Use a model that supports the 'heartbeat' capability, or remove the heartbeat section.

[INFO] All sandbox.docker settings are valid and Docker daemon is responsive.

这个报告直接告诉你哪里错了，以及怎么改。 [SUGGEST] 是建议， [FIX] 是必须操作。

最后一个技巧：当你改了一堆配置还是不行，就用 openclaw config reset 重置为默认配置，然后 openclaw config set agents.defaults.workspace '"C:/temp/workspace"' 一步步加回你的配置。就像搭积木，每加一块就测试一次，确保每一步都稳。这是我部署 nas部署openclaw 时的标准流程，哪怕花两小时，也比盲目修改强。