OpenClaw 完全使用手册：从零搭建到技能扩展的实战路径

简介《OpenClaw完全使用手册202602v1》面向希望上手开源个人 AI 助手平台的开发者与进阶用户聚焦本地部署、国内网络使用与技能插件扩展三大痛点。OpenClaw 以本地优先架构运行可通过飞书、钉钉、Telegram 等平台交互并直接读写文件、执行终端命令、控制浏览器实现从对话到自动化执行的跃迁。手册系统梳理了基础功能、文件与文档处理、浏览器自动化、系统命令执行、通讯平台集成、技能插件系统及高级应用场景并给出 Windows、macOS、Linux、Docker 与云服务器多环境部署路径附常用命令速查、配置文件参考与故障排除指南。资源包共 1 个 PDF 文件约 3.48MB结构按章节编排便于按模块查阅。目前已有 191 人学习适合需要快速搭建本地 AI 助手、接入国内通讯平台并掌握插件开发思路的读者参考。1. OpenClaw 完全使用手册从零搭建到技能扩展的实战路径第一次接触 OpenClaw 的人多半是被它“用自然语言驱动本地工具链”的能力吸引过来的。简单说OpenClaw 是一个把大模型能力接到你本机文件系统、命令行和浏览器上的自动化框架——你写一段任务描述它拆解成步骤调用本地工具执行再把结果回传。听起来像又一个“AI Agent 壳”但真正让它值得投入的原因在于它的 skill 机制允许你把重复性操作固化成可复用的模块而不是每次从零写 prompt。这篇手册面向三类人想在自己机器上跑通 OpenClaw 的开发者、需要把它接入现有工作流的运维、以及想写自定义 skill 的进阶用户。下面从安装配置讲到 skill 开发每一步都给出可复现的命令和参数说明。2. 安装与部署Windows、Linux 和 Termux 三条路怎么选2.1 先搞清楚 OpenClaw 的运行依赖OpenClaw 本身是一个 Node.js 应用核心依赖三块Node.js 运行时建议 20 LTS 以上、一个可调用的模型后端本地 Ollama 或远程 API、以及可选的浏览器自动化组件Playwright。它不绑定操作系统但不同平台上的安装摩擦差异很大。Windows 上最省事的路径是走 WSL2因为 OpenClaw 的很多 skill 依赖 Unix 风格的 shell 命令Linux 原生环境最顺Termux 方案适合没有 root 的安卓设备但需要额外处理 Node.js 编译依赖。选型上我的建议很直接如果你只是想在主力开发机上跑Windows 用户装 WSL2 UbuntuLinux 用户直接上如果你需要在移动端做轻量任务触发Termux 可以跑但别指望它执行重负载的浏览器自动化。2.2 Windows 下的最小安装步骤先确认 WSL2 已启用并装好 Ubuntu。进入 WSL 终端后执行# 更新包索引并安装 Node.js 20 LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证版本Node 低于 18 会报错 node -v npm -v # 全局安装 OpenClaw CLI npm install -g openclaw # 初始化配置目录会在 ~/.openclaw 下生成默认配置 openclaw initopenclaw init会生成~/.openclaw/config.json里面最关键的字段是model.provider和model.baseUrl。如果你用 Ollama 本地跑模型把provider设为ollamabaseUrl填http://localhost:11434如果用远程 API填对应的 endpoint 和 key。注意 WSL2 里访问 Windows 宿主机上的 Ollamalocalhost 是不通的需要用 Windows 宿主机的 IP或者在 WSL 里也装一份 Ollama。2.3 Linux 原生环境与 Termux 的差异处理Linux 原生环境下流程和上面一致但有两个额外注意点。第一部分发行版比如 Kylin自带的 Node.js 版本偏旧务必用 NodeSource 源覆盖安装不要用apt install nodejs直接装。第二如果要用浏览器自动化 skill需要手动装 Playwright 的系统依赖# 安装 Playwright 所需的系统库 npx playwright install-deps chromium # 再装浏览器二进制 npx playwright install chromiumTermux 方案要复杂一些。Termux 的包管理器和标准 Linux 不同Node.js 可以直接pkg install nodejs但openclaw的某些原生依赖比如涉及 canvas 或 sharp 的 skill在 Termux 上编译会失败。我的做法是在 Termux 上只装核心 CLI 和纯文本类 skill把重负载任务通过 SSH 转发到一台常开的 Linux 机器上执行。这样手机端只做任务触发和结果查看不承担计算压力。注意Termux 从 Google Play 安装的版本已经停止更新请从 F-Droid 或 GitHub Releases 获取。3. 模型接入Ollama 本地部署与 API 方式的取舍3.1 两种算力接入方式的本质区别OpenClaw 的模型层是抽象过的你可以在配置里切换不同的 provider。最常见的两个选择是本地 Ollama 和远程 API。本地 Ollama 的优势是数据不出机器、无调用费用、延迟可控劣势是对硬件有要求7B 级别的模型至少需要 8GB 显存或 16GB 内存做量化推理再大的模型消费级硬件就跑不动了。远程 API 的优势是模型能力强、无需本地算力劣势是每次调用都有网络延迟和费用而且任务描述里如果包含敏感文件路径或内容需要考虑数据边界。我的实际用法是混合日常的文件整理、格式转换、简单检索走本地 Ollama需要复杂推理或长上下文理解的任务切到远程 API。OpenClaw 支持在 config 里配多个 provider通过openclaw run --provider ollama这样的参数临时切换。3.2 Ollama 本地部署的完整配置先在宿主机上装好 Ollama 并拉取模型# 安装 OllamaLinux 示例 curl -fsSL https://ollama.com/install.sh | sh # 拉取一个适合工具调用的模型qwen2.5:7b 对中文和 function calling 支持较好 ollama pull qwen2.5:7b # 确认模型可用 ollama list然后在 OpenClaw 的 config.json 里配置{ model: { provider: ollama, baseUrl: http://localhost:11434, model: qwen2.5:7b, temperature: 0.3, maxTokens: 4096 } }temperature设 0.3 是因为工具调用场景需要稳定的输出格式太高会导致模型不按 JSON schema 返回。maxTokens设 4096 是平衡显存占用和单次任务复杂度如果你的任务涉及长文件分析可以调到 8192但要注意显存是否够。3.3 远程 API 接入的配置与注意事项远程 API 的配置类似只是 provider 和认证字段不同{ model: { provider: openai-compatible, baseUrl: https://your-api-endpoint/v1, apiKey: sk-xxxxxxxx, model: gpt-4o, temperature: 0.2 } }这里provider写openai-compatible是因为大多数远程 API 都兼容 OpenAI 的接口格式。apiKey建议通过环境变量注入不要硬编码在 config 文件里——OpenClaw 支持${ENV_VAR}语法写成apiKey: ${OPENCLAW_API_KEY}然后在 shell 里 export 即可。一个容易翻车的点是部分远程 API 对 function calling 的支持不完整模型返回的工具调用格式可能不符合 OpenClaw 的解析预期。遇到这种情况先看 OpenClaw 的 debug 日志里模型原始返回是什么再决定是换模型还是手动调整 skill 的输入 schema。4. Skill 机制把重复操作固化成可复用模块4.1 Skill 的目录结构与加载逻辑OpenClaw 的 skill 本质上是一个带元数据的脚本目录。默认从~/.openclaw/skills/加载每个 skill 一个子目录里面至少包含一个skill.json描述文件和一个入口脚本。加载逻辑是启动时扫描目录读取每个 skill.json 里的name、description、parameters字段注册到内部工具列表运行时模型根据 description 决定调用哪个 skill。这个设计的好处是扩展成本低——你不需要改 OpenClaw 核心代码只要按约定放文件就行。坏处是 description 写得好不好直接决定模型能不能正确调用。我见过最常见的翻车就是 description 写得太模糊模型在多个 skill 之间反复横跳。4.2 写一个最小可用的 skill下面是一个把指定目录下的图片批量转成 WebP 的 skill 示例。先建目录和描述文件mkdir -p ~/.openclaw/skills/img2webpskill.json内容{ name: img2webp, description: 将指定目录下的 PNG/JPG 图片批量转换为 WebP 格式支持质量参数, parameters: { type: object, properties: { inputDir: { type: string, description: 输入目录的绝对路径 }, quality: { type: number, description: WebP 质量1-100默认 80 } }, required: [inputDir] } }入口脚本index.js// skill 入口接收模型传入的参数对象 module.exports async function ({ inputDir, quality 80 }) { const fs require(fs); const path require(path); const sharp require(sharp); // 校验目录存在 if (!fs.existsSync(inputDir)) { return { error: 目录不存在: ${inputDir} }; } const files fs.readdirSync(inputDir) .filter(f /\.(png|jpg|jpeg)$/i.test(f)); const results []; for (const file of files) { const src path.join(inputDir, file); const dest path.join(inputDir, file.replace(/\.(png|jpg|jpeg)$/i, .webp)); // quality 参数直接传给 sharp低于 60 会有明显块状伪影 await sharp(src).webp({ quality }).toFile(dest); results.push(dest); } return { converted: results.length, files: results }; };这个 skill 的关键点parameters里用 JSON Schema 描述输入模型会根据这个 schema 生成调用参数入口脚本导出的是一个 async 函数返回值会被序列化后回传给模型。quality默认值 80 是在文件大小和视觉质量之间比较平衡的选择低于 60 时文字边缘会出现明显伪影。4.3 Skill 调试与参数调优的实操建议写完 skill 后不要直接扔给模型跑先用 CLI 手动调用验证# 手动触发 skill传入参数 openclaw skill run img2webp --inputDir /home/user/photos --quality 75如果报错优先检查三件事入口脚本的导出格式对不对必须是 module.exports 一个函数、依赖包有没有装在 OpenClaw 的 node_modules 里全局安装的 skill 需要把依赖也装到全局、参数名和 skill.json 里定义的是否一致。调试通过后再让模型调用这样能把 skill 本身的问题和模型调用的问题分开排查。5. 避坑与排查五个真实踩过的坑5.1 模型不调用 skill只输出文字现象你描述了一个明确需要执行文件操作的任务模型却回复了一段“你可以这样做”的文字没有触发任何 skill 调用。原因通常是 skill 的 description 没有包含模型能匹配的关键词或者模型的 function calling 能力本身较弱。解决把 description 改写成“当用户需要 XX 时使用此 skill”的句式并在系统 prompt 里明确要求“必须调用工具执行不要只给建议”。如果换模型后仍然不行说明该模型对工具调用的支持确实有限。5.2 Ollama 返回超时但模型实际在跑现象OpenClaw 报 timeout 错误但ollama ps显示模型正在推理。原因是 OpenClaw 默认的请求超时时间30 秒对于本地大模型的首 token 延迟来说太短尤其是模型刚从磁盘加载到显存的那一次。解决在 config 里把requestTimeout调到 120000毫秒或者提前用ollama run手动触发一次加载让模型常驻显存。5.3 WSL2 里 localhost 访问不到宿主机的 Ollama现象WSL2 里配置baseUrl: http://localhost:11434连接被拒绝。原因是 WSL2 有独立的网络命名空间localhost 指向的是 WSL 自己。解决在 WSL 里执行cat /etc/resolv.conf拿到宿主机 IPnameserver 那一行把 baseUrl 改成http://宿主机IP:11434。但要注意这个 IP 在重启后可能变化更稳妥的做法是在 Windows 侧设置 Ollama 监听0.0.0.0然后在 WSL 里用宿主机 IP 访问。5.4 skill 依赖装不上报 node-gyp 编译错误现象安装带原生依赖的 skill 时node-gyp 报错提示找不到 Python 或 C 编译工具链。原因OpenClaw 全局安装时skill 的依赖也需要在全局 node_modules 下编译而很多系统默认没有完整的构建工具。解决Linux 上装build-essential和python3Windows WSL 里同样Termux 上则基本无解只能换纯 JS 实现的替代方案。5.5 任务执行到一半卡住日志没有明显报错现象OpenClaw 执行多步任务时停在某一步不再继续日志最后一行是某个 skill 的调用记录。原因通常是 skill 返回的数据量太大超过了模型上下文的承载能力模型在等一个它处理不完的输入。解决在 skill 里对返回值做截断或摘要比如文件列表只返回前 50 个大文件内容只返回前 2000 字符。这个坑很隐蔽因为 skill 本身执行成功了问题出在回传环节。6. 进阶技巧用 skill 组合和验证闭环提升可靠性单个 skill 能做的事有限OpenClaw 真正的效率提升来自 skill 的组合调用。比如你可以写一个scan-dirskill 负责列出目录内容一个classifyskill 负责按规则分类一个move-filesskill 负责执行移动然后让模型按顺序调用。这里的关键是每个 skill 的返回值要足够简洁让模型能基于上一步的结果决定下一步调什么。验证闭环是另一个值得投入的方向。我的习惯是在每个 skill 里加一个dryRun参数默认 false当传 true 时只返回“将会执行什么操作”而不实际执行。这样在调试复杂任务链时可以先让模型跑一遍 dry run确认调用顺序和参数都对了再关掉 dry run 实际执行。这个习惯帮我省了很多次误删文件的后悔药。参数建议值说明temperature0.2-0.3工具调用场景需要稳定输出requestTimeout120000本地模型首 token 延迟较高maxTokens4096-8192根据任务复杂度和显存调整dryRuntrue调试时验证调用链而不实际执行最后说一个我自己的习惯每次写完一个新 skill先不接入模型而是用openclaw skill run手动传三组边界参数跑一遍——正常输入、空输入、超长输入。这三组能过再交给模型调用基本不会出大问题。希望帮到你。本文还有配套的精品资源点击获取