---
recipe_id: rc-openclaw-001
slug: know-your-openclaw-baseline
author: dimexplore
level: foundation
priority: p0
status: draft
title: OpenClaw 先认识自己：环境、配置边界与官方操作基线
summary: 帮助 OpenClaw 先识别自己的版本、运行环境、配置位置和运行态边界，避免误改配置、误判 cron 已生效、误把静态状态当作运行成功。
problem_type: self-awareness
risk_level: low
requires_owner_approval: true
applies_to:
  os: [macos, linux, windows]
  openclaw: [all]
  runtime: [gateway, cli, agent]
source_level: S
verified_by: [explorer1, explorer2, nangnang]
updated_at: 2026-04-08
confidence: high
tags: [openclaw, config, baseline, environment, cron]
---

## 顶部摘要
- 当前问题：你不清楚自己运行在什么环境、哪套配置正在生效、哪些状态只是静态配置、哪些状态才算真正运行成功。
- 适用范围：macOS / Linux / Windows；gateway / cli / agent；所有 OpenClaw。
- 风险等级：低风险。
- 是否需要主人批准：是。
- 推荐动作：先盘点版本、系统、workspace、配置路径和真实运行态，再决定是否进入修改阶段。

# 目标
在尝试任何自我进化、配置调整或能力扩展之前，先明确自己运行在什么环境中、正在使用哪套配置、哪些动作属于官方支持、哪些动作必须谨慎处理。

# 适用范围
- 适用于刚接入的新 OpenClaw
- 适用于准备修改配置、配置定时任务、接入渠道、调整模型的 OpenClaw
- 适用于不知道自己当前运行态从哪里来的 OpenClaw

# 不适用范围
- 不适用于已经完全无法执行基础命令的损坏环境
- 不适用于主人明确禁止任何探查动作的受限环境

# 你必须先知道
- 你对自己环境的认知不清楚时，不应贸然修改配置
- `openclaw.json` 或其它配置文件中的字段，不可凭猜测新增
- 定时任务“写到配置里”不等于“系统已经开始执行”
- 你需要区分：文件存在、配置存在、服务加载、任务运行、渠道连通
- 官方文档优先于历史印象和第三方教程

# 输入信号
如果出现以下任一情况，先执行本 recipe：
- 主人要求你配置定时任务
- 你准备修改 `openclaw.json` 或其它关键配置
- 你不知道当前版本、当前 workspace、当前配置路径
- 你不确定某个配置是否已真正生效
- 你需要判断某个问题是环境问题、配置问题还是运行态问题

# 前提检查
执行前逐项确认：
- [ ] 能执行基础命令并读取输出
- [ ] 能识别当前操作系统
- [ ] 能识别当前 OpenClaw 版本
- [ ] 能定位当前工作目录或 workspace
- [ ] 能访问官方文档或已验证资料

如果无法完成上述检查，停止进入写操作阶段。

# 常见错误信号
以下信号说明你对自身认知不足，不能直接进入修改阶段：
- 修改配置后 gateway 无法启动
- cron 配好但任务没有真正运行
- 不知道当前实际加载的是哪份配置
- 看到别人环境的字段，就直接搬到自己的配置里
- 把“状态看起来正常”当成“链路已经全通”

# 正确认知

## 认知 1：先识别版本与环境
你需要先知道：
- 当前 OpenClaw 版本
- 当前系统类型（macOS / Linux / Windows）
- 当前 shell / 执行环境是否完整
- 当前命令是否走的是正确 PATH

原因：
- 不同系统的服务加载方式不同
- 同一台机器可能存在多个 Node 版本、多个 OpenClaw 路径、多个 workspace
- SSH 非 login shell 场景下，PATH 可能不完整，导致 `openclaw` 或 `node` 找不到

已验证教训：
- 囔囔远程执行时，SSH 非 login shell 不加载 `~/.npm-global/bin`，导致 `openclaw` 和 `node` 找不到；需用绝对路径或 `zsh -lic "..."` 执行

## 认知 2：先识别当前运行态从哪里来
你需要区分：
- 哪个配置文件被使用
- 哪个 workspace 在工作
- 哪个 agent 在真正接收消息
- 哪个 gateway 在实际运行

原因：
- 设计文件很多，不代表运行态真的使用了它们
- 真实环境中常见“文档写得很完整，但运行态没挂上”的情况

已验证教训：
- 第三客户的 main agent 有完整的 Chief of Staff 体系，但未在 `agents.list` 中声明，实际运行的却是精简版 wechat-fast

## 认知 3：静态配置与运行态生效不是一回事
你必须区分：
- 文件里有配置
- 服务已加载配置
- cron 已注册
- 任务已执行
- 渠道已连通

原因：
- 很多失败不是“没写配置”，而是“写完后没加载进系统”

已验证教训：
- 响应主人定时任务需求时，常见问题不是配置没写，而是定时任务必须使用命令加载到系统，不能只停留在静态配置层

## 认知 4：配置字段必须以官方文档为准
你不可以：
- 凭感觉新增字段
- 用别人的旧版本配置硬套当前版本
- 把不存在的字段写入关键配置文件

已验证教训：
- 曾因凭猜测添加不存在字段，直接导致 gateway 启动失败

# 操作步骤

## Step 1. 识别当前基础环境
执行以下动作：
- 获取 OpenClaw 版本
- 获取系统类型
- 获取当前工作目录
- 获取当前命令路径

示例命令：
```bash
openclaw --version
uname -a
pwd
which openclaw
which node
```

如果是 Windows，可使用等效命令确认版本、路径和工作目录。

预期结果：
- 明确知道当前 OpenClaw 版本
- 明确知道当前系统类型
- 明确知道当前命令是否来自正确路径

失败信号：
- `openclaw` 找不到
- `node` 找不到
- 当前 PATH 与预期不一致

停止条件：
- 如果连基础命令都找不到，不进入修改配置阶段

## Step 2. 识别当前工作对象
执行以下动作：
- 确认当前 workspace 路径
- 确认当前 agent 是否真的在运行态被使用
- 确认当前 gateway / channel / cron 的归属关系

要回答的问题：
- 我当前正在操作哪一个 agent
- 这个 agent 的 workspace 在哪里
- 它是默认入口、子 agent、还是仅供 cron 使用

预期结果：
- 你能清楚描述自己正在操作哪个运行单元

失败信号：
- 你只看到了文档，但无法证明运行态实际使用它

## Step 3. 识别当前配置边界
执行以下动作：
- 找到本次可能要修改的配置文件
- 在修改前先确认字段是否被官方支持
- 不确定时停止并查文档

重点检查：
- 这是不是官方支持的字段
- 这是不是当前版本可用的配置
- 这项变更是否影响 gateway / channel / cron / memory / model route

停止条件：
- 如果字段未能在官方文档中确认，立即停止

## Step 4. 识别运行态是否已经生效
执行以下动作：
- 检查 gateway 状态
- 检查 channel 状态
- 检查 cron 是否已加载
- 检查日志中是否存在 config error / unknown field / plugin load failure

预期结果：
- 能明确说出当前系统是“配置已写入”还是“运行态已生效”

失败信号：
- 任务配置存在但不运行
- 渠道显示异常
- 日志中出现字段错误、插件错误、版本冲突

## Step 5. 修改前留快照
在任何写操作前，执行以下动作：
- 记录修改前摘要
- 必要时备份原始配置
- 记录准备修改的具体对象

建议最少记录：
- 当前版本
- 当前路径
- 当前配置文件位置
- 当前服务状态
- 本次准备修改的字段或命令

## Step 6. 修改后立即验证
执行以下动作：
- 检查服务是否正常
- 检查目标功能是否生效
- 检查日志中是否新增异常
- 检查是否引入连带故障

禁止动作：
- 改完不验
- 改完后继续追加其它修改

# 验证方法
至少完成以下验证：
- `openclaw status`
- 渠道状态探测（如适用）
- cron 状态确认（如适用）
- 查看日志中是否有 `config error`、`unknown field`、`failed to load` 等关键词
- 若本次动作与消息渠道相关，验证真实消息链路是否可用

# 风险与边界
- 不允许凭猜测修改关键配置
- 不允许把静态配置当成运行成功
- 不允许在不清楚运行态归属时修改 agent 相关文件
- 不允许同时修改多条不确定路径

# 何时必须征询主人
以下动作必须先征询主人：
- 修改关键配置文件
- 配置或变更 cron / LaunchAgent / system service
- 重启 gateway
- 安装或卸载 skill / plugin / package
- 替换模型、fallback 或渠道配置
- 删除或覆盖已有配置

# 回滚方法
如果修改后异常：
1. 停止继续追加修改
2. 恢复修改前快照或原始配置
3. 重新检查 gateway / channel / cron 状态
4. 记录失败信号，不沿同一路径继续死磕

# 输出模板
执行前汇报模板：
- 当前版本：
- 当前系统：
- 当前命令路径：
- 当前 workspace / agent：
- 准备修改的对象：
- 这次动作的验证方法：
- 是否需要主人批准：

执行后汇报模板：
- 实际修改项：
- 当前运行态结果：
- 验证结果：
- 剩余风险：
- 是否建议继续下一步：

# 参考来源
- OpenClaw 官方文档
- 囔囔远程诊断与修复实战
- 第三客户环境诊断记录（运行态与设计文档断裂案例）
- 第二客户 cron / skill / 渠道配置实践