老早之前我就想搞一个能随时喊一声就帮忙查资料、写文案、管日程的 AI 助手但市面上的方案总差点意思——要么只能打开网页聊要么接不上我日常用的微信要么没法按我的习惯干活。后来我找到了 OpenClaw一个开源的个人 AI 助手框架折腾了几天总算把它完整跑起来了。这篇文章就把我的完整安装过程、踩过的坑和配置技巧整理出来从环境准备到接入本地模型再到写自定义技能尽量写得让小白也能顺着走通。OpenClaw 本质上是一套AI 助手外壳它把大模型能力、消息渠道、自动化任务和工具调用整合在一起。你不需要自己从零写代码去调用各家模型 API也不需要为每个聊天平台维护一套机器人逻辑。装好之后你只需要在配置文件里声明用哪个模型、接哪个渠道再给它写几个技能它就能变成一个真正属于你的助手。适合谁想自己部署 AI 助手的人、想把助手接到微信或飞书的人、想用本地模型保护隐私的人以及想在 AI Agent 方向上练手的人都可以从这篇文章里找到可落地的内容。1. 项目概述与方案选择先搞清楚 OpenClaw 到底是什么1.1 一句话理解 OpenClawAI 助手的总调度OpenClaw 是一个开源的个人 AI 助手框架核心思想是把模型和工具解耦。模型负责理解和生成工具负责执行。你作为使用者只需要定义好模型从哪里来、有哪些工具可以用以及助手出现在哪些聊天渠道里。我自己的理解是它像一个总调度你告诉它帮我干嘛它先调大模型思考怎么做再调用对应的工具或者 API 去完成。比如你说帮我把这篇文档总结一下发到飞书它就会调用文本处理能力、文档读写能力和飞书机器人能力一步步完成。这个机制跟市面上的 Agent 框架思路一致但 OpenClaw 更偏个人使用场景安装和配置门槛相对低一些。1.2 它解决了哪些痛点适合谁如果你只用一个 ChatGPT 网页版可能觉得没必要装这么一套东西。但当你开始有这些需求时OpenClaw 的价值就出来了你想在微信、飞书、Telegram 等多个地方唤起同一个助手而不是每个平台单独维护一个 bot。你想让助手定时干活比如每天早上汇总新闻发给你的飞书。你想接入私有数据或本地模型所有对话和记录都留存在自己的机器上。你想给助手定义一些专属技能比如用固定风格写小说帮我查某个 API 的数据普通聊天工具做不到这种定制。所以它特别适合两类人一类是技术爱好者喜欢折腾、希望拥有一套完全可控的 AI 基础设施另一类是重度知识工作者日常大量依赖 AI 处理信息需要一个能嵌进工作流的助手。1.3 部署方式怎么选源码、Docker 还是一键脚本OpenClaw 的部署方式我实测下来大致有三条路各有优劣方式优点缺点适合谁源码安装最灵活改代码方便方便调试 skill依赖环境多新手容易卡在 Node 版本或依赖安装上想深度定制、后续要开发 skill 和插件的人Docker 部署环境隔离升级方便不污染宿主机数据卷和端口映射需要理解本地改代码不如源码直观追求稳定、不想折腾环境的人推荐新手一键脚本快输入命令就完事黑盒出了问题不好排查也不方便自定义只想快速体验的人我个人的建议是如果你打算长期用、后面会写不少 skill就直接源码安装虽然前期折腾一点但调试起来很顺手。如果你只是先体验一下或者对命令行不熟那就老老实实用 Docker遇到问题删掉容器重来也不心疼。2. 环境准备与前置条件动手前先把这几样装好2.1 硬件和系统要求很多人一听到 AI 助手就以为要很高的配置其实看你怎么用。如果你只是通过 API 调用云端的模型OpenClaw 本身只是一个管家程序4 核 CPU、8GB 内存的机器就够跑了。你平时的树莓派、旧笔记本、云服务器都能胜任。真正吃配置的是本地模型。你要是打算完全离线推理就按模型大小来评估资源。以 7B 参数左右的模型为例量化版本大概需要 8GB 左右的显存内存至少 16GB 起步没有独显纯 CPU 跑也能跑但速度会慢得让人着急。我劝新手别一上来就上 70B 大模型先拿小模型跑通流程后面再慢慢加资源。2.2 安装 Docker Desktop 并验证可选但推荐如果你走 Docker 路线需要先装好 Docker。Windows 和 macOS 用户直接装 Docker Desktop 就行Linux 用户安装 Docker Engine 加 docker compose 插件。装完之后记得验证一下环境docker --version docker compose version有版本号输出就说明没问题。我遇到过的情况是 Windows 上 Docker Desktop 装好但一直起不来后来发现是 WSL 2 没启用去 BIOS 打开虚拟化、在控制面板启用适用于 Linux 的 Windows 子系统之后就好了。这个坑比较常见大家留意一下。麒麟桌面这类国产 Linux 系统我实测也能装直接按 Linux 方式装 Docker Engine注意一下 CPU 架构是 x86 还是 ARM 就行后面拉镜像的时候会用到。2.3 准备 Git 和 Node.js 环境源码安装 OpenClaw 需要 Git 和 Node.js。Git 用来拉取代码Node.js 用来跑服务。Node 版本建议用 20 以上太老的版本容易在安装依赖的时候报错。装好之后同样验证一下git --version node -v npm -v如果你机器上已经有其他 Node 项目版本不一致也没关系可以用 nvm 做多版本管理按项目切换 Node 版本。我一开始直接装系统级 Node后来做别的项目要降版本就折腾了一阵子建议有条件的人直接用 nvm。2.4 提前准备好模型服务云 API 或本地模型OpenClaw 本身不带模型它需要连接一个模型后端。这一步建议在安装 OpenClaw 之前就准备好否则装好之后也没法对话。方案 A 是云端 API。OpenAI、DeepSeek、通义千问这些服务商都提供兼容接口你只需要注册账号、创建一个 API Key。以 DeepSeek 为例去开放平台创建一个 Key记下来备用。方案 B 是本地模型。Ollama 是我用得最多的方案安装后执行ollama pull qwen2.5:7b就能把模型拉下来非常省事。NVIDIA NIM 是另一种方式用容器跑模型适合有 NVIDIA 显卡的人。后面我会专门讲怎么在 OpenClaw 里配置这两种方案。3. 安装实操从零到跑通 OpenClaw3.1 源码安装完整流程源码安装的核心步骤就是四件事拉代码、装依赖、配环境、启动。先克隆仓库。到 GitHub 搜索 OpenClaw 官方仓库复制链接后执行git clone OpenClaw 官方仓库地址 cd openclaw然后安装依赖。OpenClaw 的依赖比较多npm install可能要跑几分钟npm install这一步我经常遇到卡住不动的情况多半是网络原因。可以切换到国内 npm 镜像源再试npm config set registry https://registry.npmmirror.com npm install依赖装完之后会有一个初始化流程引导你填写配置文件。先复制环境变量模板cp .env.example .env然后在.env里填你的 API Key、默认模型名等关键信息。有些版本提供了npm run setup这个交互命令跟着提示走就行它会自动生成主配置文件。最后启动npm start看到类似OpenClaw is running的日志基本就成功了。3.2 Docker 一行命令部署推荐新手Docker 部署相比源码安装会简单不少。官方提供了镜像配置通过环境变量注入数据目录通过卷挂载出来。我写了一份最简 docker-compose.yml你可以直接参考version: 3 services: openclaw: image: openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - 3000:3000 environment: - OPENCLAW_MODEL_PROVIDERdeepseek - OPENCLAW_MODEL_NAMEdeepseek-chat - OPENCLAW_API_KEYsk-你的密钥 volumes: - ./openclaw-data:/data然后执行docker compose up -d查看日志确认启动状态docker compose logs -f如果日志里有报错先别慌去倒数几行找关键错误信息多半是 API Key 填错或者网络连不上。Docker 的好处就在这里出问题改完配置执行docker compose restart就行不用重装。3.3 遇到 Control UI did not start 怎么办Control UI 是 OpenClaw 自带的 Web 控制台可以在浏览器里管理会话、查看配置、调试 skill。但不少人都遇到过它起不来的情况报错信息一般就是Control UI did not start。我排查这个问题时通常按顺序做三件事第一看端口占用。Control UI 会监听一个默认端口如果你机器上那个端口被别的程序占了它自然起不来。可以用netstat -ano | findstr 端口号Windows或者ss -lntp | grep 端口号Linux查看。第二确认 Node 版本。有些版本的 Control UI 对 Node 版本有要求20 以下是高危区。用node -v看看如果版本太低就升级。第三清理缓存后重启。浏览器缓存有时候会让控制台页面显示不出来换个无痕窗口试试。服务端也可以清一下 npm 缓存再重启。如果你的 Control UI 是通过单独子命令启动的记得先启动主服务再启动控制台顺序反了它也可能起不来。3.4 首次对话验证确认助手真的活了安装完成之后先别急着接各种渠道第一件事是验证助手能不能正常对话。打开 Control UI 的地址创建一个新的会话发一句你好。如果配置没问题几秒钟内就能收到回复。这时候观察两件事一是回复速度二是日志里有没有报错。如果你配置的是云端 API回复速度通常比较快如果你配置的是本地模型第一次加载模型会慢一些需要多点耐心。日志里如果出现agent failed before reply之类的字样大概率是模型配置的问题下一节我会详细讲。4. 模型接入与核心配置让助手变聪明4.1 配置文件关键字段解析OpenClaw 的配置核心是模型提供方provider和模型model两层。provider 定义了这个模型从哪里来、鉴权信息是什么model 定义了你具体用哪个模型。一个典型的模型配置看起来是这样{ model: { default: deepseek-chat, providers: { deepseek: { baseUrl: https://api.deepseek.com/v1, apiKey: sk-你的密钥, supportedModels: [deepseek-chat, deepseek-reasoner] } } } }这里的关键点是baseUrl。很多 OpenAI 兼容接口的地址必须要带/v1不少新手漏了这个尾巴结果请求一直 404。default字段指定默认使用的模型 ID这个 ID 必须和supportedModels里的某一个完全一致否则就会报找不到模型。4.2 高频报错 unknown model 的根因与解决有个报错在 OpenClaw 用户里非常常见基本每个新手都会遇到agent failed before reply: unknown model: deepseek这句话的意思是你把默认模型写成了deepseek但配置里能用的模型列表中根本没有叫deepseek的只有deepseek-chat或deepseek-reasoner。解决办法很简单把配置里的模型 ID 改成真实存在的名字。或者有些版本支持别名alias你可以给一个模型起个短名字方便记忆。但我的建议是直接用官方模型的完整 ID省得后面混淆。另外我提醒一句网上很多教程会让你在配置里写model: deepseek那是人家在某个特定版本里的写法不代表你也能用。遇到 unknown model直接去看你 API 服务商文档里的模型列表把准确的模型 ID 抄进去。4.3 接入本地模型Ollama 与 NVIDIA NIM本地模型最大的优势是隐私可控所有对话数据不出你这台机器。对于不想把聊天记录送到云端的人这是刚需。先说 Ollama。安装 Ollama 之后先拉模型ollama pull qwen2.5:7b然后启动 Ollama 服务ollama serve这个时候 Ollama 会在本机 11434 端口暴露一个 OpenAI 兼容接口。在 OpenClaw 里这样配置{ model: { default: qwen2.5:7b, providers: { ollama: { baseUrl: http://localhost:11434/v1, apiKey: ollama, supportedModels: [qwen2.5:7b] } } } }注意apiKey随便填一个值占位就行Ollama 本地接口不校验 Key。再说 NVIDIA NIM。如果你有 NVIDIA 显卡并且想体验更好的本地推理性能NVIDIA NIM 是另一个好选择。它本质上是用容器把模型服务跑起来同样暴露一个 OpenAI 兼容 API。安装 NIM 容器后把它的baseUrl填到 OpenClaw 配置里即可。我个人的体会是Ollama 胜在轻量、上手快适合绝大多数个人用户NVIDIA NIM 性能更强但配置复杂度高不少适合对推理速度有要求的人。4.4 多模型切换与降级策略日常使用中就算配置好了模型也难免遇到 API 限流、服务波动或者额度用完的情况。我习惯同时配置两家模型一个做主模型一个做备用。比如主模型用 DeepSeek便宜且速度快备用模型用通义千问的兼容接口。主模型挂了就手动切到备用。如果你用的是 GitHub Copilot 或者其他编程助手其实也能从 OpenClaw 接但那是另一个话题这里不多说。在配置里备用模型和主模型一样定义切换的时候改一下default字段重启服务就生效。如果版本支持 fallback 配置可以直接让它在主模型失败时自动重试备用模型。5. 渠道接入把助手接到微信和飞书5.1 微信接入实操与风险提示微信是很多人第一个想接的渠道因为日常使用频率实在太高。但这里我必须先泼一盆冷水微信个人号官方并不开放机器人接口所有第三方接入方案都游走在灰色地带有封号风险。如果你只是自己测试建议用小号别拿主号去试。OpenClaw 的微信接入方式通常是在渠道配置里启用 wechat 相关的配置项填上你的账号凭证或者 webhook 地址。以 webhook 方式为例思路是微信侧收到消息后转发到 OpenClaw 暴露的接口OpenClaw 处理完再通过接口把回复发回去。企业微信和公众号的官方接口会更稳定个人号方案虽然也能跑通但我见过不少朋友用了一阵子就被限制登录了。所以我的建议是如果一定要接微信优先考虑企业微信或者公众号这是官方支持的正规路径个人微信只适合短时间体验。5.2 飞书机器人接入步骤如果你用飞书办公把 OpenClaw 接进飞书会非常爽。飞书开放平台对机器人支持很完善创建应用、开启机器人能力、配置事件订阅三步就能搞定。具体步骤大概是去飞书开放平台创建一个企业自建应用拿到 App ID 和 App Secret。在应用能力里开启机器人能力。配置事件订阅把回调 URL 填成 OpenClaw 提供的事件接收地址。在 OpenClaw 渠道配置里填入 App ID、App Secret启用飞书渠道。飞书这边有一点要注意如果你的 OpenClaw 跑在内网机器上飞书服务器得能访问到你的回调地址。没有公网 IP 的话你需要用内网穿透工具把本地端口暴露出去并且最好配一个固定的域名免得每次重启 IP 都变。5.3 多渠道并存时的会话管理我的 OpenClaw 同时接了飞书和 Telegram刚开始发现一个问题我在飞书里和它聊了一半的事跑到 Telegram 里它完全想不起来。后来我理解了OpenClaw 默认按渠道和会话维度隔离上下文。这其实是合理的——不同渠道、不同对话场景记忆理应是分开的否则你在公司群里问的东西和私聊里问的东西混在一起会非常尴尬。所以如果你也想多渠道并用不用纠结上下文不共享这恰恰是框架的设计取舍。你只需要记住每个渠道的对话历史是独立的想跨渠道延续话题就把上下文信息明确写在新的对话里。6. 扩展玩法用 Skill 让助手学会新技能6.1 Skill 的工作原理与目录结构Skill 是 OpenClaw 最打动我的功能它相当于给助手装上了外挂工具。普通的聊天机器人只能动嘴而带 Skill 的 OpenClaw 能动手。一个 Skill 通常包含两部分一个描述文件SKILL.md和一个或多个可执行脚本。描述文件告诉模型这个技能什么时候可以用、怎么用脚本负责真正干活。当你在对话里提出需求时模型会判断当前需求匹配哪个 Skill 的描述然后按描述中规定的参数格式调用脚本脚本执行完把结果返回给模型模型再把最终答案组织成自然语言回复你。Skill 的目录结构大概是这样的skills/ weather/ SKILL.md script.py6.2 从零写一个天气查询 Skill我拿一个天气查询 Skill 举例这是最容易理解也最实用的入门案例。SKILL.md的内容大致是--- name: weather description: 查询指定城市的实时天气当用户询问天气时使用 input: - city: string 必填城市名称如北京 --- 使用示例 北京今天天气怎么样 - 执行 weather(city北京)script.py的逻辑就是调一个公开天气 API把结果输出到标准输出import sys import json import urllib.request city sys.argv[1] url fhttps://api.example.com/weather?city{city} with urllib.request.urlopen(url) as resp: data json.loads(resp.read()) print(f{city} 当前天气{data[weather]}温度{data[temp]}℃)写完这两个文件重启 OpenClaw让技能加载生效。然后你在对话里问一句北京天气怎么样如果配置正确助手就会去调这个脚本并给你返回结果。6.3 实战扩展写一个AI 写小说的 Skill天气查询只是热身玩 Skill 最有意思的是可以组合出复杂的创作流程。我给自己写了一个AI 写小说的 Skill专门用来生成固定风格的章节内容。这个 Skill 的核心思路是不直接把整本小说丢给模型让它自由发挥而是把它拆成设定管理和章节生成两步。在 SKILL.md 里我定义好输入参数小说名、大纲、当前章节序号、人物状态。脚本负责拼接一个完整的 prompt把上下文、风格要求、字数限制全部写清楚再调用模型 API 生成内容。代码核心逻辑大概是def generate_chapter(title, outline, chapter_no, style): prompt f 你是一位小说作者。请按照以下要求创作第 {chapter_no} 章。 小说标题{title} 大纲{outline} 写作风格{style} 要求逻辑连贯、人物性格稳定、对话自然、本章不少于 2000 字。 response call_model_api(prompt, max_tokens4000) save_to_file(f{title}_第{chapter_no}章.md, response) print(f第 {chapter_no} 章已生成)这里的关键是 max_tokens 一定要给够小说章节动辄几千字token 太短会读到一半就断掉。还可以加一个章节历史摘要把前面的剧情传给模型避免它失忆。6.4 Skill 稳定运行的几点经验写 Skill 踩过几次坑之后我总结了几条经验新手可以直接照着做第一SKILL.md 的描述一定要写得足够清晰。你可以把什么时候用参数怎么传返回什么格式都写出来模型才有把握正确调用。含糊的描述会导致模型瞎猜、乱传参。第二脚本一定要做参数校验。模型调用脚本时给的参数有时是反的比如把城市名传给了日期字段。多一层校验宁可让它返回错误信息也不要让脚本崩溃。第三每个 Skill 脚本先手动在终端跑一遍确认输入输出格式没问题再交给模型调用。要不然出了问题你根本分不清是模型的问题还是脚本的问题。7. 常见问题排查与运维心得7.1 问题速查表我把自己和身边朋友安装 OpenClaw 过程中最常遇到的几个问题整理成了表格方便你快速定位现象可能原因解决办法Control UI did not start端口被占用、Node 版本低、缓存异常换端口、升级 Node、清缓存重启unknown model: xxx默认模型 ID 和可用模型列表不一致核对服务商模型列表改正确 IDagent failed before replyAPI Key 无效、baseUrl 错误、网络不通检查 Key、确认 baseUrl 带 /v1、测试网络微信收不到消息回调地址不对、账号被风控检查回调配置、用小号测试本地模型响应极慢显存不足、模型过大、CPU 推理换更小量化模型、加显存中文乱码编码设置不对检查终端编码、环境变量加 LANGzh_CN.UTF-87.2 日常维护与数据安全OpenClaw 跑起来之后日常维护其实不多但有三件事我建议养成习惯。一是定期看日志。Docker 部署就用docker compose logs -f源码安装就去日志目录翻文件。日志里藏着很多潜在问题比如某个 API 偶尔超时、某个 Skill 调用失败早发现早处理。二是备份配置和数据。配置文件和 skill 目录是心血的结晶务必备份。会话数据库如果重要也一起备份。我的做法是把整个 openclaw 数据目录同步到私有仓库换机器时直接拉下来就能恢复。三是 API Key 安全。千万别把 Key 写死在代码里再推到公开仓库。用环境变量或者.env文件管理.gitignore里把.env排除掉。7.3 我从踩坑里总结的几点心得最后聊点实在的。第一次装 OpenClaw 的时候我在 Node 版本这里卡了一晚上装依赖反复报错后来发现是版本太旧。这个印象太深了所以现在看到安装教程第一步永远是检查环境版本。还有一件事刚装好 OpenClaw 的时候我特别贪心一上来就配了微信、飞书、Telegram 三个渠道还写了五六个 Skill结果乱成一团出了问题都不知道该查哪里。后来我重新来了一遍先本地跑通对话再接一个渠道再加一个 Skill每一步稳定了再继续。这个最小可用的思路对折腾任何开源项目都适用。如果你打算部署 OpenClaw我的建议是从一个小场景开始比如先接上 DeepSeek 的 API 跑通对话再加一个飞书机器人然后慢慢探索 Skill 的玩法。它值得你花一个周末去折腾因为一旦跑通你就拥有了一套完全属于自己、可以无限扩展的 AI 助手基础设施。