OpenClaw CLI 速查手册：从安装部署到排错实战

1. OpenClaw CLI 到底是什么先别急着敲命令先把这个事情的定位说清楚。OpenClaw 是一个开源的智能体Agent运行时框架你可以把它理解成给 AI 装上了手和脚——它能连接各种大模型作为大脑再把微信、飞书、钉钉、Slack 这些 IM 平台当成手脚去执行任务。而 OpenClaw CLI就是控制这个智能体运行时的命令行工具。很多人一上来就问我OpenClaw 和 WorkBuddy 哪个好Claude Code CLI 和它啥关系其实它们不完全是一类东西。Claude Code 偏重AI 结对编程Codex CLI 也是写代码场景而 OpenClaw 更像是一个随时在线的数字员工你把它部署到服务器上它可以 7x24 小时在微信群里响应指令、在飞书里自动汇总报表、定时执行脚本、调用外部 API。CLI 只是你管理这个员工的控制台启动它、配置它、看它的日志、踢它重启。这篇速查手册不打算写成枯燥的--help输出堆砌而是结合我实际部署 OpenClaw 的经验把最常用的命令、最容易踩的坑、还有那些网上搜不到的中文注释一次性讲清楚。内容覆盖 Windows 和 Linux 两种环境从安装、配置大模型以千问为例、接入 IM 渠道到处理报错都是实操过的。先说结论OpenClaw CLI 的命令设计整体遵循动词 对象 参数的套路核心就四个动词——openclaw install、openclaw serve、openclaw agent、openclaw doctor。把这四个吃透剩下都是变体。2. 安装部署阶段的 CLI 操作Windows 和 Linux 两套流程2.1 Windows 下安装 OpenClaw 的完整命令序列Windows 上安装 OpenClaw 主要有两种方式脚本安装和 Windows Hub 安装。如果你的系统是 Windows 10/11 且开了 WSL2官方推荐走 WSL2 路线因为 OpenClaw 的很多依赖比如 Docker、部分 Python 包在 Linux 环境下更稳定。最直接的安装命令是打开 PowerShell管理员模式执行irm https://openclaw.ai/install.ps1 | iex这个命令会下载安装脚本并执行。注意一定要用管理员权限因为它会写环境变量、注册服务。安装完成后关掉当前终端重新打开让 PATH 生效然后验证openclaw --version如果看到版本号输出说明安装成功。如果提示command not found手动把%USERPROFILE%\.openclaw\bin加到系统 PATH。还有一类安装方式是 OpenClaw Windows Hub。这是给不想用命令行的用户准备的图形化入口但本质还是调用 CLI。你装完 Hub 之后它会在后台拉起openclaw serve日志路径通常在C:\Users\你的用户名\.openclaw\logs\。我个人建议Hub 可以装但日常排查问题还是得回到 CLI因为 Hub 会把错误信息藏起来而 CLI 会把完整的堆栈打出来。2.2 Linux 服务器上的安装与本地一键部署命令Linux 上安装更简单一条命令curl -fsSL https://openclaw.ai/install.sh | bash装完之后同样验证版本。这里有个细节如果你的服务器在国内直接拉 GitHub 可能会超时我试过几个方案最省事的是配置代理变量再执行安装脚本export https_proxyhttp://你的代理地址:端口 curl -fsSL https://openclaw.ai/install.sh | bash还有一个高频需求是本地一键部署——就是不想联网装依赖想在内网环境完整跑起来。OpenClaw 官方没有严格意义的离线包但你可以先在一台联网机器上完成安装然后把~/.openclaw整个目录打包拷贝到目标机器再手动装一下 Python 3.11 和 Node.js 18 这两个运行时依赖基本就能跑。我踩过的一个坑是打包拷贝之后openclaw serve启动报 Python 虚拟环境路径不对这是因为安装脚本把虚拟环境的绝对路径写死进了配置。解决办法是删掉~/.openclaw/venv文件夹重新执行openclaw install它会只重建虚拟环境而不会覆盖你的配置。2.3 WSL2 环境验证失败的排查命令很多 Windows 用户会碰到这个报错could not safely verify the WSL2 environment.翻译过来就是OpenClaw 无法安全确认 WSL2 环境是否正常。这个问题我遇到过三次每次原因都不一样。第一次是 WSL2 根本没启用。排查方法wsl --status wsl --list --verbose如果显示的是 WSL 1 或者没有输出需要先升级wsl --set-version 发行版名称 2 wsl --set-default-version 2第二次是 Windows 上有多个 WSL 发行版OpenClaw 不知道该用哪个。这时候需要指定默认发行版wsl --set-default Ubuntu第三次比较隐蔽OpenClaw 会尝试在 WSL2 里执行docker version来检查 Docker 环境如果 Docker Desktop 没有开启 WSL 集成它就会判定WSL2 环境不安全。解决方法是打开 Docker Desktop - Settings - Resources - WSL Integration把对应发行版的开关打开。如果上面都做了还是报错终极排查方法是直接看日志openclaw doctor这个命令会列出系统环境检查结果包括 WSL2 状态、Node 版本、Python 版本、Docker 可用性。把输出贴给 AI 或者发到社区比你自己瞎猜快得多。3. 启动与运行的核心命令server agent 双引擎详解3.1 openclaw serve 启动服务前端后台怎么选openclaw serve是 OpenClaw 的主进程命令相当于把所有功能跑起来。它有三种运行形态前台运行输出全部日志到终端openclaw serve后台守护进程运行日志写到文件openclaw serve --daemon或者用--listen 0.0.0.0指定监听所有网卡默认只监听本机 127.0.0.1。这一点特别注意如果你要让局域网内其他机器访问 OpenClaw 的 Web 控制台必须加这个参数。我自己常用的启动组合是nohup openclaw serve --daemon --listen 0.0.0.0 ~/.openclaw/logs/serve.log 21 这样即使用户退出 SSH进程也不会死。查看运行状态用openclaw status停止服务openclaw stop重启服务更新配置后必须重启才生效openclaw restart这里有个容易混淆的点openclaw serve --daemon和openclaw status这两个命令一个是启动一个是查询很多新手把status当成启动命令用结果报 daemon not running 就慌了。实际上如果你执行openclaw serve不带--daemon它会以前台模式运行终端一关服务就死。所以我建议在服务器上部署一律用--daemon在本地调试才用前台模式。3.2 配置模型驱动的三个关键命令以千问为例OpenClaw 本身不内置模型它通过 Driver 机制对接各种模型服务商OpenAI、Claude、Gemini、千问、DeepSeek、Ollama 本地模型都支持。Driver你可以理解成驱动程序——就像打印机需要装驱动才能用OpenClaw 也需要装对应模型的驱动才能调用。查看当前已安装的 Driveropenclaw driver list安装千问的 Driveropenclaw driver install qwen查看某个 Driver 的详细配置要求openclaw driver info qwen配置 API Key 和模型参数最推荐的方式是编辑~/.openclaw/config.yaml核心片段如下driver: qwen: api_key: sk-你的千问API密钥 model: qwen-plus base_url: https://dashscope.aliyuncs.com/compatible-mode/v1改完配置后用openclaw restart让配置生效。这里我要多说一句千问接 OpenClaw 这事官方文档写得有点隐晦很多人在driver install qwen之后就直接跑openclaw agent run 你好结果报driver qwen not found或者api_key is required。原因是安装 Driver 只是把驱动代码拉下来但配置文件里的api_key还是空的。必须手动编辑config.yaml。还有一个常见坑千问的base_url别配错了。OpenClaw 走的是 OpenAI 兼容接口所以 URL 要指向 DashScope 的 compatible-mode 端点不是原生端点。这点非常关键。3.3 查看和切换 Channel解决微信只发不收的问题Channel 是 OpenClaw 连接 IM 平台的通道比如微信、飞书、钉钉、Slack。查看所有 Channel 状态openclaw channel list查看某个 Channel 的详细配置openclaw channel info wechat重新初始化微信连接openclaw channel login wechat热词里有人问OpenClaw agent 怎么选择 Channel其实逻辑很简单你在微信里给机器人发消息微信 Channel 收到后会把消息交给 Agent 处理Agent 处理完再从原 Channel 回复。所以如果出现OpenClaw 能发消息微信但微信发消息没回复问题十有八九出在登录态失效或者消息回调没配对。排查步骤依次执行openclaw channel list openclaw channel login wechat openclaw agent testagent test会主动发一条测试消息如果测试消息能收到但你自己发的不回说明是消息回调链路的问题重点检查微信登录态和 session 文件。如果测试消息也收不到说明 Channel 和 Agent 之间的连接就没建立起来。4. 命令速查表与参数详解直接抄作业的版本4.1 最常用的 20 个命令速查表我整理了一份高频命令速查表按照使用频率从高到低排列。功能命令说明查看版本openclaw --version确认安装结果查看所有命令openclaw --help完整命令列表系统体检openclaw doctor检查环境依赖启动服务前台openclaw serve调试用终端关闭即停启动服务后台openclaw serve --daemon服务器部署推荐停止服务openclaw stop优雅停止所有进程重启服务openclaw restart改配置后必须执行查看状态openclaw status检查进程是否存活查看 Agent 列表openclaw agent list查看所有已配置 Agent创建新 Agentopenclaw agent create按向导创建运行一次 Agent 任务openclaw agent run 查询天气手动触发单次任务进入 Agent 对话模式openclaw agent chat交互式对话发送测试消息openclaw agent test验证链路是否通畅查看 Driver 列表openclaw driver list查看已装模型驱动安装 Driveropenclaw driver install qwen按需安装模型驱动查看 Driver 信息openclaw driver info qwen查看配置要求查看 Channel 列表openclaw channel list查看所有 IM 连接登录 Channelopenclaw channel login wechat重新扫码登录查看实时日志openclaw logs -f跟踪输出排查问题时必备修改配置openclaw config edit打开默认编辑器编辑 YAML4.2 日志和调试命令的进阶用法日志是排查问题的第一利器。openclaw logs -f是跟踪模式类似 Linux 的tail -f会实时刷新最新日志。我通常配合--tail 200参数先看最近 200 行openclaw logs --tail 200 -f只看错误级别日志过滤掉 INFO 噪音openclaw logs --level ERROR把最近 500 行日志导出到文件方便发给别人排查openclaw logs --tail 500 ~/openclaw_debug.log还有一个调试神器--debug参数可以用在多个子命令上比如openclaw serve --debug会输出非常详细的内存、事件、消息流转信息。初次排查复杂问题建议直接上 debug 模式。4.3 config.yaml 常用配置项中文注释版OpenClaw 的所有配置集中在~/.openclaw/config.yaml。这是最核心的配置文件我用中文注释整理了最常见的配置块你可以直接参考# OpenClaw 全局配置 port: 8080 # Web 控制台端口 host: 127.0.0.1 # 监听地址如需局域网访问改为 0.0.0.0 daemon: true # 是否默认以守护进程运行 # Agent 配置区 agent: default: main # 默认使用的 Agent 名称 sessionTimeout: 600 # 会话超时时间单位秒 # 模型驱动配置区以千问为例 driver: qwen: api_key: sk-你的API密钥 # 从阿里云百炼控制台获取 model: qwen-plus # 推荐 qwen-plus性价比高复杂任务换 qwen-max base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 max_tokens: 4096 # 单次回复最大 token 数 # 飞书渠道配置区 channel: feishu: app_id: cli_xxxxxx # 飞书开放平台创建应用后获取 app_secret: 你的应用密钥 encrypt_key: # 如果开启了加密填这个否则留空 verification_token: # 事件订阅的校验 token改配置的两个建议第一每次改完都执行openclaw config validate如果有这个命令或者直接openclaw restart验证第二务必备份config.yaml我因为手滑改错一个缩进导致整个服务起不来这种事发生过不止一次。YAML 对缩进极度敏感一个空格错误配置就全部失效。5. 高频报错与排查技巧这些坑我都替你踩过了5.1 session file locked (timeout 60000ms) 的三种解法热词里有一个非常典型的报错agent failed before reply: session file locked (timeout 60000ms)。这个报错的意思是Agent 在回复之前失败了原因是会话文件被锁定等待 60 秒超时。什么情况下会发生这个最常见的是多个请求同时触发了同一个会话文件写入。比如你在微信里同时给机器人发了两条消息或者 Web 控制台和微信同时唤起同一个 Agent。另一个原因是之前的进程崩溃了但没有释放文件锁。我的解法按优先级排列第一种等一下再试。因为 60 秒超时是等待锁释放如果只是短暂并发等锁释放后自己就好了。第二种杀掉僵尸进程释放锁openclaw stop pkill -f openclaw openclaw start这里的思路是openclaw stop可能只停了主进程但某些子进程变成僵尸进程还占着锁文件pkill -f openclaw把所有相关进程一锅端。第三种如果上面都不行手动删除锁文件。锁文件一般在~/.openclaw/sessions/目录下找到对应.lock文件删掉即可ls ~/.openclaw/sessions/ rm ~/.openclaw/sessions/xxx.lock openclaw restart注意删除锁文件前最好确认没有其他进程正在使用该会话否则可能损坏会话数据。5.2 codex cli 相关报错与 WSL2 目录混用问题很多人电脑上同时装了 Codex CLI 和 OpenClaw然后会碰到unable to locate the codex cli binary or required runtime components这种报错。这个问题不在 OpenClaw 本身而是 Codex CLI 在 Windows 上的路径映射问题。Codex CLI 在 Windows 上运行如果安装在 Windows 路径但 OpenClaw 跑在 WSL2 里两边文件系统不通就找不到二进制文件。解决办法要么在 WSL2 里单独安装 Codex CLI推荐要么在 Windows 的 PowerShell 里配置好 PATH 之后再启动 OpenClaw。还有一种情况用 Windows Terminal 执行codex --version能看到版本号但用其他终端比如 VS Code 内置终端就找不到这是因为两个终端的 PATH 环境变量不一致重新打开终端或者手动刷新环境变量即可$env:Path [System.Environment]::GetEnvironmentVariable(Path, Machine) ; [System.Environment]::GetEnvironmentVariable(Path, User)5.3 飞书输出容易被截断的解决办法热词里有一条openclaw 在飞书输出容易被截断。这个问题的本质是飞书自定义机器人的消息长度上限远低于 OpenClaw 默认的输出长度。飞书 webhook 机器人单条消息最多支持 10 万个字符但如果你开的是长文本模式或用了消息卡片限制会更严格。而大模型回复几千字是家常便饭一旦超出飞书直接截断看起来就像AI 没说完。解决办法有两种第一种配置输出分段。在 OpenClaw 的飞书 Channel 配置里设置max_message_length参数比如 2000 字符超出的内容自动拆分多条发送channel: feishu: max_message_length: 2000 split_long_message: true第二种用消息卡片。飞书消息卡片支持折叠长文本配置use_card: true长回复会变成点击展开的形式既不截断又不刷屏。我自己实测下来更推荐消息卡片方案因为多段拆分容易把代码块拆散影响阅读。5.4 Agent 之间如何切换多个 Agent 并行不打架OpenClaw 支持配置多个 Agent每个 Agent 可以绑定不同的模型驱动。查看当前默认 Agentopenclaw agent list临时切换openclaw agent run --agent 另一个Agent名 你的指令设置新的默认 Agentopenclaw agent set-default 另一个Agent名这里有个细节不同 Channel 可以和不同 Agent 绑定。比如微信绑定日常对话 Agent用 qwen-plus 省钱飞书绑定代码审查 Agent用 qwen-max 更强完全互不干扰。这个在config.yaml里配置channel: wechat: agent: main feishu: agent: code-review-agent5.5 常用排查命令速查表最后做了一张基于实际踩坑经历的排查命令对照表建议收藏症状首选排查命令辅助手段服务起不来openclaw doctor看~/.openclaw/logs下的错误日志消息发不出openclaw channel list重新channel login模型不回复openclaw driver list检查config.yaml的 api_keyAgent 无响应openclaw statusopenclaw logs -f看实时输出微信只发不收openclaw agent test重新扫码登录微信飞书回复截断检查max_message_length开启use_card卡片模式配置改了不生效openclaw restart确认没有旧进程残留6. 实操经验总结稳定运行 OpenClaw 的几个习惯说几个我长期部署下来养成的操作习惯不一定写在官方文档里但确实能避免很多夜半惊魂。第一个习惯每次改配置之前先备份。cp ~/.openclaw/config.yaml ~/.openclaw/config.yaml.bak这行命令不值钱但能救命。有几次我为了调一个参数把整个 YAML 结构改乱了直接回滚备份一分钟恢复。第二个习惯日志轮转要开启。OpenClaw 跑久了日志文件会膨胀到几个 GB磁盘满了之后各种诡异问题都来了——session 写入失败、服务无响应、心跳超时。定期清理日志或者配置日志轮转是必须的。第三个习惯重启之前先pkill -f openclaw再启动。因为openclaw restart偶尔会碰到旧进程没死透的情况新进程起不来反而报端口占用。养成先杀干净再启动的习惯这个坑就不会再踩。第四个习惯微信登录态会过期定期检查。openclaw channel list的输出里如果微信状态不是 online你就得重新openclaw channel login wechat。我一般每周五下班前看一眼周一上班不用手忙脚乱。第五个习惯遇到复杂问题第一反应不是重装而是开--debug模式跑一次把完整日志留档。因为重装往往丢配置而且错误信息不会因为重装就消失。用 debug 模式定位到具体原因修起来反而更快。OpenClaw CLI 这套工具链学起来不难但真正熟练需要自己在真实场景里折腾几轮。对照这份手册把常用命令变成肌肉记忆遇到问题知道去哪查、怎么查比背命令本身重要得多。后面我在整理 Channel 接入各 IM 平台的详细配置案例每个平台差异还挺大到时候再单独写一篇。