把 OpenClaw 从仓库里拉下来只是开始真正的折腾在后面的配置Git 要装吧数据库要选吧模型用云 API 还是本地 Ollama技能目录怎么放手机上还想跑一个部署端……我一圈试下来发现大多数人不是卡在“不会敲命令”而是卡在“不知道这些零件是怎么咬合在一起的”。这篇文章就把我实际跑通的配置路径拆开讲从基础环境、模型接入、技能编写到安卓 Termux、电商和 ROS2 仿真场景的扩展最后附一份排查速查表。适合刚拿到 OpenClaw 的新手也适合已经在用其他智能体框架、想快速切换过来的开发者。1. 先搞清楚 OpenClaw 是什么再动手配置1.1 它解决什么问题OpenClaw 是一个开源的个人 AI 助手项目核心不是“陪你聊天”而是让你通过聊天或者本地接口指挥它做事查日程、发提醒、查数据库、跑脚本、调接口。传统大模型只能生成文字OpenClaw 相当于给模型装了一双手通过技能模块去执行真实操作。我见过很多人一上来就照着网上的命令装依赖装完 MySQL 又装数据库结果项目根本起不来原因就是没理解它是个组件拼装型项目。OpenClaw 的运行至少需要四样东西模型、存储、消息渠道、技能。模型负责理解和决策存储负责记录消息和长期记忆消息渠道负责接收你的指令技能负责真正把指令落地。配置教程的本质就是把这四样东西分别接通再让它们互相认识。搞清楚这一点之后你就不会再问“为什么我装了个 MySQL 项目还是不动”这种问题了。MySQL 只是存储层的一个选项模型连不上、技能没配、消息渠道没监听任何一个环节断了整个项目都表现异常。所以后面的所有步骤都是围绕这条链路来做的。1.2 配置前先做一张清单我每次部署新环境都会先在纸上列一张清单把下面几个问题写清楚再动手。配置项作用常见选择运行环境提供 Node.js 执行环境Windows / Ubuntu / Termux 安卓环境代码管理拉取项目、管理技能Git模型大脑负责语义理解与工具调用云 API、本地 Ollama、任意 OpenAI 兼容接口存储保存消息、业务数据、记忆SQLite、MySQL消息渠道接收用户指令并返回结果本地 HTTP、命令行、聊天应用接口技能让模型具备执行外部操作的能力内置技能、社区技能、自写技能这张表里的每一项都不是可选项而是必选项只是不同场景的选型不同。比如你只想在电脑上自己试用SQLite 就够了你要是想把它当成一个长期跑的本地服务MySQL 会更顺畅。先列清单再动手能少走很多弯路这也是我反复强调的第一步。1.3 配置文件的整体结构OpenClaw 的配置一般会拆成几类文件而不是全部塞在一个文件里。这里给出一套最常见的目录划分方式具体文件名以你拉下来的项目 README 为准但分层逻辑基本一致openclaw-project/ ├── .env # 密钥、模型端点、环境差异配置 ├── openclaw.json # 主配置存储、渠道、技能目录 ├── persona.md # 人设与回复风格 ├── skills/ │ └── current_time/ # 技能目录 └── data/ └── openclaw.db # SQLite 数据库文件为什么拆开因为.env里放着 API Key、数据库密码这种敏感信息绝对不能提交到 Git而openclaw.json是机器配置可以随项目走persona.md是给人看、给模型看的行为描述换模型也能复用。把这三者分开你换一台机器部署时只需要拷配置和技能不用把整个环境都折腾一遍。openclaw.json最常见的骨架长这样字段名在不同版本里可能有差异但表达的意思是一致的{ model: { provider: openai-compatible, baseUrl: http://localhost:11434/v1, apiKey: ollama, model: qwen2.5:7b }, storage: { type: sqlite, path: ./data/openclaw.db }, http: { enabled: true, port: 3000 }, skillsDir: ./skills }配置基本是启动时读取的改完必须重启进程。很多人改完模型参数发现没反应往往就是没重启或者.env没被正确加载。2. 基础环境安装Git、Node.js、数据库2.1 Windows 上的完整安装流程Windows 是不少人的主力环境我先把 Windows 的配置流程完整走一遍。先后顺序建议是Git → Node.js → MySQL → SQLite因为项目拉取和运行依赖前两个存储层后面再定。Git 的安装没什么技术含量一路 Next 就行但有两个地方要注意。一是安装完必须配置用户名和邮箱否则提交技能代码时会报错二是要把 Git Bash 加入 PATH方便在终端里直接使用。配置命令很简单git config --global user.name 你的名字 git config --global user.email 你的邮箱 git config --global core.autocrlf truecore.autocrlf true是 Windows 上最容易忽略的一项它能把行尾符自动转换避免从仓库拉下来的脚本因为换行符问题在 Windows 上报错。Node.js 建议装 LTS 版本。OpenClaw 这类项目对 Node 版本有最低要求太老的版本装依赖时会看到一堆 engine 相关的警告。装完之后打开终端验证node -v npm -v如果出现版本号这一步就算过了。MySQL 8 的 zip 方式配置我用过很多次。从 MySQL 官网下载mysql-8.x-winx64.zip解压到一个不含空格的路径比如C:\mysql-8.x-winx64。然后在这个目录下手动建一个my.ini[mysqld] basedirC:/mysql-8.x-winx64 datadirC:/mysql-8.x-winx64/data port3306 character-set-serverutf8mb4用管理员身份打开 PowerShell进入解压目录的bin文件夹执行初始化命令.\mysqld --initialize-insecure这个命令会生成一个无密码的 root 账号并创建data目录。接着注册 Windows 服务.\mysqld --install OpenClawMySQL net start OpenClawMySQL服务启动后登录数据库.\mysql -u root然后给 root 设置密码创建项目库ALTER USER rootlocalhost IDENTIFIED BY 你的密码; CREATE DATABASE openclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;utf8mb4一定要选否则后续存储中文内容会出现乱码。这一步是很多中文用户踩坑的重灾区默认的 latin1 字符集存不了中文。2.2 Ubuntu 24.04 LTS 上的环境配置如果用的是 Linux 服务器Ubuntu 24.04 LTS 是我的首选。安装命令比 Windows 简单很多sudo apt update sudo apt install -y git nodejs npm mysql-server sqlite3装完之后检查版本node -v git --version mysql --versionUbuntu 下 MySQL 的 root 账号默认使用 auth_socket 认证直接sudo mysql就能登录但 OpenClaw 用普通密码连接时会失败。建议创建一个专用账号而不是去折腾 rootsudo mysql进入 MySQL 后执行CREATE USER openclawlocalhost IDENTIFIED BY 你的密码; CREATE DATABASE openclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL PRIVILEGES ON openclaw.* TO openclawlocalhost; FLUSH PRIVILEGES;这样 OpenClaw 用openclaw账号连openclaw库权限边界清楚不会动不动拿 root 去跑应用。2.3 SQLite 还是 MySQL我的选择逻辑很多人会在 SQLite 和 MySQL 之间纠结。我的建议很简单单机自用无脑选 SQLite准备长期跑服务、多端访问再上 MySQL。SQLite 的配置成本几乎为零数据就是一个文件备份直接复制文件即可。OpenClaw 在本地开发阶段用 SQLite 最舒服项目出问题删掉数据库文件就能重置。但它不适合并发写多的场景如果多个渠道同时写入数据库文件会被锁住。MySQL 适合作为独立服务运行能扛住更多连接也方便你在服务器上部署后从别处访问。代价是你得多管一个服务多处理一套权限和认证问题。MySQL 8 默认的caching_sha2_password认证插件和部分老版本驱动不兼容如果连接时报认证错误可以在 MySQL 里单独改一下ALTER USER openclawlocalhost IDENTIFIED WITH mysql_native_password BY 你的密码;SQLite 没有这种烦恼Windows 和 Linux 下基本开箱即用。如果你只是想在电脑上体验 OpenClaw别为了“正式”去装 MySQL那是给自己找麻烦。2.4 Git 初始化与项目拉取环境装完后把项目拉下来。我建议优先用 SSH 方式而不是 HTTPS避免每次操作都输密码。生成密钥ssh-keygen -t ed25519 -C 你的邮箱然后查看公钥并添加到代码托管平台cat ~/.ssh/id_ed25519.pub添加完公钥后从项目主页复制 SSH 格式的仓库地址执行git clone 你的OpenClaw仓库地址 cd 项目目录 npm install这一步如果报权限错误多半是 SSH key 没配好如果报依赖错误先看 Node 版本。npm install完成后项目的基础运行环境就绪下面开始接模型。3. 模型接入云 API 与本地 Ollama 全覆盖3.1 先回答那个高频问题搜索里经常看到有人问“OpenClaw 只能用接入 API 的方式使用算力吗”这是个误解。OpenClaw 在模型层是模型无关的凡是提供 OpenAI 兼容接口的模型都能接入。所谓算力可以来自云端厂商也可以来自你自己的电脑或服务器。云 API 的优点是模型大、聪明缺点是每次调用都要走网络、按量付费。本地 Ollama 的优点是数据不出门、不花钱、断网也能用缺点是受机器性能限制只能跑参数较小的模型。OpenClaw 本身不绑定算力来源你在配置里填不同的baseUrl它就会去不同的地方找模型。这个设计很实用开发阶段用本地模型上线后切云端大模型只改配置不改代码。3.2 Ollama 部署与配置步骤Ollama 是目前最简单易用的本地模型运行工具支持 Windows、macOS、Linux。安装完成后终端里执行ollama pull qwen2.5:7b国内中文场景我优先选 Qwen 系列中文理解和生成质量在线。拉取完成后验证ollama list看到模型列表就说明本地服务已经起来了。默认情况下 Ollama 会监听http://localhost:11434而且提供了 OpenAI 兼容接口路径是/v1。这就是 OpenClaw 能直接接入的原因。在 OpenClaw 的.env里这样写OPENCLAW_MODEL_BASE_URLhttp://localhost:11434/v1 OPENCLAW_MODEL_API_KEYollama OPENCLAW_MODEL_NAMEqwen2.5:7b很多本地接口不校验 Key随便填一个占位符就行。配置好后可以用 curl 快速验证curl http://localhost:11434/v1/models能返回 JSON 模型列表说明链路通。这时启动 OpenClaw发一条消息测试它应该就能通过本地模型回复了。如果 OpenClaw 跑在另一台机器上要把上面的localhost改成 Ollama 所在机器的局域网 IP并且 Ollama 需要监听外部地址OLLAMA_HOST0.0.0.0 ollama serve不加这一步跨设备访问会被拒绝。我自己测试时踩过一次坑OpenClaw 始终连不上查半天才发现 Ollama 只监听了127.0.0.1。3.3 “中文版”不是安装包是配置搜索“OpenClaw 中文版”的人很多实际上 OpenClaw 并没有一个独立的中文安装包它是一个配置化项目“中文版”是在配置层面实现的。要做三件事选择中文友好的模型、用中文写 persona、把模型参数里的语言偏好调成中文。最影响体验的是模型选型。用本地推理就选 Qwen、GLM 系列云端服务可以用支持中文更好的大模型。模型选好后写persona.md你是一个名叫小爪的个人 AI 助手。 默认使用简体中文回复。 回答要简洁、直接不要重复用户的话。 如果用户没有指定格式优先给出可执行的操作步骤。这段内容不要写得像功能说明书要写得像对一个人的行为要求。模型会把它当成系统提示词来遵循。你会发现同样的模型写清楚人设后回复质量提升非常明显。很多人说“中文版不好用”其实是人设文件写得太笼统模型不知道该怎么表现。3.4 密钥与安全模型接入涉及 API Key安全习惯要从第一天就养成。Key 只放.env不要写进openclaw.json更不要提交到 Git。.gitignore里必须加上.env还要尽量给云端 API 设置调用额度上限防止 Key 泄露后被刷爆。本地 Ollama 虽然没有 Key 概念但如果开放了局域网访问最好限制在可信内网别直接暴露到公网。这些都是配置之外最容易忽略的事但恰恰是最重要的。4. 技能Skill配置实战4.1 技能的设计逻辑OpenClaw 的能力上限很大程度取决于技能怎么配。技能的本质是给模型提供一份“工具使用说明书”和一个可执行脚本。模型本身不会直接执行代码它看到用户消息后根据技能的描述判断该调用哪个工具然后运行对应的脚本再把脚本输出拿回来加工成回复。打个比方模型是大脑技能是手。大脑不能直接拿杯子但大脑知道“伸手”这个动作可以拿杯子于是它指挥手去执行。OpenClaw 里SKILL.md就是大脑看到的动作描述脚本就是手。这个设计也解释了为什么技能的描述必须写清楚否则大脑不知道什么时候该伸手。4.2 写一个最小可用技能我建议新手第一个技能不要搞复杂就写一个查询当前时间的技能跑通完整链路。在skills目录下建一个子目录skills/ current_time/ SKILL.md script.jsSKILL.md内容如下--- name: current_time description: 查询当前日期和时间。当用户问“现在几点”“今天几号”“现在时间”时使用。 command: node script.js ---script.js只需要一行console.log(new Date().toString());然后在openclaw.json里确认skillsDir指向./skills重启 OpenClaw。之后用户说“现在几点”模型会看到current_time的描述调用脚本把时间输出返回给用户。整个流程走通后你就理解了 OpenClaw 的核心机制模型的判断 技能的执行。写技能时有几个细节要注意。一是description要写清楚触发场景太模糊的技能模型不会调用二是脚本一定要处理异常不然模型拿到错误信息也不知道怎么办三是脚本输出要简洁最好只输出结果别把一堆日志也丢给模型那会干扰回复生成。4.3 社区技能的使用原则社区里能搜到很多现成的技能用起来方便但风险也在。我的原则是不直接运行没看过的技能。拿到一个技能包先打开SKILL.md看它声明了什么操作再看脚本依赖了哪些第三方库最后看有没有网络外发、文件删除这类危险动作。技能一旦挂载模型就可能在特定条件下调用它等于给外部脚本开了一个执行口子。有一次我下载了一个“天气查询”技能结果脚本里还藏了一段上传用户目录文件的代码。从那以后我对社区技能一律先审查再挂载。这个习惯在配置 OpenClaw 时非常重要因为它不是纯聊天应用它真的会执行命令。5. 进阶场景安卓 Termux、电商、ROS25.1 Termux 安卓部署把 OpenClaw 跑在安卓手机上等于随身带了一个离线助手。搜索里提到的“Termux 安装 OpenClaw 手机版”逻辑上不是安装 APK而是在安卓环境里搭一个完整的 Node.js 运行环境。Termux 不要从应用商店下载版本太旧建议通过 F-Droid 获取。安装后先换源更新软件包pkg update pkg upgrade然后安装依赖pkg install nodejs-lts git sqlite openssh安装完 SSH 后可以用电脑远程连接手机终端操作体验会好很多。接下来克隆项目、安装依赖git clone 你的OpenClaw仓库地址 cd 项目目录 npm install配置方面存储层直接用 SQLite省内存模型可以指向局域网内电脑上的 Ollama也可以直接在手机上跑小模型但手机会发热明显实际用下来不如远程调用顺畅。启动命令和电脑上一样根据项目 README 使用npm start或入口文件。一个必须处理的问题是安卓后台杀进程锁屏后 Termux 进程容易被回收。执行termux-wake-lock可以暂时阻止系统休眠这是 Termux 部署必须记住的一条命令否则第二天醒来会发现助手已经断了。5.2 电商客服与订单场景怎么配OpenClaw 在电商场景里完全可以当做一个“业务查询助手”。很多后台系统的订单、库存数据都在数据库里OpenClaw 要做的不是直接暴露数据库而是通过技能封装查询逻辑。我设计电商场景时最喜欢用的模式是数据库只存数据技能提供查询入口模型负责理解用户问法。比如你先建一张商品表CREATE TABLE products ( id INT PRIMARY KEY, name VARCHAR(200), price DECIMAL(10,2), stock INT );然后写一个query_product技能接收keyword参数在脚本里执行 SQL 查询只返回结果 JSON。模型收到用户消息“帮我查一下保温杯的价格”它看到技能描述提取关键词“保温杯”调用脚本最终返回价格信息。这种设计的一个核心原则是把数据库读写操作控制在技能脚本里不要让模型生成 SQL。模型生成的 SQL 可能不准确也可能带了破坏性语句。电商场景更要谨慎查询订单、改库存、发通知这些操作要分成只读技能和写入技能写入类技能必须增加确认环节。比如用户说“把订单 123 的快递单号发给客户”这个操作应该先展示拟发送内容确认后再执行不能直接让模型一把梭。5.3 机器人仿真OpenClaw ROS2 Humble Gazebo搜索里有“rosclaw openclaw ros2 humble gazebo”这明显是把 OpenClaw 当成机器人仿真环境的“大脑”来用。ROS2 是机器人领域的标准中间件Gazebo 是常见仿真环境OpenClaw 在里面的角色是自然语言控制入口。先说版本组合。ROS2 Humble 官方主要支持 Ubuntu 22.04如果你用的是 Ubuntu 24.04 LTS我建议直接上 ROS2 Jazzy配置思路完全一样。在 Ubuntu 22.04 上按官方文档装完 Humble 和 Gazebo 后每次使用终端要加载环境source /opt/ros/humble/setup.bash这个 source 动作很关键ROS2 命令依赖环境变量直接在 OpenClaw 的技能脚本里要用bash -c包一层例如写一个机器人控制技能--- name: robot_cmd description: 向 ROS2 仿真环境发布控制指令。当用户需要移动机器人或设置线速度、角速度时使用。 command: bash -c source /opt/ros/humble/setup.bash ros2 topic pub /cmd_vel geometry_msgs/msg/Twist \{linear: {x: 0.1}, angular: {z: 0.0}}\ --once ---这个技能的效果是你在 OpenClaw 里说“让机器人前进”模型识别意图后调用技能向 Gazebo 里的仿真机器人发布速度消息。先把环境 source 进去再执行ros2 topic pub这样脚本能正常运行。实际调试中要注意ROS2 的 topic 消息格式要求严格括号和引号容易出错。建议先手动在终端跑一遍命令确认机器人动了再挂到技能脚本里。安全第一在仿真环境里可以随便试真机环境一定要加急停逻辑。5.4 和其他常见开发工具链共存热搜词里还有一些开发工具配置比如 XAMPP、Tomcat、若依、Zotero。这些工具和 OpenClaw 不是替代关系更多是共存。核心撞车点只有两个端口和数据库。XAMPP 自带 MySQL 和 Apache如果已启动默认占 3306 和 80/443 端口。OpenClaw 要用同一个 MySQL要么复用 XAMPP 的 MySQL要么把其中一个改端口。Tomcat 默认 8080若依这类 Java 后台也会用到 MySQL 和 Redis只要端口不冲突完全可以在同一台机器上并存。Zotero 是文献管理工具它能作为 OpenClaw 的知识来源。思路是把 Zotero 数据库当成只读数据源写一个技能定期导出条目或者直接在技能脚本里查询 Zotero 的 SQLite 数据库文件。这样你可以在 OpenClaw 里问“我上个月存的文献有哪些”它会从 Zotero 的数据里找到答案。这个玩法不是必须的但可以体现 OpenClaw 的扩展方式只要数据能被读取就能被模型使用。6. 常见问题与排查速查6.1 问题速查表配置过程中会遇到很多重复问题我整理了一张速查表照着查效率最高。症状可能原因排查方法启动报错提示找不到模块Node 版本太低或依赖没装全node -v检查版本删除node_modules后重装模型一直不回复baseUrl不通或模型名错误用 curl 直接请求模型接口验证Ollama 跨设备连不上服务只监听了本机地址用OLLAMA_HOST0.0.0.0启动连接 MySQL 报认证错误认证插件不兼容改用mysql_native_password认证中文回复夹杂英文模型选型或人设问题换成中文友好模型重写persona.md技能始终不触发description写得太模糊重写技能的触发场景描述手机锁屏后进程断掉系统回收了后台进程在 Termux 里执行termux-wake-lock改完配置没生效没有重启进程重启 OpenClaw配置是启动时加载的端口被占用其他服务占用了 3000/3306/8080查看占用进程修改端口配置这张表基本覆盖了我在 Windows、Ubuntu、Termux 三端部署时遇到的高频问题。每一条背后都对应一次真实排查经历照着做比从头看日志要快得多。6.2 我踩过的几个坑第一个坑是 Windows 下 MySQL 初始化失败。问题出在my.ini里的路径用反斜杠写成了C:\mysql...MySQL 解析时容易出问题。改成正斜杠C:/mysql...后一次通过。所以写配置文件时路径分隔符要统一别混用。第二个坑是让模型直接查数据库。早期图省事给模型开放了 SQL 权限结果用户问订单时模型生成了错误 SQL把整张表扫了一遍。后来我改成所有查询都走技能脚本把 SQL 写死在脚本里只让模型传参数。数据访问更安全响应也更可预测。第三个坑是 Ollama 模型文件过大导致手机不堪重负。在安卓 Termux 上跑 7B 模型虽然能跑但同时跑 OpenClaw 和模型推理手机会非常烫。后来我把手机端模型层去掉让手机只作为前端模型统一走局域网里电脑上的 Ollama。这样分工才合理不能什么都往手机上塞。第四个坑是.env被提交到 Git。有一次做示例项目没注意.gitignore漏了.env结果密钥全被推到仓库里只能紧急撤下并且把 Key 全部重置。从那以后我所有项目的第一件事就是先写好.gitignore把.env、node_modules、data目录全部排除掉。这个习惯从来没有让我后悔过。最后再分享一个小习惯把openclaw.json、persona.md和整个skills目录纳入 Git但.env永远不进仓库。我本地、服务器、手机三份环境共用一套代码差异只靠.env切换。以后想换模型只需要改一行ENV变量不用动任何逻辑。这样管理配置类项目长期用下来是最省心的。