简介《OpenClaw完全使用手册202602v1》面向希望上手本地 AI 助手的开发者、运维人员与效率工具爱好者系统梳理了这款开源个人 AI 助手平台从入门到进阶的完整路径。手册围绕本地优先架构、多平台通讯集成、技能插件系统与持久化记忆等核心特性展开覆盖海量玩法攻略、国内网络使用、本地部署指南以及安全与最佳实践四大板块帮助读者解决部署环境准备、模型选择配置、通讯平台接入等实际问题。资源包内含1个PDF文件约3.48MB内容涵盖基础功能、文件与文档处理、浏览器自动化、系统命令执行、技能插件开发以及Windows、macOS、Linux、Docker、云服务器等多种部署方案并附常用命令速查、配置文件参考与故障排除指南。目前已有191人学习适合需要快速掌握OpenClaw本地部署与自动化任务执行的读者参考。1. OpenClaw 完全使用手册从零搭起一套能跑通的本地智能体很多人第一次听到 OpenClaw以为又是一个套壳聊天工具装完发现它其实是一套「本地优先」的智能体运行框架把模型算力、技能skill、工具调用和任务编排拆成可插拔的模块你既能接云端 API也能挂本地推理服务。真正让它出圈的是 skill 机制——你可以把一段重复劳动写成技能让它在本地反复执行而不是每次重新对话。这份手册面向三类人想在自己机器上把 OpenClaw 跑起来的新手、想接本地算力省成本的开发者、想把 OpenClaw 塞进已有工作流比如 Obsidian 笔记、ROS2 机器人调试的工程师。下面按「装得上 → 配得对 → 跑得稳 → 用得巧」的顺序推每一步都给可抄的命令和参数踩过的坑也一并写清楚。2. 部署前先想清楚OpenClaw 的算力接入方式与选型2.1 三种算力接入方式的取舍OpenClaw 最常见的疑问是「只能用接入 API 的方式使用算力吗」。答案是否定的实际有三条路接入方式典型场景延迟成本配置复杂度云端 API快速验证、轻量任务受网络影响按量计费低本地推理Ollama 等隐私数据、离线环境取决于显卡一次性硬件中混合模式敏感任务本地、重任务上云可调度可控高选型逻辑很简单数据不能出内网的直接走本地推理只是做原型验证、对延迟不敏感的云端 API 起步最快已经有本地显卡又想兼顾复杂任务的用混合模式把 skill 里的敏感步骤指向本地端点其余走远端。提示不要一上来就追求全本地。本地推理的显存占用和量化精度会直接影响 skill 的稳定性先用 API 把流程跑通再逐步替换算力后端返工成本最低。2.2 本地推理后端用 Ollama 挂 OpenClaw 的最小配置Ollama 是目前接本地模型最省事的方式。先确认服务在跑# 启动 ollama 服务默认监听 11434 ollama serve # 拉一个中等体量的模型显存 8G 左右可跑 ollama pull qwen2.5:7b # 验证接口通不通 curl http://localhost:11434/api/tags然后在 OpenClaw 的模型配置里指向本地端点。常见做法是改配置文件里的 base_url 和 model 字段# openclaw 模型配置片段 model: provider: openai-compatible # Ollama 兼容 OpenAI 协议 base_url: http://localhost:11434/v1 api_key: ollama # 本地服务占位即可 model: qwen2.5:7b timeout: 120 # 本地推理首 token 慢超时给足逻辑说明Ollama 暴露的是 OpenAI 兼容接口所以 provider 填 openai-compatible 就能复用 OpenClaw 的通用调用链。timeout 是关键参数本地 7B 模型冷启动首 token 可能等十几秒默认 30 秒经常直接超时报错看起来像「连接失败」其实是等不及。api_key 本地服务不校验但不能留空留空有些客户端会直接拒绝请求。2.3 Windows 与 Linux含 Kylin环境的差异处理Windows 上跑 OpenClaw最容易翻车的是路径和换行符。配置文件里写相对路径时Windows 用反斜杠会被 YAML 解析器当成转义统一用正斜杠或双反斜杠。Linux 侧Kylin 等国产系统常见问题是自带的 Python 版本偏旧OpenClaw 依赖的部分库要求 3.10 以上建议用虚拟环境隔离# Kylin / 通用 Linux 下建虚拟环境 python3 -m venv openclaw-env source openclaw-env/bin/activate pip install -U pip pip install -r requirements.txt # 确认版本低于 3.10 直接换源装新版 python --versionWindows 侧如果要用 companion 模式把本机当作执行节点注意防火墙会拦本地回环以外的端口配置里绑定地址写 127.0.0.1 而不是 0.0.0.0既避开弹窗又更安全。这一步没有玄学纯粹是系统差异但每年都有人在这卡半天。3. 安装与首次启动把 OpenClaw 跑起来的最小闭环3.1 从零到能对话的四个步骤第一步拉代码并装依赖。第二步生成默认配置。第三步填模型端点。第四步启动并验证。四步里任何一步跳过后面都会以奇怪的方式报错。# 1. 获取代码按你实际拿到的分发方式替换 git clone openclaw-repo cd openclaw # 2. 安装依赖建议在虚拟环境内 pip install -r requirements.txt # 3. 生成默认配置 python -m openclaw init --config ./config.yaml # 4. 启动服务 python -m openclaw serve --config ./config.yaml --host 127.0.0.1 --port 8080参数说明--config指定配置文件路径多环境时用不同文件区分--host和--port决定监听地址本地自用绑 127.0.0.1init子命令生成的配置里模型段是空的必须手动补上第 2 章那套 base_url 和 model否则启动不报错但一发消息就 401。启动成功后用一条最小请求验证闭环curl -X POST http://127.0.0.1:8080/v1/chat \ -H Content-Type: application/json \ -d {message:ping,session:test-001}返回里带正常文本就说明模型链路通了。如果返回超时先回去看模型端点的 timeout如果返回 401检查 api_key 是否留空如果连接被拒确认服务真的在监听而不是启动脚本提前退出了。3.2 配置文件里必须改的五个字段默认配置能启动但基本不能用。以下五个字段是血泪经验里出现频率最高的server: host: 127.0.0.1 port: 8080 model: base_url: http://localhost:11434/v1 model: qwen2.5:7b timeout: 120 skills: dir: ./skills # 技能目录不配就找不到自定义 skill autoload: true logging: level: info # 排查阶段调 debug稳定后回 info file: ./logs/openclaw.logskills.dir和autoload决定你的自定义技能能不能被扫到很多人写完 skill 发现不生效就是这两个没配。logging.level在排查阶段一定调成 debug否则错误信息被吞掉只能看到一句「执行失败」等于黑匣子。3.3 用 Termux 在安卓上做轻量部署的边界热搜里「openclaw 安卓部署」「termux 安装 openclaw」问得很多。Termux 能装 Python 环境理论上能跑 OpenClaw 的服务端但要有心理预期手机端只适合做控制端或轻量 skill 调度本地推理基本别想算力还是得指向外部端点。# Termux 内准备环境 pkg update pkg install python git python -m venv oc-env source oc-env/bin/activate pip install -r requirements.txt # 启动时绑定本地模型指向局域网内的推理机 python -m openclaw serve --config ./config.yaml --host 127.0.0.1 --port 8080关键点手机上的 config.yaml 里 base_url 要写局域网内那台推理机的地址不能写 localhost否则它找的是手机自己。另外 Termux 后台进程容易被系统回收长期跑要配合唤醒锁这一点和桌面端体验差距明显别指望手机当稳定服务器。4. Skill 机制把重复劳动写成可复用的技能4.1 skill 的目录结构与加载规则OpenClaw 的 skill 本质是一个带元信息的可执行单元。常见结构是每个技能一个子目录里面放描述文件和入口脚本skills/ daily_report/ skill.yaml # 元信息名称、触发词、参数 run.py # 入口逻辑 file_clean/ skill.yaml run.pyskill.yaml决定这个技能怎么被识别和调用name: daily_report description: 汇总当日日志并生成简报 trigger: - 生成日报 - daily report params: - name: date type: string required: false default: today entry: run.py逻辑说明trigger 是自然语言触发词用户消息命中后 OpenClaw 会把参数解析出来传给入口脚本。params 里 required 为 false 的字段要有 default否则解析不到时直接抛错。entry 指向的脚本必须可执行Linux 下记得 chmod xWindows 下确认 Python 关联正确。4.2 写一个能跑的最小 skill下面这个技能读取指定日期的日志文件统计行数并返回摘要是最小可运行模板# skills/daily_report/run.py import sys import json from pathlib import Path def main(): # OpenClaw 通过 stdin 传入 JSON 参数 payload json.loads(sys.stdin.read()) date payload.get(date, today) log_path Path(f./logs/{date}.log) if not log_path.exists(): # 返回结构固定error 字段会被上层识别 print(json.dumps({error: f日志不存在: {log_path}})) return lines log_path.read_text(encodingutf-8).splitlines() error_lines [l for l in lines if ERROR in l] print(json.dumps({ total: len(lines), errors: len(error_lines), sample: error_lines[:3] }, ensure_asciiFalse)) if __name__ __main__: main()逻辑说明OpenClaw 调用 skill 时通过标准输入传 JSON脚本通过标准输出返回 JSON这是最稳的约定不依赖任何框架内部 API。返回结构里约定error字段表示失败其余字段作为结果透传。ensure_asciiFalse保证中文不被转义成乱码这个细节不注意返回的摘要会变成一串\uXXXX。参数说明date 默认 today实际使用时由触发词里的时间表达解析而来日志路径按你的实际目录调整写死相对路径时注意工作目录是 OpenClaw 启动目录不是 skill 目录这是新手最常踩的坑之一。4.3 skill 调试怎么定位「执行失败」到底失败在哪skill 不生效时按这个顺序排查先看 logging.level 是不是 debug再看 skill 有没有被 autoload 扫到然后手动模拟一次调用。# 手动喂参数绕过 OpenClaw 直接测脚本 echo {date:2026-02-01} | python skills/daily_report/run.py # 看服务日志里 skill 的加载记录 grep -i skill ./logs/openclaw.log如果手动跑通、通过 OpenClaw 却失败问题多半在参数解析或工作目录如果手动都跑不通就是脚本本身的问题跟框架无关。分清楚这两层能省掉大量无效排查。5. 避坑与排查那些让 OpenClaw 看起来「不能用」的问题5.1 现象启动成功但一发消息就超时原因本地推理首 token 延迟高默认 timeout 太短请求在模型出第一个字之前就被掐断。解决把模型配置里的 timeout 提到 120 秒以上同时确认模型确实加载完成ollama ps能看到运行中的模型再发请求。5.2 现象skill 写了但触发词没反应原因skills.dir 路径不对或 autoload 为 false或 skill.yaml 的 trigger 写成了用户不会说的表达。解决先确认日志里有加载记录再把 trigger 改成用户真实会输入的说法别用书面语。5.3 现象Windows 下配置文件读取报编码错误原因配置文件存成了 GBK解析器按 UTF-8 读。解决统一另存为 UTF-8 无 BOM路径分隔符用正斜杠。这个坑在中文 Windows 上出现频率极高。5.4 现象Termux 里跑一会儿进程就没了原因安卓系统回收后台进程。解决加唤醒锁或接受它只能做短时任务长期服务还是放桌面端或服务器。别在这上面耗太久方向本身就不对。5.5 现象接了本地模型后回答质量明显下降原因模型体量太小或量化过度复杂 skill 的推理步骤撑不住。解决把复杂任务拆成多个简单 skill 分步执行或对关键步骤切回云端 API混合模式就是为这种场景准备的。6. 进阶把 OpenClaw 接进已有工作流的两个实用技巧第一个技巧是让 OpenClaw 和 Obsidian 联动。Obsidian 的库本质是一堆 Markdown 文件你可以写一个 skill 扫描指定目录把当天新增笔记汇总成摘要再写回一个索引文件。核心不是技术难度而是路径约定skill 里读写的目录要用绝对路径或相对 OpenClaw 启动目录的稳定路径别依赖当前工作目录否则换个启动方式就找不到文件。第二个技巧是用 skill 做 ROS2 调试辅助。热搜里「rosclaw openclaw ros2 humble gazebo」这类组合实际落地方式是把 ROS2 的日志和话题状态通过一个 skill 拉出来让模型做异常归纳。这里要注意skill 只做数据采集和格式化判断逻辑交给模型别在脚本里写死规则否则模型的价值就没了。验证一个 skill 是否值得沉淀我的习惯是看它一周内被触发几次。触发少于两次的说明要么触发词不对要么这个需求本身是伪需求直接删掉别让技能目录变成垃圾场。这套手册里的每个参数都是我在真实环境里调出来的你照着走能少走弯路。希望帮到你。本文还有配套的精品资源点击获取