简介《OpenClaw完全使用手册202602v1》面向希望上手开源个人AI助手平台的开发者与进阶用户聚焦本地部署、国内网络环境适配与技能插件扩展三大核心诉求。OpenClaw以本地优先架构运行可通过Telegram、飞书、钉钉等平台交互并具备文件读写、终端命令执行、浏览器自动化等执行能力手册围绕这些能力给出系统化指引。资源包为1个PDF文件约3.48MB内容涵盖基础功能、文档处理、浏览器自动化、通讯平台集成、技能插件系统与高级应用场景并专章讲解国内部署环境准备、模型选择配置及常见问题解决另附Windows、macOS、Linux、Docker与云服务器多平台部署指南以及安全加固、权限管理、监控审计与命令速查、配置参考、故障排除等附录。目前已有191人学习适合需要从零搭建并深度定制个人AI助手的读者按目录逐章查阅。1. 从一台吃灰的迷你主机说起OpenClaw 到底能帮你干什么上个月我把一台 N100 的迷你主机从柜子里翻出来本来想装个 NAS 就完事后来发现用它跑 OpenClaw 才是这台机器最舒服的归宿。简单说OpenClaw 是一个可以完全跑在本地环境里的 AI 助手框架它把「模型推理」和「技能插件」拆成了两层底层可以接本地模型也可以接云端 API上层通过 skill 插件机制让助手能真正去操作文件、执行命令、调用外部服务而不是只会在对话框里聊天。这跟网页版助手最大的区别在于你的数据、你的脚本、你的工作流都留在自己机器上插件想怎么改就怎么改。适合谁一类是手里有闲置 Linux 小主机、想搭个私人自动化助手的后端开发另一类是不放心把内部文档丢给在线服务、但又确实需要 AI 帮忙处理重复劳动的团队。这篇就按我实际部署和调试的顺序把安装、配置、skill 编写和几个血泪坑一次讲透。2. 部署前先把架构想清楚本地模型还是 API 接入2.1 OpenClaw 的两层结构决定了你怎么选算力很多人一上来就问「OpenClaw 只能用接入 API 的方式使用算力吗」其实不是。它的设计把「推理后端」和「助手运行时」解耦了你可以理解成两块积木推理层负责把自然语言变成模型输出。可以是本地跑的模型服务比如用 Ollama 拉一个量化模型也可以是任何兼容 OpenAI 接口规范的远程端点。运行时层OpenClaw 本体负责管理会话、加载 skill 插件、调度工具调用、维护上下文。这个分层带来的直接好处是你可以在同一台机器上先接本地模型跑通流程等发现算力不够再换成 API配置文件里改一个base_url和model字段就行skill 代码一行不用动。反过来也一样先用 API 验证业务逻辑再迁到本地做数据隔离。选型上我的建议很直接如果你只是想让助手处理文本、写写脚本、整理文件本地 7B 到 14B 的量化模型足够如果你需要它读长文档、做复杂推理、稳定调用多个 skill本地小模型会频繁翻车这时候接 API 更省心。别一上来就追求全本地先跑通再优化这是我踩过的最大的时间坑。2.2 硬件和系统的最低门槛OpenClaw 本体对机器要求不高真正吃资源的是本地推理。下面这张表是我在几种常见环境下的实测感受供你判断自己的机器能不能扛环境内存推理方式实际体验N100 迷你主机 / Ubuntu 22.0416GBOllama 7B 量化日常对话和简单 skill 流畅长上下文会慢旧笔记本 / Windows 11 WSL216GBOllama 7B 量化可用但 WSL 内存回收要注意云服务器 2C4G4GB仅接 API本体跑得动本地推理别想开发机 / macOS16GB本地或 API体验最均衡系统层面Linux 是最省事的Windows 用户建议走 WSL2别硬扛原生环境。安卓端通过 Termux 也能装但那是应急方案不适合长期跑后面避坑章节会细说。2.3 安装前的依赖清单在动手之前把这几样确认好能省掉后面一半的报错# 确认系统版本和架构 uname -a # 确认 Python 版本建议 3.10 以上 python3 --version # 确认 pip 可用 pip3 --version # 如果要用本地模型先装好 Ollama ollama --version逻辑说明OpenClaw 本体是 Python 写的所以 Python 版本是第一道门槛低于 3.9 会在装依赖时直接失败。uname -a是为了确认你是 x86 还是 ARMARM 环境下部分预编译包可能缺失需要源码编译。Ollama 不是必须的但如果你想走本地推理提前装好能避免后面来回切换。参数上没什么可调的唯一要注意的是 pip 源。国内环境建议换成镜像源否则装依赖能等到你怀疑人生pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这条命令是写进用户级配置的不影响系统其他 Python 环境后悔了用pip3 config unset global.index-url就能撤。3. 从零跑通第一个会话安装、配置与模型对接3.1 拉取本体与初始化配置目录OpenClaw 的安装方式取决于你拿到的分发包形态。常见做法是克隆仓库后本地安装# 克隆项目到本地 git clone openclaw-repo-url openclaw cd openclaw # 创建独立虚拟环境避免污染系统 Python python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt逻辑说明用虚拟环境是硬性习惯因为 OpenClaw 的依赖里可能包含特定版本的 HTTP 库和模型 SDK跟系统里其他项目冲突是迟早的事。source venv/bin/activate之后你所有的 pip 安装都只作用于这个目录删掉 venv 文件夹就等于卸载干净。初始化配置目录一般在首次启动时自动生成也可以手动建# 创建配置目录 mkdir -p ~/.openclaw # 复制示例配置 cp config.example.yaml ~/.openclaw/config.yaml~/.openclaw/config.yaml是核心配置文件后面所有模型和 skill 的设置都在这里改。建议先备份一份原始文件改坏了能快速回滚。3.2 对接本地模型以 Ollama 为例如果你走本地推理配置大概长这样# ~/.openclaw/config.yaml model: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 api_key: ollama model: qwen2.5:7b max_tokens: 2048 temperature: 0.7逻辑说明Ollama 默认在 11434 端口提供兼容 OpenAI 的接口所以provider填openai_compatible就能直接对接。api_key随便填Ollama 不校验但字段不能空否则某些客户端库会报错。model要跟你ollama list里看到的名称完全一致大小写和标签都不能错。参数上max_tokens控制单次回复长度本地小模型建议别超过 2048否则生成慢且容易跑偏。temperature是创造性参数做文件整理、命令执行这类任务时建议调到 0.2 到 0.3减少它自作主张的概率。启动 Ollama 并拉模型# 启动服务 ollama serve # 拉取模型首次会下载几个 GB ollama pull qwen2.5:7b # 验证模型可用 ollama run qwen2.5:7b 你好3.3 对接 API改三个字段的事如果你决定用远程 API配置改成这样model: provider: openai_compatible base_url: https://your-api-endpoint/v1 api_key: sk-your-key-here model: your-model-name max_tokens: 4096 temperature: 0.5逻辑说明跟本地配置唯一的区别就是base_url和api_key。这里要注意base_url一定要带/v1后缀很多兼容接口不带这个后缀会 404。api_key建议用环境变量注入别硬编码在配置文件里export OPENCLAW_API_KEYsk-your-key-here然后在配置里写api_key: ${OPENCLAW_API_KEY}这样配置文件即使被同步或备份密钥也不会泄露。3.4 启动并验证第一个会话配置好之后启动本体# 激活虚拟环境 source venv/bin/activate # 启动 OpenClaw python -m openclaw start # 或者用提供的启动脚本 ./scripts/start.sh启动后如果看到监听端口的日志说明本体起来了。用 curl 验证一下curl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {message: 列出当前目录下的文件}逻辑说明这个请求会走完整的「接收消息 → 模型推理 → 返回结果」链路。如果返回正常文本说明模型对接成功如果返回超时多半是模型服务没起来或者base_url写错如果返回 401检查api_key。到这一步一个能对话的 OpenClaw 就跑起来了。但真正让它有用的是下一步的 skill 插件。4. 写一个能干活儿的 skill插件机制与实战4.1 skill 的加载逻辑和目录约定OpenClaw 的 skill 本质上是一个带元信息的 Python 模块放在指定目录下会被自动扫描加载。常见约定是项目根目录下的skills/文件夹每个 skill 一个子目录skills/ file_organizer/ __init__.py skill.py manifest.yamlmanifest.yaml描述这个 skill 叫什么、干什么、需要什么参数本体靠它决定什么时候把任务路由过来。skill.py里是实现逻辑。这个设计的好处是插件之间完全隔离删掉一个目录就等于卸载一个 skill不会影响本体。4.2 一个文件整理 skill 的完整实现下面这个例子实现「把指定目录下的文件按扩展名分类到子文件夹」# skills/file_organizer/skill.py import os import shutil from pathlib import Path def organize(directory: str, dry_run: bool True) - dict: 按扩展名整理目录下的文件 :param directory: 目标目录 :param dry_run: 为 True 时只打印计划不实际移动 target Path(directory).expanduser().resolve() if not target.is_dir(): return {error: f{target} 不是有效目录} plan {} for item in target.iterdir(): if item.is_file(): ext item.suffix.lower().lstrip(.) or no_ext plan.setdefault(ext, []).append(item.name) if dry_run: return {dry_run: True, plan: plan} moved 0 for ext, files in plan.items(): sub target / ext sub.mkdir(exist_okTrue) for name in files: shutil.move(str(target / name), str(sub / name)) moved 1 return {dry_run: False, moved: moved, groups: list(plan.keys())}逻辑说明dry_run参数是这个 skill 最关键的设计默认 True 意味着第一次调用只返回计划不实际动文件确认无误后再传 False 执行。expanduser()处理~路径resolve()把相对路径转成绝对路径避免因为工作目录不同导致操作错地方。返回结构统一用 dict方便本体把结果转成自然语言回复。对应的manifest.yamlname: file_organizer description: 按扩展名整理指定目录下的文件 parameters: - name: directory type: string required: true description: 要整理的目录路径 - name: dry_run type: boolean required: false default: true description: 是否只预览不执行参数说明required决定模型是否必须提供这个参数default是模型没给时的兜底值。description写清楚很重要模型是靠这段文字判断什么时候该调用这个 skill 的写得含糊它就会乱调。4.3 调试 skill 的常用手段skill 写完不生效先看本体日志里有没有加载记录。常见做法是启动时加--log-level debugpython -m openclaw start --log-level debug然后在日志里搜 skill 名字能看到「loaded」「skipped」「error」三种状态。如果显示 skipped多半是manifest.yaml格式有问题如果显示 error看堆栈定位到具体行。单独测试 skill 逻辑不用每次都走模型# 直接调用函数验证 from skills.file_organizer.skill import organize print(organize(~/Downloads, dry_runTrue))这样能把「skill 本身有没有 bug」和「模型有没有正确调用 skill」两个问题分开排查效率高很多。5. 避坑与排查那些让我重装三次的问题5.1 模型返回正常但 skill 从不触发现象对话能正常回复但让它整理文件它只会说「好的我来帮你整理」然后就没有然后了。原因manifest.yaml里的description写得太泛或者参数描述跟用户说法对不上模型判断不出该调用哪个 skill。解决把description写成具体的动作描述比如「当用户要求按文件类型分类、整理下载目录时调用」而不是「文件整理工具」。参数描述也尽量贴近用户口语模型匹配靠的是语义相似度。5.2 本地模型把 skill 参数编错现象skill 被触发了但传进来的directory是「我的下载文件夹」这种自然语言不是真实路径。原因小模型对参数格式的理解能力有限尤其是 7B 以下的模型。解决两个方向。一是换更大的模型14B 以上明显改善二是在 skill 里做参数清洗把常见口语映射成真实路径PATH_ALIASES { 下载: ~/Downloads, 桌面: ~/Desktop, 文档: ~/Documents, } def normalize_path(raw: str) - str: for key, real in PATH_ALIASES.items(): if key in raw: return os.path.expanduser(real) return os.path.expanduser(raw)这个映射表按自己习惯维护比指望模型每次都输出标准路径靠谱得多。5.3 Termux 里装完跑不起来现象在安卓 Termux 里按教程装完启动就报缺少编译好的 wheel。原因Termux 是 ARM 环境部分依赖没有预编译包pip 会尝试源码编译而 Termux 默认缺编译工具链。解决先pkg install python clang rust把工具链补齐再装依赖。但说实话Termux 方案只适合临时验证长期跑建议还是用 Linux 小主机性能和稳定性都不是一个量级。5.4 配置文件改了不生效现象改了config.yaml里的模型重启后还是用旧的。原因OpenClaw 可能同时读了项目目录下的配置和~/.openclaw/config.yaml优先级搞反了。解决用--config显式指定配置文件路径避免歧义python -m openclaw start --config ~/.openclaw/config.yaml同时检查环境变量里有没有覆盖配置的项环境变量优先级通常高于文件。5.5 长对话后响应越来越慢现象刚开始很快聊了几十轮之后每次回复要等很久。原因上下文越堆越长本地模型处理长上下文的开销是线性甚至超线性增长的。解决在配置里设置上下文窗口上限和历史裁剪策略context: max_history: 20 strategy: sliding_windowmax_history控制保留最近多少轮对话sliding_window是滑动窗口裁剪超出就丢最旧的。做任务型对话时这个值可以设小一点10 到 15 轮足够。6. 进阶让 skill 组合起来干复杂活儿单个 skill 能做的事有限OpenClaw 真正有意思的地方是让模型自己编排多个 skill。比如「把下载目录里的图片挑出来压缩后放到归档文件夹」这个任务可以拆成三个 skilllist_files、compress_image、move_files模型根据 manifest 里的描述依次调用。这里有个技巧在 skill 的 description 里写明前置条件和输出模型编排的准确率会明显提升。比如compress_image的描述写成「输入是图片文件路径列表输出是压缩后的文件路径列表需在 list_files 之后调用」模型就能理解调用顺序。验证 skill 组合是否按预期执行我习惯在本地开一个追踪日志# 在 skill 入口加一行追踪 import logging logging.basicConfig(filenameskill_trace.log, levellogging.INFO) def compress_image(paths: list) - dict: logging.info(fcompress_image called with {len(paths)} files) # ... 实际逻辑跑完之后看skill_trace.log调用顺序、参数、返回一目了然。这个习惯帮我定位过好几次「模型跳过了某个 skill 直接编结果」的问题。还有一个容易被忽略的点skill 的返回值尽量结构化别返回一大段自然语言。模型拿到结构化数据后自己会组织语言回复用户你返回自然语言反而容易让它二次加工出错。我一般返回{status: ok, data: {...}}这种格式需要展示给用户的文本让模型自己生成。从那以后我每次写完新 skill都强制走一遍「dry_run 预览 → 单测函数 → 接入对话验证 → 看追踪日志」这四步再也没出现过 skill 误操作文件的情况。希望这些经验帮到你少走点我踩过的弯路。本文还有配套的精品资源点击获取