第一次在终端里看到 OpenClaw CLI 把一句“帮我把 logs 目录下所有超过 100MB 的日志按日期归档并打印体积变化”直接翻译成一连串 shell 命令、逐条执行完并给出汇总时我确实愣了一下。这种感觉和以前在网页里问 AI 完全不一样——它不是隔着屏幕给你贴一段代码而是直接在你电脑里动真格的。OpenClaw CLI 就是这样一个开源的人工智能命令行助理和 Codex CLI、Claude Code 这类工具属于同一个生态模型负责理解意图它负责调度终端里的文件、命令和工具链。这篇文章不是官网文档的复述而是我实际装机和用下来的过程记录覆盖 Windows、Ubuntu、手机 Termux 三种环境讲解模型后端配置包括 Ollama 本地模型和 API、核心命令与斜杠指令、Skills 扩展、Windows Companion 配置最后附上常见报错的排查思路。无论你是想找个本地可跑的终端 AI 助手还是打算把它接进自动化脚本里这篇都能直接照着操作。1. 安装前先把环境收拾干净Node.js 与 WSL2 检查清单1.1 Node.js 版本别图新LTS 最稳OpenClaw CLI 是用 Node.js 生态分发的所以第一步不是装 OpenClaw 本身而是装 Node.js。很多初次上手的人包括我自己第一次装的时候都犯过一个低级错误直接去官网下载了最新版结果后面跑 npm 安装时各种依赖兼容问题折腾半小时最后发现是 Node 版本太激进。去 node.js 官网下载 LTS 版本就好别碰 Current 版本。LTS 是长期维护版所有 CLI 类工具在发布前主要测试的都是 LTS 环境稳定性远高于尝鲜版。Windows 下安装包一路下一步即可注意安装过程中那个“Add to PATH”选项一定要勾上否则装完打开终端会提示“node 不是内部或外部命令”。装完验证一下node -v npm -v两个命令都有输出、且版本号能对上 LTS 的版本段就可以往下走了。如果你的电脑之前装过别版本的 Node建议先把旧环境清理干净再装避免 PATH 里残留多个 node.exe导致你明明升级了、node -v却还是旧版本。之后通过 npm 全局安装 OpenClaw CLI具体包名以官方 README 为准我这边装的版本用的是 openclaw-clinpm install -g openclaw-cli装完执行openclaw --version能输出版本号说明核心程序已经就位。注意不要用管理员权限去跑 npm 全局安装Windows 下经常因此产生权限目录问题。1.2 Windows 下修好 WSL2避免“无法安全验证”报错Windows 上安装 OpenClaw踩坑率最高的位置就在 WSL2。我遇到的报错信息是这么一段“OpenClaw 无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status 后查看报告信息。”这个报错翻译成人话就是OpenClaw 在 Windows 侧需要调用 WSL2 的能力来做文件系统桥接和跨平台命令执行但系统里要么没装 WSL2要么内核版本太旧要么默认发行版没有正确指定。它检测不到可用的环境就直接撂挑子。处理步骤并不复杂但顺序有讲究用管理员身份打开 PowerShell不是 CMD运行wsl --status先看系统报什么。如果提示 WSL 未安装运行wsl --install它会自动装上 WSL2 相关组件和默认发行版。如果提示内核版本旧运行wsl --update更新内核。如果你的机器上装了多个 Linux 发行版运行wsl --set-default 发行版名指定一个默认环境避免 OpenClaw 不知道该调用哪个。最后用wsl --list --verbose校验VERSION 列显示 2 才算真正就绪。有一点特别容易漏全部配置完成后要新开一个终端窗口不要直接在当前窗口继续跑。CLI 在启动时会读取一次系统环境信息不会动态刷新你刚装好 WSL2 再用原来的窗口跑大概率还是同样的报错。1.3 Ubuntu 上的一路顺畅安装Linux 环境省去了 WSL2 这一层麻烦。Ubuntu 上装 OpenClaw 的思路和 Windows 类似区别只在 Node.js 的获取方式。Ubuntu 自带的 apt 源里 Node.js 版本通常偏旧不建议直接apt install nodejs。我更推荐用 nvm 装 LTS这样可以随时切换版本也绕开了全局安装时 /usr/lib 目录权限不足的问题。装好 nvm 后执行nvm install --lts nvm use --lts然后同样是 npm 全局安装。如果你是在云服务器上装注意一下内存和磁盘npm 安装过程会拉取不少依赖磁盘低于 1GB 剩余空间时建议先清理一下。还有一个容易被忽略的小点Linux 下如果用了 zsh安装完成后需要执行hash -r或者干脆重开终端否则openclaw命令会提示找不到。这不是没装成功只是 shell 的命令哈希表还没刷新。2. 模型后端怎么选本地 Ollama 还是云端 API2.1 不是只有 API 一条路Ollama Qwen2.5:3b 实测网上有朋友问“OpenClaw 是不是只能用接入 API 的方式使用算力”这个说法其实不准确。OpenClaw CLI 本身不绑定某个模型供应商它更像一个“带工具的模型客户端”模型在后端跑CLI 只负责把任务拆解、调用工具、把结果喂回给模型。所以后端完全可以是本地模型。我最先实测的就是 Ollama Qwen2.5:3b 这套组合。先保证 Ollama 已经装好并拉取模型ollama pull qwen2.5:3b然后到 OpenClaw 的配置文件里把推理后端指到 Ollama。配置文件一般生成在用户目录的 .openclaw 文件夹下多数版本是 config.json 或 config.toml核心字段如下{ model_backend: ollama, base_url: http://127.0.0.1:11434, model: qwen2.5:3b }配置完成后跑一条简单指令测试“列出当前目录的前 10 个文件并说明各文件类型”。这一步如果能在终端里正常输出结果说明本地模型链路已经打通。这里要注意几个实测中遇到的点。第一Ollama 必须保持在后台运行CLI 启动时不会帮你拉起它。你可以先手动ollama serve看看端口是否正常监听。第二host 地址不要写 localhost 以外的花活默认 127.0.0.1 最稳。第三3b 模型的指令跟随能力在小任务上够用但你要是让它分析一个几百个文件的仓库它很快就会开始答非所问这是模型规模决定的不是 OpenClaw 的问题。2.2 API 接入与配置文件里的几个坑如果你需要更强的推理能力API 是更省事的选择。配置方式和 Ollama 大同小异本质都是指向一个 OpenAI 兼容接口。{ model_backend: openai_compatible, api_key_env: MY_API_KEY, base_url: https://your-endpoint.example.com/v1, model: gpt-4o-mini }有几个坑我踩过写出来给大家避一避。第一api_key_env字段指的是环境变量名不是让你直接把密钥明文写进配置文件。把密钥放配置文件里不仅危险而且在团队协作时很容易被误提交到仓库。正确做法是提前在终端里设置好export MY_API_KEYsk-xxxx第二base_url 末尾的/v1不是可选项。OpenClaw 在调用接口时会往 base_url 后面拼路径少写一层/v1就可能导致 404 或路由错误。第三如果你配的是企业内网自建网关务必确认网关的 SSL 证书被系统信任否则 CLI 可能在 TLS 握手阶段就直接失败表现形式是各种看不懂的网络错误码。2.3 本地和 API 的分工建议跑通两种后端之后我现在的使用习惯是明确分工的。敏感数据、离线环境、轻量文本处理用本地 Ollama代码重构、复杂逻辑生成、大仓库问答用 API。本地模型的好处不只是隐私响应速度也稳定不受外部服务波动影响API 模型则赢在推理深度上。如果你机器配置一般不建议本地跑超过 7B 的模型。我试过用 CPU 跑更大的模型不是不能跑是一个任务要等几十秒交互体验很差。性能不强的机器老老实实 3b 起步先跑通流程再去追求效果。这一步的体验优先级是能响应 响应快 结果好。3. 命令行工作流核心命令、斜杠指令与 Windows Companion3.1 三种启动方式chat、run 与临时切模型OpenClaw 的日常使用大致分三种形态。第一种是直接敲openclaw进入交互式对话适合探索性任务比如“帮我想想这个模块怎么拆分”。第二种是单次执行模式openclaw run 把当前目录下所有 .tmp 文件移动到 /tmp 并输出移动记录run模式几乎是我日常用最多的因为可以把任务写进脚本、配合计划任务执行。比如我写了一个清理缓存的小脚本每天凌晨用openclaw run 清理 /var/log 下超过 7 天未修改的 .log 文件跑一遍就相当于给系统配了一个懂得自然语言的定时保洁员。第三种是临时切模型不修改配置文件openclaw --model qwen2.5:3b这招在快速对比不同模型效果时很管用。注意它只对当前会话生效重启后恢复原配置。很多人不知道这个参数每次想换模型都得改配置文件麻烦还容易改错。3.2 斜杠指令速查/compact、/model、/resume 各管什么长时间对话后CLI 的上下文窗口会被塞满。这里的处理方式和 Codex CLI 这类工具基本一致OpenClaw 在会话里提供一组斜杠指令指令作用什么时候用/compact压缩当前会话的历史记录上下文太长、模型开始“失忆”时/model临时切换模型需要对比不同模型效果时/resume恢复之前的历史会话跨天继续同一个任务时/clear清空当前会话换任务主题时/help查看当前版本支持的指令不确定语法时/compact这个指令值得单独说一下。它的原理是把之前的对话摘要成更短的文本重新作为上下文放进模型而不是简单地截断丢掉。压缩后模型能保留关键任务信息但会丢失一部分细节所以执行完重要任务、确定结果没问题之前不要急着压缩。我吃过一次亏压缩后让 AI 继续改代码结果它把我之前明确否决过的一个方案又拿出来了。/resume的使用有一个容易忽略的注意点恢复会话时尽量保持和原来相同的项目路径。AI 在对话过程中会记录相对路径你换了个目录再 resume它可能还按旧路径找文件自然找不到。这不是 bug是上下文管理的基本逻辑。3.3 Skills 技能包与 Windows Companion 配置OpenClaw 的 Skills 机制是把一组固定流程打包成可复用的“技能”。比如我让 AI 做“日志分析”以前每次都要描述一遍分析口径后来我直接建了一个技能目录放在~/.openclaw/skills/下log-analyzer/ SKILL.md scripts/analyze.shSKILL.md 里写清楚触发条件和执行步骤比如“当用户提到日志分析时先运行 analyze.sh再按文档里的格式输出结论”。配置好之后我只需要说“用 log-analyzer 分析今天的请求日志”AI 就会按既定流程执行。这个机制非常适合团队内部把运维经验固化下来每个人理解有偏差的口语化指令最终都落到同一个标准化脚本上。Windows 上还有一个 Companion 组件它的定位是 Windows 侧的后台助手负责文件系统桥接、剪贴板同步、通知转发这些和系统交互的脏活。配置流程大致三步安装组件后启动一次它会生成一个本地连接地址和令牌然后在 OpenClaw 配置文件里填上这个地址最后跑一个剪贴板同步测试能通过就说明桥接成功。不同版本对 Companion 的命名略有差异有的叫openclaw-companion有的直接集成在主程序里以你手头版本的提示为准。如果你只在 WSL2 里使用 OpenClawCompanion 倒不是必需品核心 CLI 功能不依赖它。4. 手机端部署Termux 上跑 OpenClaw 的完整记录4.1 Termux 环境与安装步骤手机端跑 OpenClaw目前最主流的方式是 Termux。Termux 是 Android 上的 Linux 终端环境不是模拟器它直接跑在用户态。安装之前先去官网或应用商店把 Termux 装好然后执行pkg update pkg upgrade -y pkg install nodejs-lts git -y npm install -g openclaw-cli openclaw --version这里有一个大多数新手会忽略的操作如果后续 OpenClaw 需要读写手机存储必须在 Termux 里先执行termux-setup-storage它会把手机内部存储挂载到 Termux 的目录树里否则你会看到各种 permission denied。装好之后手机端的 OpenClaw 和电脑上没有任何功能差别可以正常跑run命令也可以进入交互式对话。我在手机上的典型用法是“临时查一下某个服务的日志”直接openclaw run 分析 /sdcard/logs/ 下最新的日志结构不用打开电脑也能快速看到结论。4.2 手机端的限制与应对手机端跑得通但限制也很现实。第一息屏后系统会杀掉后台进程长任务大概率跑不完。解决办法是用termux-wake-lock保持设备唤醒再用 tmux 或 screen 把会话挂在后台双保险。第二手机内存就那么大本地模型建议别跑尤其 3b 以上直接劝退。但有个折中方案在同一局域网内让手机连接一台已经跑着 Ollama 的电脑或服务器。{ model_backend: ollama, base_url: http://192.168.1.100:11434, model: qwen2.5:3b }这样手机负责交互和工具调用真正算力在局域网内的服务器上体验会好很多。第三屏幕上敲复杂指令不方便我推荐把高频任务写成脚本只保留一个可变参数手机端只管触发即可。5. 常见报错排查实录WSL2、403 与 Windows 网络错误5.1 WSL2 环境验证失败的修复先给个速查表Windows 上 OpenClaw 与 WSL2 相关的问题基本都能对号入座报错场景常见原因处理方式无法安全验证 WSL2 环境WSL2 未安装或内核太旧管理员 PowerShell 执行wsl --status检查再wsl --update提示未找到发行版只装了 WSL 内核没有装 Linux 发行版wsl --install -d Ubuntu检测到 WSL1 而非 WSL2发行版还是第一代版本wsl --set-version 发行版 2有多个发行版时调用错乱没设默认发行版wsl --set-default 发行版名重点是先跑wsl --list --verbose确认当前状态别在没看清状态之前乱重装。WSL2 不像普通软件卸载重装成本高很多时候只是内核版本落后一条wsl --update就能解决。5.2 请求返回 403先查鉴权再看地址接入 API 或自建网关时403 是我遇到频率最高的错误之一。排查顺序我总结成一套固定流程确认 API Key 真的注入到了环境变量里。很多情况下 Key 写错了文件、终端没重启环境变量根本没生效。确认 base_url 是否完整尤其不能漏/v1。漏掉之后请求会被路由到错误地址服务端直接拒绝。确认账号权限和余额。这个最容易被忽略一些网关账号没有模型调用权限表现同样是 403。最后再去查网关日志。自建网关的日志里会写明拒绝原因比在 CLI 端猜效率高得多。还有一个容易忽略的安全细节排查时不要把完整 API Key 贴进对话里也不要贴到日志分享里。可以用环境变量名替代比如“我检查了 MY_API_KEY 对应的值”既能让对方理解问题又不会泄露密钥。5.3 internetopenurl() failed 0x800 的处理在 Windows 上跑某些 AI 命令行工具时可能报internetopenurl() failed. 0x800这类错误。这个名字看起来很唬人其实它是 Windows 底层网络组件无法完成请求时的通用报错。常见原因集中在三块第一系统里残留了无效的网络转发配置。我之前因为测试软件改过网络设置之后忘记恢复导致所有需要走网络的 CLI 命令集体报错。处理办法是重开终端、确认当前网络状态正常必要时重置系统网络栈。第二TLS 相关组件版本过旧。可以检查系统更新是否都装上了尤其 TLS 1.2 相关补丁很多老旧机器卡在这一步。第三如果你连的是自建网关网关证书不受系统信任也会触发这个错。解决方式是把证书加入系统信任区而不是在 CLI 层绕过校验。这个报错的核心排查思路是CLI 只是个引信问题大概率在系统网络栈或网关本身。5.4 卸载与版本升级的正确姿势想卸载 OpenClaw或者单纯想清理环境操作其实很简单npm uninstall -g openclaw-cli然后删掉用户目录下的配置文件夹。Windows 上是%USERPROFILE%\.openclawLinux 和 Termux 上是~/.openclaw。如果你装过 Companion还需要去服务管理里停掉对应的常驻服务再删除它的启动项。但如果不是必须卸载我更推荐直接覆盖升级npm install -g openclaw-clilatestOpenClaw 的迭代速度不慢有些问题新版早就修掉了与其折腾卸载重装不如先升级一个版本看看问题是否还在。这个习惯同样适用于 Codex CLI 这类 npm 分发的命令行工具升级成本低、收益明显。6. 我的实际使用体会与建议6.1 我平时最常用的组合方式用了一段时间之后我现在的固定组合是电脑上跑 Ollama 本地模型处理敏感任务API 模式处理重活手机 Termux 只挂一个轻量客户端应急查询用。每天最常用的不是交互式对话而是openclaw run写进脚本的自动化任务。它让我把“用自然语言描述任务”这件事从聊天框里解放出来真正变成了可重复执行的指令。在团队协作场景里我更推荐大家把经验固化成 Skill。新同事不用背一堆命令直接让 OpenClaw 按技能包执行效率提升非常明显。这就好比把老师傅的操作手册做成了 AI 可直接调用的 API人换了几轮经验还在。6.2 几句实在的提醒最后说几句打消滤镜的话。OpenClaw 这类 CLI 工具确实能干活但它不是万能的。模型会猜错路径、理解错需求尤其在小模型模式下绝对不能让它直接对重要数据执行不可逆操作。我的习惯是第一次让它只输出执行计划、不真正运行命令确认无误后再放行。从大环境看Codex CLI、Claude Code、OpenClaw 这批工具已经把终端 AI 交互方式固化得差不多斜杠指令、会话恢复、工具调用、技能扩展。你熟练其中一个其他的上手成本会非常低。这也是我为什么愿意花时间写这篇教程——工具会换代但这套思路和排查方式换个工具依然能用。装好环境、配好后端、从一个小任务开始跑通它你会发现终端里多了一个靠谱的搭档而不再只是一个输入命令的窗口。