说实话OpenClaw 的命令我第一次看的时候只觉得杂乱——run、watch、fork放在一起scan、mirror、diff又凑成一组不翻手册根本记不住谁管谁。后来用熟了才明白这套命令表面上是给终端用户敲的实际上是一套面向任务生命周期的操作协议创建任务、观察进度、调整配置、汇总结果每一步都有对应的动词。这篇笔记按我自己的使用习惯把 OpenClaw 常见命令整理了一遍每条命令都附上作用和说明——不仅告诉你它干什么还写上我实际使用时的注释哪些地方容易踩坑、哪些场合千万别用。如果你刚接触 OpenClaw拿这篇当目录配合help命令实践比死记硬背效率高得多。1. 先弄明白命令体系的划分再去背命令1.1 OpenClaw 命令背后的分类逻辑OpenClaw 官方文档把命令列得很全但初学者最大的问题不是命令多而是不知道命令和命令之间的关系。我自己把常用命令按用途分成五组任务控制、文件与工作区、配置管理、输出集成、权限与审计。这么一分命令就不再是散点而是对应到你在终端里的真实操作。最常见的误解是以为run就是 OpenClaw 的全部。实际上 OpenClaw 的设计思路更像一个任务管理器 文件工具箱的组合run负责把任务定义执行起来watch负责盯执行过程fork负责基于已有任务做变体而scan、mirror、diff这类命令是独立的文件操作能力可以单独使用也可以被任务步骤调用。理解这层关系之后你会发现一个规律OpenClaw 里大部分动词都是英文原义直译run就是跑起来、pause就是暂停、scan就是扫描。少部分容易混淆的组合反而出在那些看起来功能相近的动词上比如scan和mirror的区别后面我会专门讲。1.2 通用语法一组命令全部遵循的骨架OpenClaw 的命令语法统一只要你记住一个骨架剩下全是填词openclaw 动词 对象 [标记]动词决定操作类型比如run、scan、config。对象决定作用范围可以是任务名、目录路径、配置键名。标记控制细节常见的有--format、--scope、--output-file。举个例子执行一个名为release-build的任务同时要求输出 JSON 格式、只预演不真正执行openclaw run release-build --format json --dry-run这个骨架的好处是当你拿到一个没见过的命令比如openclaw profiles validate你也能立刻猜到它的行为——动词是validate校验对象是profiles配置集合起来就是校验当前配置集是否合法。这种命名一致性让学习成本大幅下降我第一次用 OpenClaw 时基本没看文档就猜中了大部分命令的用法。1.3 帮助信息怎么读最有效率OpenClaw 有两个帮助入口用途完全不同openclaw help 命令 # 查看命令的参数说明和示例 openclaw 命令 --explain # 在不执行的情况下输出该命令会做什么help很好理解就是命令行版的说明书。但--explain是个容易被忽略的好东西它会打印出命令将要操作的路径、会读取哪些配置文件、会生成哪些临时文件、可能返回哪些退出码。我在调试复杂命令时习惯先加--explain跑一遍确认影响范围没问题再去掉标记真正执行。提示拿不准一个命令会不会影响线上数据时先加--explain。它会明确告诉你这条命令是只读操作还是写操作。比如openclaw scan --explain会显示即将扫描以下目录并生成清单文件不修改任何源文件。2. 高频命令任务控制与文件操作最高频的其实是这几个2.1 任务执行三兄弟run、watch、fork先看run。它是 OpenClaw 使用频率最高的命令作用是执行一个任务定义openclaw run 任务名 [--from 步骤名] [--dry-run] [--format json]--from是我强烈推荐你记住的标记。如果某个任务包含 10 个步骤前 4 步已经跑完中间断了你重新执行时不需要从头再来——openclaw run build --from step5会直接从第 5 步继续。这个能力在长时间任务中太实用了省下来的时间相当可观。--dry-run是预演模式只打印将要执行的步骤不真正做事。凡是涉及执行后不可逆的操作比如mirror同步、批量改名我都会先--dry-run再看输出的计划清单。接着是watch它的作用是把任务执行过程变成实时视图openclaw watch 任务名watch和run的区别在于run是前台跑完即结束watch则一直挂在那里刷新步骤状态适合任务执行时间比较长、你想实时看到进度的情况。它也能用来观察别人或另一个终端启动的任务带有一定的协作性质。最后是fork用途是基于现有任务副本生成新任务openclaw fork 任务名 [--to 新任务名]fork适用于我想改一个小参数然后跑一版的场景。比如原有的daily-backup任务备份两个目录今天想临时加上第三个目录直接fork一份改成三目录版本不用动原任务。三者对比命令作用典型用法会不会创建新任务run执行指定任务跑一遍部署流程不会watch实时观察任务进度盯着一个长任务跑完不会fork复制任务生成新任务基于原任务改参数后另跑一版会2.2 任务生命周期控制pause、resume、cancel任务一旦跑起来怎么让它停下、暂时挂起、或者彻底终止用是这三个命令openclaw pause 任务名 # 挂起任务进程还在可以恢复 openclaw resume 任务名 # 从挂起点继续执行 openclaw cancel 任务名 # 终止任务生成停止快照很多人分不清pause和cancel的区别。我打个比方pause是看视频按了暂停键画面冻结在原地按下播放就能继续cancel是直接关掉播放器再想看只能重新打开文件。cancel会生成一个终止快照记录任务停止时已经完成了哪些步骤、哪些步骤还没开始、当时的临时文件在哪。这个快照对排查为什么任务执行到一半失败非常重要。如果你希望终止任务的同时把已经完成的部分还原掉可以用openclaw cancel 任务名 --rollback--rollback会尝试把任务执行过程中改动过的文件恢复到执行前状态。注意它只能回滚被 OpenClaw 标记为可回滚的文件操作对于那些调用了外部脚本、你手动改过的内容它管不了。我把rollback当成最后一道保险而不是常规手段。2.3 文件与工作区命令scan、mirror、diff这三个命令独立于任务系统直接操作文件系统也是日常用得最频繁的一组。scan的作用是扫描目录结构并生成清单文件openclaw scan 目录 [--glob **/*.png] [--exclude tmp] [--format json]它默认会输出目录下所有文件的相对路径、大小、修改时间支持正则过滤。我有一次需要统计一个项目里资源目录的图片数量和各子目录占用空间一条scan就把清单生成好了配合--format json再丢给脚本统计全程不用写一段 Python。mirror是目录镜像同步openclaw mirror 源目录 目标目录 [--incremental]默认是全量镜像把源目录内容完整复制到目标目录目标目录里多余的文件会被删除。加上--incremental后它会按文件哈希比对只复制变化的部分。这个命令我常用来做发布产物同步——把构建目录同步到部署目录。但务必记住mirror会删除目标目录里源目录没有的文件所以第一次使用前先--dry-run看清楚它会删什么。diff是目录或清单文件对比openclaw diff 路径A 路径B路径可以是两个目录也可以是两份scan生成的清单文件。diff特别适合回答两个版本的环境到底差在哪这类问题。一个细节默认情况下它忽略文件权限位变化只关注内容差异。如果需要连权限位一起对比加--mode strict标记。实际用下来scan、mirror、diff经常组合出现先scan生成基线清单隔一段时间再scan生成新清单最后diff两份清单看变化。我在整理素材目录时就用这个组合做每周新增文件巡检完全不需要额外工具。3. 配置命令初始化、参数查询与多环境切换3.1 init 之后目录里到底有什么第一次安装 OpenClaw第一件事是初始化配置目录openclaw init命令会在你的用户目录下创建~/.openclaw/文件夹默认结构是这样的~/.openclaw/ ├── config.toml # 主配置文件 ├── profiles/ # 多环境配置集 ├── hooks/ # 生命周期钩子脚本 ├── cache/ # 缓存目录 └── tmp/ # 临时文件目录其中config.toml是核心你可以手动编辑它也可以用config set命令修改。hooks/里放的是任务生命周期钩子比如某个任务执行前需要先拉取远程清单可以在hooks/pre-run目录放一个脚本。cache/和tmp/是运行时用的前者存索引缓存后者存执行过程中的中间文件。我建议 init 完之后先不要急着改配置而是跑一遍openclaw doctor它会检查配置文件语法、目录权限、依赖命令是否存在、磁盘剩余空间是否足够。我第一次用的时候就是靠doctor发现python3版本太老导致某些任务步骤无法执行。3.2 config get、set 与配置优先级查询和修改配置参数用这两个命令openclaw config get 键名 openclaw config set 键名 值比如把默认输出格式改成 JSONopenclaw config set output.format json配置值的来源优先级从高到低是优先级配置来源示例1命令行标记--format json2环境变量OPENCLAW_FORMATjson3项目级配置项目目录下的.openclaw/config.toml4用户级配置~/.openclaw/config.toml5内置默认值安装包自带的默认参数这个优先级顺序意味着你在命令行加的--format json会临时覆盖环境变量和配置文件里的设置但这个覆盖只对当前命令生效不会写进任何配置文件。理解了这一点就不会出现我明明配置了输出格式为什么命令行表现不一样的困惑。config get后面可以直接跟键名逐级查询也可以一次列出整个配置结构。我会在需要确认当前生效配置时用openclaw config get打印全部基本代替了去翻配置文件的工作。3.3 profiles 多环境切换如果你的工作任务需要在不同环境间切换比如开发环境、测试环境、生产环境各自有不同的目标目录、不同的参数那就需要 profilesopenclaw profiles list # 查看当前有哪些配置集 openclaw profiles use 名称 # 切换到指定配置集 openclaw profiles validate # 校验当前配置集是否合法每个 profile 是~/.openclaw/profiles/下的一个独立文件里面可以存任意配置项覆盖全局配置。切换后后续命令自动使用该配置集内的参数。我常用的做法是给每个环境建一个 profile里面只写差异项# profiles/prod.toml output.format json tasks.deploy.auto_approve false用profiles use prod切到生产环境配置切回开发环境就profiles use dev。这样的好处是主配置文件保持精简环境差异单独管理不容易误操作。3.4 doctor 环境自检到底查了什么openclaw doctor我把它称作命令前的体检。它比你想的查得细OpenClaw 自身版本和配置文件语法是否正常任务依赖的外部命令比如git、rsync、python3是否存在且版本达标配置目录、缓存目录、临时目录的读写权限磁盘剩余空间是否低于安全阈值系统时间同步状态每项检查都会输出正常 / 异常的标记异常项会附带修复建议。比如目录权限不对它会提示需要执行chmod的具体命令。它还支持自动修复模式openclaw doctor --fix--fix只会修复那些可以安全自动处理的问题比如缺失的目录创建、权限修正不会动你的业务配置。我每更新一次 OpenClaw 版本都会先跑一遍doctor --fix确保环境没问题。4. 输出与集成命令把结果接进自己的自动化流程4.1 三种输出格式的取舍OpenClaw 的大多数查询类命令都支持三种输出格式用--format切换格式适合场景优点缺点table直接在终端看直观对齐整齐不方便程序解析json管道传给脚本处理结构完整可编程处理打印出来占屏幕yaml生成配置文件或交接给其他系统可读性较好注释友好解析依赖 yq 等工具我的经验是人看的用 table机器处理的用 json跨系统交接的用 yaml。别混着来。有一个场景很典型把scan的 JSON 输出直接喂给jq提取文件大小openclaw scan ./dist --format json | jq .files[] | select(.size 1048576)一个命令就能筛出所有大于 1MB 的文件清单。如果你不开--format jsonjq解析的是对齐后的表格文本结果一定是错的。4.2 静默模式与关闭进度条在终端里跑交互式命令、看进度条没有问题但在 CI 脚本里调用时进度条和彩色输出会让日志变得一团糟。这时候用openclaw run 任务名 --quiet --progress off--quiet会尽量减少标准输出只保留必要的结果信息--progress off显式关闭进度条。两者可以单独用也可以组合。我在编写自动化脚本时固定加这两个标记输出的日志干净很多。4.3 report 和 export 有什么区别两个命令都是输出结果但侧重点不同openclaw report [周报|月报] --format markdown --output-file weekly.md openclaw export 任务名 --format yaml --output-file task-backup.yamlreport生成的是关于任务执行情况的汇总报告比如本周哪些任务成功了、哪些失败了、耗时多少、耗时最长的是哪个步骤。它适合做周期性巡检我把一条报告命令做成了每周一的例行脚本跑完直接出一条 Markdown 结果贴进周报。export导出的是任务定义本身或者审计摘要作用是备份、迁移、分享。换电脑或换环境时用export把任务定义导出来再在新环境导入比重新手写任务配置省事得多。4.4 Shell 脚本里调用 OpenClaw 的几个建议在脚本里调用时有四个细节直接影响你的脚本是否健壮第一用--output-file代替管道解析。输出内容多的时候管道解析容易截断或混入进度信息。写文件是最稳妥的openclaw scan ./src --format json --output-file manifest.json第二用set e处理可能失败的命令。如果你的脚本开了set -e而某条 OpenClaw 命令预期可能失败比如diff找出了差异脚本会立刻退出。我会在这种命令前临时关掉严格模式或者用条件判断if openclaw diff ./dir-a ./dir-b --format json; then echo 目录内容一致 else echo 目录有差异 fi第三设置超时保护。某些任务可能因为网络等待或外部依赖原因卡住外层用timeout包一层比较安全timeout 300 openclaw run 任务名 --quiet第四记录退出码。退出码不是只有成功和失败两种下一章我会单独说。脚本里根据退出码做分支比单纯判断字符串输出可靠得多。5. 权限、审计与清理别等出事了才想起来5.1 token 的默认有效期与最小权限OpenClaw 的某些功能比如触发远程设备上的任务、访问受保护的资源需要用到访问令牌。令牌相关命令openclaw token create [--scope run] [--expires-in 2h] openclaw token renew token标识 openclaw token revoke token标识令牌默认有效期是 2 小时过期后需要renew续期。我特别想强调 scope 最小化创建令牌时明确指定它能干什么比如只允许触发任务就写--scope run不要图省事加一个--scope all。令牌权限越大泄露时的风险半径就越大。把它理解成给门配钥匙给日常进出的人配一把只开前门的锁没必要配万能钥匙。5.2 audit 日志到底看什么audit命令输出操作审计记录openclaw audit [--since 7d] [--action run] [--format json]一条审计记录包含这些字段字段含义时间操作发生的时间戳动作执行的是哪个命令对象操作的任务名或文件路径发起方式交互终端 / 脚本 / API 调用状态码命令最终的退出码这个命令平时用不上但在排查谁在那个时间点改了配置为什么半夜有个任务自动执行了这类问题时它是唯一线索。我的建议是把审计日志定期导出归档保留至少 90 天。成本很低真出问题时价值非常大。5.3 缓存与临时目录清理OpenClaw 跑久了~/.openclaw/cache/和~/.openclaw/tmp/会积累不少文件。清理命令openclaw cache purge # 清空缓存索引不影响任务定义 openclaw temp prune [--older-than 7d] # 清理超过指定时间的临时文件cache purge不会删掉任务配置只是让下次scan或索引操作重新构建缓存可以放心用。temp prune默认只清理超过 7 天的临时文件避免误删正在执行的任务的中间文件。我会在每次版本升级后做一次双清理顺手doctor检查一遍保持环境干净。6. 踩坑记录三组容易混淆的命令和退出码6.1 三组命令的混淆现场用 OpenClaw 时间长了我发现新手包括我自己最容易混的是三组命令。第一组run vs fork。run是执行任务跑完就完fork是复制生成新任务跑的是副本。如果你只是想临时加个参数跑一次用fork如果你想让定义好的任务按原样执行用run。我见过有人想跑原任务结果顺手fork了一个新任务导致后续自动化脚本找不到原任务名排查了半天。第二组scan vs mirror。scan只做描述——输出目录里有什么文件mirror做的是同步——会实际修改目标目录。曾经有人把mirror当scan用对着生产目录执行了同步目标目录里多余文件被删了。记住scan 只读mirror 会写。第三组config set vs profiles use。config set是直接修改配置值把某个参数永久改掉profiles use是切换整套配置集相当于换了上下文集。改全局默认值用config set切环境用profiles use两者不能互相替代。我的记忆方法很简单动词的英文原义就是记忆锚点。偷偷说还有个土办法——实在不确定时先敲openclaw 命令 --explain看它告诉你会做什么确认了再执行。6.2 退出码不是只有 0 和 1OpenClaw 的退出码设计得比较细写脚本时只看0和1远远不够退出码含义常见触发场景0执行成功命令正常完成1运行期失败任务步骤报错、外部命令异常2参数错误传入不存在的任务名、非法标记3配置错误配置文件语法错误、profile 校验不过4权限不足令牌 scope 不够、目录无写权限130被用户中断手动 CtrlC 终止区分2和4很关键参数错误说明你敲的命令有问题配置错误说明环境有问题权限不足则要检查令牌或目录权限。调试时先看退出码能省很多找原因的功夫。写脚本时我习惯用$?捕获并映射到日志openclaw run nightly-build --quiet code$? case $code in 0) echo 构建成功 ;; 2) echo 参数错误检查任务名 ;; 4) echo 权限不足需要重新授权 ;; *) echo 执行失败退出码 $code ;; esac6.3 升级后的命令兼容性变化OpenClaw 从 1.x 升到 2.x 后个别标记名称做了调整。最典型的是--path改成了--target--out改成了--output-file--no-progress改成了--progress off如果你的旧脚本还在用--path命令会提示参数错误但不会告诉你是升级导致的。我的处理方式升级完第一件事跑openclaw doctor --compat它会扫描当前环境里的脚本和配置文件标记出已经不兼容的用法。另外升级前把~/.openclaw/整个目录备份一份出问题随时回滚。如果你刚上手 OpenClaw我的建议是先别急着背命令把init和doctor跑一遍再用scan和diff练手感受命令格式等需要自动化重复操作时再学run、fork、mirror这些更重的命令。工具用久了你会发现大部分命令根本不需要刻意记——help文本已经写得很清楚你唯一需要记的是哪些操作会改文件、哪些只会读文件以及出了问题先看退出码。这些经验比背一百条命令更有用。