第一次在终端里看到 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-cli：
npm 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 还是云端 API
2.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_KEY="sk-xxxx"第二，base_url 末尾的/v1不是可选项。OpenClaw 在调用接口时会往 base_url 后面拼路径，少写一层/v1就可能导致 404 或路由错误。第三，如果你配的是企业内网自建网关，务必确认网关的 SSL 证书被系统信任，否则 CLI 可能在 TLS 握手阶段就直接失败，表现形式是各种看不懂的网络错误码。
2.3 本地和 API 的分工建议
跑通两种后端之后，我现在的使用习惯是明确分工的。敏感数据、离线环境、轻量文本处理，用本地 Ollama；代码重构、复杂逻辑生成、大仓库问答，用 API。本地模型的好处不只是隐私，响应速度也稳定，不受外部服务波动影响；API 模型则赢在推理深度上。
如果你机器配置一般，不建议本地跑超过 7B 的模型。我试过用 CPU 跑更大的模型，不是不能跑，是一个任务要等几十秒，交互体验很差。性能不强的机器，老老实实 3b 起步，先跑通流程再去追求效果。这一步的体验优先级是：能响应 > 响应快 > 结果好。
3. 命令行工作流：核心命令、斜杠指令与 Windows Companion
3.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 里使用 OpenClaw，Companion 倒不是必需品，核心 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%\.openclaw，Linux 和 Termux 上是~/.openclaw。如果你装过 Companion，还需要去服务管理里停掉对应的常驻服务，再删除它的启动项。
但如果不是必须卸载，我更推荐直接覆盖升级：
npm install -g openclaw-cli@latestOpenClaw 的迭代速度不慢，有些问题新版早就修掉了，与其折腾卸载重装，不如先升级一个版本看看问题是否还在。这个习惯同样适用于 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 交互方式固化得差不多：斜杠指令、会话恢复、工具调用、技能扩展。你熟练其中一个，其他的上手成本会非常低。这也是我为什么愿意花时间写这篇教程——工具会换代，但这套思路和排查方式，换个工具依然能用。装好环境、配好后端、从一个小任务开始跑通它，你会发现终端里多了一个靠谱的搭档，而不再只是一个输入命令的窗口。
