景擴(kuò)展：模型、技能與部署全攻略)
把 OpenClaw 從倉(cāng)庫(kù)里拉下來(lái)只是開(kāi)始真正的折騰在后面的配置Git 要裝吧數(shù)據(jù)庫(kù)要選吧模型用云 API 還是本地 Ollama技能目錄怎么放手機(jī)上還想跑一個(gè)部署端……我一圈試下來(lái)發(fā)現(xiàn)大多數(shù)人不是卡在“不會(huì)敲命令”而是卡在“不知道這些零件是怎么咬合在一起的”。這篇文章就把我實(shí)際跑通的配置路徑拆開(kāi)講從基礎(chǔ)環(huán)境、模型接入、技能編寫到安卓 Termux、電商和 ROS2 仿真場(chǎng)景的擴(kuò)展最后附一份排查速查表。適合剛拿到 OpenClaw 的新手也適合已經(jīng)在用其他智能體框架、想快速切換過(guò)來(lái)的開(kāi)發(fā)者。1. 先搞清楚 OpenClaw 是什么再動(dòng)手配置1.1 它解決什么問(wèn)題OpenClaw 是一個(gè)開(kāi)源的個(gè)人 AI 助手項(xiàng)目核心不是“陪你聊天”而是讓你通過(guò)聊天或者本地接口指揮它做事查日程、發(fā)提醒、查數(shù)據(jù)庫(kù)、跑腳本、調(diào)接口。傳統(tǒng)大模型只能生成文字OpenClaw 相當(dāng)于給模型裝了一雙手通過(guò)技能模塊去執(zhí)行真實(shí)操作。我見(jiàn)過(guò)很多人一上來(lái)就照著網(wǎng)上的命令裝依賴裝完 MySQL 又裝數(shù)據(jù)庫(kù)結(jié)果項(xiàng)目根本起不來(lái)原因就是沒(méi)理解它是個(gè)組件拼裝型項(xiàng)目。OpenClaw 的運(yùn)行至少需要四樣?xùn)|西模型、存儲(chǔ)、消息渠道、技能。模型負(fù)責(zé)理解和決策存儲(chǔ)負(fù)責(zé)記錄消息和長(zhǎng)期記憶消息渠道負(fù)責(zé)接收你的指令技能負(fù)責(zé)真正把指令落地。配置教程的本質(zhì)就是把這四樣?xùn)|西分別接通再讓它們互相認(rèn)識(shí)。搞清楚這一點(diǎn)之后你就不會(huì)再問(wèn)“為什么我裝了個(gè) MySQL 項(xiàng)目還是不動(dòng)”這種問(wèn)題了。MySQL 只是存儲(chǔ)層的一個(gè)選項(xiàng)模型連不上、技能沒(méi)配、消息渠道沒(méi)監(jiān)聽(tīng)任何一個(gè)環(huán)節(jié)斷了整個(gè)項(xiàng)目都表現(xiàn)異常。所以后面的所有步驟都是圍繞這條鏈路來(lái)做的。1.2 配置前先做一張清單我每次部署新環(huán)境都會(huì)先在紙上列一張清單把下面幾個(gè)問(wèn)題寫清楚再動(dòng)手。配置項(xiàng)作用常見(jiàn)選擇運(yùn)行環(huán)境提供 Node.js 執(zhí)行環(huán)境Windows / Ubuntu / Termux 安卓環(huán)境代碼管理拉取項(xiàng)目、管理技能Git模型大腦負(fù)責(zé)語(yǔ)義理解與工具調(diào)用云 API、本地 Ollama、任意 OpenAI 兼容接口存儲(chǔ)保存消息、業(yè)務(wù)數(shù)據(jù)、記憶SQLite、MySQL消息渠道接收用戶指令并返回結(jié)果本地 HTTP、命令行、聊天應(yīng)用接口技能讓模型具備執(zhí)行外部操作的能力內(nèi)置技能、社區(qū)技能、自寫技能這張表里的每一項(xiàng)都不是可選項(xiàng)而是必選項(xiàng)只是不同場(chǎng)景的選型不同。比如你只想在電腦上自己試用SQLite 就夠了你要是想把它當(dāng)成一個(gè)長(zhǎng)期跑的本地服務(wù)MySQL 會(huì)更順暢。先列清單再動(dòng)手能少走很多彎路這也是我反復(fù)強(qiáng)調(diào)的第一步。1.3 配置文件的整體結(jié)構(gòu)OpenClaw 的配置一般會(huì)拆成幾類文件而不是全部塞在一個(gè)文件里。這里給出一套最常見(jiàn)的目錄劃分方式具體文件名以你拉下來(lái)的項(xiàng)目 README 為準(zhǔn)但分層邏輯基本一致openclaw-project/ ├── .env # 密鑰、模型端點(diǎn)、環(huán)境差異配置 ├── openclaw.json # 主配置存儲(chǔ)、渠道、技能目錄 ├── persona.md # 人設(shè)與回復(fù)風(fēng)格 ├── skills/ │ └── current_time/ # 技能目錄 └── data/ └── openclaw.db # SQLite 數(shù)據(jù)庫(kù)文件為什么拆開(kāi)因?yàn)?env里放著 API Key、數(shù)據(jù)庫(kù)密碼這種敏感信息絕對(duì)不能提交到 Git而openclaw.json是機(jī)器配置可以隨項(xiàng)目走persona.md是給人看、給模型看的行為描述換模型也能復(fù)用。把這三者分開(kāi)你換一臺(tái)機(jī)器部署時(shí)只需要拷配置和技能不用把整個(gè)環(huán)境都折騰一遍。openclaw.json最常見(jiàn)的骨架長(zhǎng)這樣字段名在不同版本里可能有差異但表達(dá)的意思是一致的{ 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 }配置基本是啟動(dòng)時(shí)讀取的改完必須重啟進(jìn)程。很多人改完模型參數(shù)發(fā)現(xiàn)沒(méi)反應(yīng)往往就是沒(méi)重啟或者.env沒(méi)被正確加載。2. 基礎(chǔ)環(huán)境安裝Git、Node.js、數(shù)據(jù)庫(kù)2.1 Windows 上的完整安裝流程Windows 是不少人的主力環(huán)境我先把 Windows 的配置流程完整走一遍。先后順序建議是Git → Node.js → MySQL → SQLite因?yàn)轫?xiàng)目拉取和運(yùn)行依賴前兩個(gè)存儲(chǔ)層后面再定。Git 的安裝沒(méi)什么技術(shù)含量一路 Next 就行但有兩個(gè)地方要注意。一是安裝完必須配置用戶名和郵箱否則提交技能代碼時(shí)會(huì)報(bào)錯(cuò)二是要把 Git Bash 加入 PATH方便在終端里直接使用。配置命令很簡(jiǎn)單git config --global user.name 你的名字 git config --global user.email 你的郵箱 git config --global core.autocrlf truecore.autocrlf true是 Windows 上最容易忽略的一項(xiàng)它能把行尾符自動(dòng)轉(zhuǎn)換避免從倉(cāng)庫(kù)拉下來(lái)的腳本因?yàn)閾Q行符問(wèn)題在 Windows 上報(bào)錯(cuò)。Node.js 建議裝 LTS 版本。OpenClaw 這類項(xiàng)目對(duì) Node 版本有最低要求太老的版本裝依賴時(shí)會(huì)看到一堆 engine 相關(guān)的警告。裝完之后打開(kāi)終端驗(yàn)證node -v npm -v如果出現(xiàn)版本號(hào)這一步就算過(guò)了。MySQL 8 的 zip 方式配置我用過(guò)很多次。從 MySQL 官網(wǎng)下載mysql-8.x-winx64.zip解壓到一個(gè)不含空格的路徑比如C:\mysql-8.x-winx64。然后在這個(gè)目錄下手動(dòng)建一個(gè)my.ini[mysqld] basedirC:/mysql-8.x-winx64 datadirC:/mysql-8.x-winx64/data port3306 character-set-serverutf8mb4用管理員身份打開(kāi) PowerShell進(jìn)入解壓目錄的bin文件夾執(zhí)行初始化命令.\mysqld --initialize-insecure這個(gè)命令會(huì)生成一個(gè)無(wú)密碼的 root 賬號(hào)并創(chuàng)建data目錄。接著注冊(cè) Windows 服務(wù).\mysqld --install OpenClawMySQL net start OpenClawMySQL服務(wù)啟動(dòng)后登錄數(shù)據(jù)庫(kù).\mysql -u root然后給 root 設(shè)置密碼創(chuàng)建項(xiàng)目庫(kù)ALTER USER rootlocalhost IDENTIFIED BY 你的密碼; CREATE DATABASE openclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;utf8mb4一定要選否則后續(xù)存儲(chǔ)中文內(nèi)容會(huì)出現(xiàn)亂碼。這一步是很多中文用戶踩坑的重災(zāi)區(qū)默認(rèn)的 latin1 字符集存不了中文。2.2 Ubuntu 24.04 LTS 上的環(huán)境配置如果用的是 Linux 服務(wù)器Ubuntu 24.04 LTS 是我的首選。安裝命令比 Windows 簡(jiǎn)單很多sudo apt update sudo apt install -y git nodejs npm mysql-server sqlite3裝完之后檢查版本node -v git --version mysql --versionUbuntu 下 MySQL 的 root 賬號(hào)默認(rèn)使用 auth_socket 認(rèn)證直接sudo mysql就能登錄但 OpenClaw 用普通密碼連接時(shí)會(huì)失敗。建議創(chuàng)建一個(gè)專用賬號(hào)而不是去折騰 rootsudo mysql進(jìn)入 MySQL 后執(zhí)行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賬號(hào)連openclaw庫(kù)權(quán)限邊界清楚不會(huì)動(dòng)不動(dòng)拿 root 去跑應(yīng)用。2.3 SQLite 還是 MySQL我的選擇邏輯很多人會(huì)在 SQLite 和 MySQL 之間糾結(jié)。我的建議很簡(jiǎn)單單機(jī)自用無(wú)腦選 SQLite準(zhǔn)備長(zhǎng)期跑服務(wù)、多端訪問(wèn)再上 MySQL。SQLite 的配置成本幾乎為零數(shù)據(jù)就是一個(gè)文件備份直接復(fù)制文件即可。OpenClaw 在本地開(kāi)發(fā)階段用 SQLite 最舒服項(xiàng)目出問(wèn)題刪掉數(shù)據(jù)庫(kù)文件就能重置。但它不適合并發(fā)寫多的場(chǎng)景如果多個(gè)渠道同時(shí)寫入數(shù)據(jù)庫(kù)文件會(huì)被鎖住。MySQL 適合作為獨(dú)立服務(wù)運(yùn)行能扛住更多連接也方便你在服務(wù)器上部署后從別處訪問(wèn)。代價(jià)是你得多管一個(gè)服務(wù)多處理一套權(quán)限和認(rèn)證問(wèn)題。MySQL 8 默認(rèn)的caching_sha2_password認(rèn)證插件和部分老版本驅(qū)動(dòng)不兼容如果連接時(shí)報(bào)認(rèn)證錯(cuò)誤可以在 MySQL 里單獨(dú)改一下ALTER USER openclawlocalhost IDENTIFIED WITH mysql_native_password BY 你的密碼;SQLite 沒(méi)有這種煩惱Windows 和 Linux 下基本開(kāi)箱即用。如果你只是想在電腦上體驗(yàn) OpenClaw別為了“正式”去裝 MySQL那是給自己找麻煩。2.4 Git 初始化與項(xiàng)目拉取環(huán)境裝完后把項(xiàng)目拉下來(lái)。我建議優(yōu)先用 SSH 方式而不是 HTTPS避免每次操作都輸密碼。生成密鑰ssh-keygen -t ed25519 -C 你的郵箱然后查看公鑰并添加到代碼托管平臺(tái)cat ~/.ssh/id_ed25519.pub添加完公鑰后從項(xiàng)目主頁(yè)復(fù)制 SSH 格式的倉(cāng)庫(kù)地址執(zhí)行g(shù)it clone 你的OpenClaw倉(cāng)庫(kù)地址 cd 項(xiàng)目目錄 npm install這一步如果報(bào)權(quán)限錯(cuò)誤多半是 SSH key 沒(méi)配好如果報(bào)依賴錯(cuò)誤先看 Node 版本。npm install完成后項(xiàng)目的基礎(chǔ)運(yùn)行環(huán)境就緒下面開(kāi)始接模型。3. 模型接入云 API 與本地 Ollama 全覆蓋3.1 先回答那個(gè)高頻問(wèn)題搜索里經(jīng)?？吹接腥藛?wèn)“OpenClaw 只能用接入 API 的方式使用算力嗎”這是個(gè)誤解。OpenClaw 在模型層是模型無(wú)關(guān)的凡是提供 OpenAI 兼容接口的模型都能接入。所謂算力可以來(lái)自云端廠商也可以來(lái)自你自己的電腦或服務(wù)器。云 API 的優(yōu)點(diǎn)是模型大、聰明缺點(diǎn)是每次調(diào)用都要走網(wǎng)絡(luò)、按量付費(fèi)。本地 Ollama 的優(yōu)點(diǎn)是數(shù)據(jù)不出門、不花錢、斷網(wǎng)也能用缺點(diǎn)是受機(jī)器性能限制只能跑參數(shù)較小的模型。OpenClaw 本身不綁定算力來(lái)源你在配置里填不同的baseUrl它就會(huì)去不同的地方找模型。這個(gè)設(shè)計(jì)很實(shí)用開(kāi)發(fā)階段用本地模型上線后切云端大模型只改配置不改代碼。3.2 Ollama 部署與配置步驟Ollama 是目前最簡(jiǎn)單易用的本地模型運(yùn)行工具支持 Windows、macOS、Linux。安裝完成后終端里執(zhí)行ollama pull qwen2.5:7b國(guó)內(nèi)中文場(chǎng)景我優(yōu)先選 Qwen 系列中文理解和生成質(zhì)量在線。拉取完成后驗(yàn)證ollama list看到模型列表就說(shuō)明本地服務(wù)已經(jīng)起來(lái)了。默認(rèn)情況下 Ollama 會(huì)監(jiān)聽(tīng)http://localhost:11434而且提供了 OpenAI 兼容接口路徑是/v1。這就是 OpenClaw 能直接接入的原因。在 OpenClaw 的.env里這樣寫OPENCLAW_MODEL_BASE_URLhttp://localhost:11434/v1 OPENCLAW_MODEL_API_KEYollama OPENCLAW_MODEL_NAMEqwen2.5:7b很多本地接口不校驗(yàn) Key隨便填一個(gè)占位符就行。配置好后可以用 curl 快速驗(yàn)證curl http://localhost:11434/v1/models能返回 JSON 模型列表說(shuō)明鏈路通。這時(shí)啟動(dòng) OpenClaw發(fā)一條消息測(cè)試它應(yīng)該就能通過(guò)本地模型回復(fù)了。如果 OpenClaw 跑在另一臺(tái)機(jī)器上要把上面的localhost改成 Ollama 所在機(jī)器的局域網(wǎng) IP并且 Ollama 需要監(jiān)聽(tīng)外部地址OLLAMA_HOST0.0.0.0 ollama serve不加這一步跨設(shè)備訪問(wèn)會(huì)被拒絕。我自己測(cè)試時(shí)踩過(guò)一次坑OpenClaw 始終連不上查半天才發(fā)現(xiàn) Ollama 只監(jiān)聽(tīng)了127.0.0.1。3.3 “中文版”不是安裝包是配置搜索“OpenClaw 中文版”的人很多實(shí)際上 OpenClaw 并沒(méi)有一個(gè)獨(dú)立的中文安裝包它是一個(gè)配置化項(xiàng)目“中文版”是在配置層面實(shí)現(xiàn)的。要做三件事選擇中文友好的模型、用中文寫 persona、把模型參數(shù)里的語(yǔ)言偏好調(diào)成中文。最影響體驗(yàn)的是模型選型。用本地推理就選 Qwen、GLM 系列云端服務(wù)可以用支持中文更好的大模型。模型選好后寫persona.md你是一個(gè)名叫小爪的個(gè)人 AI 助手。 默認(rèn)使用簡(jiǎn)體中文回復(fù)。 回答要簡(jiǎn)潔、直接不要重復(fù)用戶的話。 如果用戶沒(méi)有指定格式優(yōu)先給出可執(zhí)行的操作步驟。這段內(nèi)容不要寫得像功能說(shuō)明書(shū)要寫得像對(duì)一個(gè)人的行為要求。模型會(huì)把它當(dāng)成系統(tǒng)提示詞來(lái)遵循。你會(huì)發(fā)現(xiàn)同樣的模型寫清楚人設(shè)后回復(fù)質(zhì)量提升非常明顯。很多人說(shuō)“中文版不好用”其實(shí)是人設(shè)文件寫得太籠統(tǒng)模型不知道該怎么表現(xiàn)。3.4 密鑰與安全模型接入涉及 API Key安全習(xí)慣要從第一天就養(yǎng)成。Key 只放.env不要寫進(jìn)openclaw.json更不要提交到 Git。.gitignore里必須加上.env還要盡量給云端 API 設(shè)置調(diào)用額度上限防止 Key 泄露后被刷爆。本地 Ollama 雖然沒(méi)有 Key 概念但如果開(kāi)放了局域網(wǎng)訪問(wèn)最好限制在可信內(nèi)網(wǎng)別直接暴露到公網(wǎng)。這些都是配置之外最容易忽略的事但恰恰是最重要的。4. 技能Skill配置實(shí)戰(zhàn)4.1 技能的設(shè)計(jì)邏輯OpenClaw 的能力上限很大程度取決于技能怎么配。技能的本質(zhì)是給模型提供一份“工具使用說(shuō)明書(shū)”和一個(gè)可執(zhí)行腳本。模型本身不會(huì)直接執(zhí)行代碼它看到用戶消息后根據(jù)技能的描述判斷該調(diào)用哪個(gè)工具然后運(yùn)行對(duì)應(yīng)的腳本再把腳本輸出拿回來(lái)加工成回復(fù)。打個(gè)比方模型是大腦技能是手。大腦不能直接拿杯子但大腦知道“伸手”這個(gè)動(dòng)作可以拿杯子于是它指揮手去執(zhí)行。OpenClaw 里SKILL.md就是大腦看到的動(dòng)作描述腳本就是手。這個(gè)設(shè)計(jì)也解釋了為什么技能的描述必須寫清楚否則大腦不知道什么時(shí)候該伸手。4.2 寫一個(gè)最小可用技能我建議新手第一個(gè)技能不要搞復(fù)雜就寫一個(gè)查詢當(dāng)前時(shí)間的技能跑通完整鏈路。在skills目錄下建一個(gè)子目錄skills/ current_time/ SKILL.md script.jsSKILL.md內(nèi)容如下--- name: current_time description: 查詢當(dāng)前日期和時(shí)間。當(dāng)用戶問(wèn)“現(xiàn)在幾點(diǎn)”“今天幾號(hào)”“現(xiàn)在時(shí)間”時(shí)使用。 command: node script.js ---script.js只需要一行console.log(new Date().toString());然后在openclaw.json里確認(rèn)skillsDir指向./skills重啟 OpenClaw。之后用戶說(shuō)“現(xiàn)在幾點(diǎn)”模型會(huì)看到current_time的描述調(diào)用腳本把時(shí)間輸出返回給用戶。整個(gè)流程走通后你就理解了 OpenClaw 的核心機(jī)制模型的判斷 技能的執(zhí)行。寫技能時(shí)有幾個(gè)細(xì)節(jié)要注意。一是description要寫清楚觸發(fā)場(chǎng)景太模糊的技能模型不會(huì)調(diào)用二是腳本一定要處理異常不然模型拿到錯(cuò)誤信息也不知道怎么辦三是腳本輸出要簡(jiǎn)潔最好只輸出結(jié)果別把一堆日志也丟給模型那會(huì)干擾回復(fù)生成。4.3 社區(qū)技能的使用原則社區(qū)里能搜到很多現(xiàn)成的技能用起來(lái)方便但風(fēng)險(xiǎn)也在。我的原則是不直接運(yùn)行沒(méi)看過(guò)的技能。拿到一個(gè)技能包先打開(kāi)SKILL.md看它聲明了什么操作再看腳本依賴了哪些第三方庫(kù)最后看有沒(méi)有網(wǎng)絡(luò)外發(fā)、文件刪除這類危險(xiǎn)動(dòng)作。技能一旦掛載模型就可能在特定條件下調(diào)用它等于給外部腳本開(kāi)了一個(gè)執(zhí)行口子。有一次我下載了一個(gè)“天氣查詢”技能結(jié)果腳本里還藏了一段上傳用戶目錄文件的代碼。從那以后我對(duì)社區(qū)技能一律先審查再掛載。這個(gè)習(xí)慣在配置 OpenClaw 時(shí)非常重要因?yàn)樗皇羌兞奶鞈?yīng)用它真的會(huì)執(zhí)行命令。5. 進(jìn)階場(chǎng)景安卓 Termux、電商、ROS25.1 Termux 安卓部署把 OpenClaw 跑在安卓手機(jī)上等于隨身帶了一個(gè)離線助手。搜索里提到的“Termux 安裝 OpenClaw 手機(jī)版”邏輯上不是安裝 APK而是在安卓環(huán)境里搭一個(gè)完整的 Node.js 運(yùn)行環(huán)境。Termux 不要從應(yīng)用商店下載版本太舊建議通過(guò) F-Droid 獲取。安裝后先換源更新軟件包pkg update pkg upgrade然后安裝依賴pkg install nodejs-lts git sqlite openssh安裝完 SSH 后可以用電腦遠(yuǎn)程連接手機(jī)終端操作體驗(yàn)會(huì)好很多。接下來(lái)克隆項(xiàng)目、安裝依賴git clone 你的OpenClaw倉(cāng)庫(kù)地址 cd 項(xiàng)目目錄 npm install配置方面存儲(chǔ)層直接用 SQLite省內(nèi)存模型可以指向局域網(wǎng)內(nèi)電腦上的 Ollama也可以直接在手機(jī)上跑小模型但手機(jī)會(huì)發(fā)熱明顯實(shí)際用下來(lái)不如遠(yuǎn)程調(diào)用順暢。啟動(dòng)命令和電腦上一樣根據(jù)項(xiàng)目 README 使用npm start或入口文件。一個(gè)必須處理的問(wèn)題是安卓后臺(tái)殺進(jìn)程鎖屏后 Termux 進(jìn)程容易被回收。執(zhí)行termux-wake-lock可以暫時(shí)阻止系統(tǒng)休眠這是 Termux 部署必須記住的一條命令否則第二天醒來(lái)會(huì)發(fā)現(xiàn)助手已經(jīng)斷了。5.2 電商客服與訂單場(chǎng)景怎么配OpenClaw 在電商場(chǎng)景里完全可以當(dāng)做一個(gè)“業(yè)務(wù)查詢助手”。很多后臺(tái)系統(tǒng)的訂單、庫(kù)存數(shù)據(jù)都在數(shù)據(jù)庫(kù)里OpenClaw 要做的不是直接暴露數(shù)據(jù)庫(kù)而是通過(guò)技能封裝查詢邏輯。我設(shè)計(jì)電商場(chǎng)景時(shí)最喜歡用的模式是數(shù)據(jù)庫(kù)只存數(shù)據(jù)技能提供查詢?nèi)肟谀Ｐ拓?fù)責(zé)理解用戶問(wèn)法。比如你先建一張商品表CREATE TABLE products ( id INT PRIMARY KEY, name VARCHAR(200), price DECIMAL(10,2), stock INT );然后寫一個(gè)query_product技能接收keyword參數(shù)在腳本里執(zhí)行 SQL 查詢只返回結(jié)果 JSON。模型收到用戶消息“幫我查一下保溫杯的價(jià)格”它看到技能描述提取關(guān)鍵詞“保溫杯”調(diào)用腳本最終返回價(jià)格信息。這種設(shè)計(jì)的一個(gè)核心原則是把數(shù)據(jù)庫(kù)讀寫操作控制在技能腳本里不要讓模型生成 SQL。模型生成的 SQL 可能不準(zhǔn)確也可能帶了破壞性語(yǔ)句。電商場(chǎng)景更要謹(jǐn)慎查詢訂單、改庫(kù)存、發(fā)通知這些操作要分成只讀技能和寫入技能寫入類技能必須增加確認(rèn)環(huán)節(jié)。比如用戶說(shuō)“把訂單 123 的快遞單號(hào)發(fā)給客戶”這個(gè)操作應(yīng)該先展示擬發(fā)送內(nèi)容確認(rèn)后再執(zhí)行不能直接讓模型一把梭。5.3 機(jī)器人仿真OpenClaw ROS2 Humble Gazebo搜索里有“rosclaw openclaw ros2 humble gazebo”這明顯是把 OpenClaw 當(dāng)成機(jī)器人仿真環(huán)境的“大腦”來(lái)用。ROS2 是機(jī)器人領(lǐng)域的標(biāo)準(zhǔn)中間件Gazebo 是常見(jiàn)仿真環(huán)境OpenClaw 在里面的角色是自然語(yǔ)言控制入口。先說(shuō)版本組合。ROS2 Humble 官方主要支持 Ubuntu 22.04如果你用的是 Ubuntu 24.04 LTS我建議直接上 ROS2 Jazzy配置思路完全一樣。在 Ubuntu 22.04 上按官方文檔裝完 Humble 和 Gazebo 后每次使用終端要加載環(huán)境source /opt/ros/humble/setup.bash這個(gè) source 動(dòng)作很關(guān)鍵ROS2 命令依賴環(huán)境變量直接在 OpenClaw 的技能腳本里要用bash -c包一層例如寫一個(gè)機(jī)器人控制技能--- name: robot_cmd description: 向 ROS2 仿真環(huán)境發(fā)布控制指令。當(dāng)用戶需要移動(dòng)機(jī)器人或設(shè)置線速度、角速度時(shí)使用。 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 ---這個(gè)技能的效果是你在 OpenClaw 里說(shuō)“讓機(jī)器人前進(jìn)”模型識(shí)別意圖后調(diào)用技能向 Gazebo 里的仿真機(jī)器人發(fā)布速度消息。先把環(huán)境 source 進(jìn)去再執(zhí)行ros2 topic pub這樣腳本能正常運(yùn)行。實(shí)際調(diào)試中要注意ROS2 的 topic 消息格式要求嚴(yán)格括號(hào)和引號(hào)容易出錯(cuò)。建議先手動(dòng)在終端跑一遍命令確認(rèn)機(jī)器人動(dòng)了再掛到技能腳本里。安全第一在仿真環(huán)境里可以隨便試真機(jī)環(huán)境一定要加急停邏輯。5.4 和其他常見(jiàn)開(kāi)發(fā)工具鏈共存熱搜詞里還有一些開(kāi)發(fā)工具配置比如 XAMPP、Tomcat、若依、Zotero。這些工具和 OpenClaw 不是替代關(guān)系更多是共存。核心撞車點(diǎn)只有兩個(gè)端口和數(shù)據(jù)庫(kù)。XAMPP 自帶 MySQL 和 Apache如果已啟動(dòng)默認(rèn)占 3306 和 80/443 端口。OpenClaw 要用同一個(gè) MySQL要么復(fù)用 XAMPP 的 MySQL要么把其中一個(gè)改端口。Tomcat 默認(rèn) 8080若依這類 Java 后臺(tái)也會(huì)用到 MySQL 和 Redis只要端口不沖突完全可以在同一臺(tái)機(jī)器上并存。Zotero 是文獻(xiàn)管理工具它能作為 OpenClaw 的知識(shí)來(lái)源。思路是把 Zotero 數(shù)據(jù)庫(kù)當(dāng)成只讀數(shù)據(jù)源寫一個(gè)技能定期導(dǎo)出條目或者直接在技能腳本里查詢 Zotero 的 SQLite 數(shù)據(jù)庫(kù)文件。這樣你可以在 OpenClaw 里問(wèn)“我上個(gè)月存的文獻(xiàn)有哪些”它會(huì)從 Zotero 的數(shù)據(jù)里找到答案。這個(gè)玩法不是必須的但可以體現(xiàn) OpenClaw 的擴(kuò)展方式只要數(shù)據(jù)能被讀取就能被模型使用。6. 常見(jiàn)問(wèn)題與排查速查6.1 問(wèn)題速查表配置過(guò)程中會(huì)遇到很多重復(fù)問(wèn)題我整理了一張速查表照著查效率最高。癥狀可能原因排查方法啟動(dòng)報(bào)錯(cuò)提示找不到模塊Node 版本太低或依賴沒(méi)裝全node -v檢查版本刪除node_modules后重裝模型一直不回復(fù)baseUrl不通或模型名錯(cuò)誤用 curl 直接請(qǐng)求模型接口驗(yàn)證Ollama 跨設(shè)備連不上服務(wù)只監(jiān)聽(tīng)了本機(jī)地址用OLLAMA_HOST0.0.0.0啟動(dòng)連接 MySQL 報(bào)認(rèn)證錯(cuò)誤認(rèn)證插件不兼容改用mysql_native_password認(rèn)證中文回復(fù)夾雜英文模型選型或人設(shè)問(wèn)題換成中文友好模型重寫persona.md技能始終不觸發(fā)description寫得太模糊重寫技能的觸發(fā)場(chǎng)景描述手機(jī)鎖屏后進(jìn)程斷掉系統(tǒng)回收了后臺(tái)進(jìn)程在 Termux 里執(zhí)行termux-wake-lock改完配置沒(méi)生效沒(méi)有重啟進(jìn)程重啟 OpenClaw配置是啟動(dòng)時(shí)加載的端口被占用其他服務(wù)占用了 3000/3306/8080查看占用進(jìn)程修改端口配置這張表基本覆蓋了我在 Windows、Ubuntu、Termux 三端部署時(shí)遇到的高頻問(wèn)題。每一條背后都對(duì)應(yīng)一次真實(shí)排查經(jīng)歷照著做比從頭看日志要快得多。6.2 我踩過(guò)的幾個(gè)坑第一個(gè)坑是 Windows 下 MySQL 初始化失敗。問(wèn)題出在my.ini里的路徑用反斜杠寫成了C:\mysql...MySQL 解析時(shí)容易出問(wèn)題。改成正斜杠C:/mysql...后一次通過(guò)。所以寫配置文件時(shí)路徑分隔符要統(tǒng)一別混用。第二個(gè)坑是讓模型直接查數(shù)據(jù)庫(kù)。早期圖省事給模型開(kāi)放了 SQL 權(quán)限結(jié)果用戶問(wèn)訂單時(shí)模型生成了錯(cuò)誤 SQL把整張表掃了一遍。后來(lái)我改成所有查詢都走技能腳本把 SQL 寫死在腳本里只讓模型傳參數(shù)。數(shù)據(jù)訪問(wèn)更安全響應(yīng)也更可預(yù)測(cè)。第三個(gè)坑是 Ollama 模型文件過(guò)大導(dǎo)致手機(jī)不堪重負(fù)。在安卓 Termux 上跑 7B 模型雖然能跑但同時(shí)跑 OpenClaw 和模型推理手機(jī)會(huì)非常燙。后來(lái)我把手機(jī)端模型層去掉讓手機(jī)只作為前端模型統(tǒng)一走局域網(wǎng)里電腦上的 Ollama。這樣分工才合理不能什么都往手機(jī)上塞。第四個(gè)坑是.env被提交到 Git。有一次做示例項(xiàng)目沒(méi)注意.gitignore漏了.env結(jié)果密鑰全被推到倉(cāng)庫(kù)里只能緊急撤下并且把 Key 全部重置。從那以后我所有項(xiàng)目的第一件事就是先寫好.gitignore把.env、node_modules、data目錄全部排除掉。這個(gè)習(xí)慣從來(lái)沒(méi)有讓我后悔過(guò)。最后再分享一個(gè)小習(xí)慣把openclaw.json、persona.md和整個(gè)skills目錄納入 Git但.env永遠(yuǎn)不進(jìn)倉(cāng)庫(kù)。我本地、服務(wù)器、手機(jī)三份環(huán)境共用一套代碼差異只靠.env切換。以后想換模型只需要改一行ENV變量不用動(dòng)任何邏輯。這樣管理配置類項(xiàng)目長(zhǎng)期用下來(lái)是最省心的。 OpenClaw 從零配置到多場(chǎng)景擴(kuò)展：模型、技能與部署全攻略
把 OpenClaw 從倉(cāng)庫(kù)里拉下來(lái)只是開(kāi)始真正的折騰在后面的配置Git 要裝吧數(shù)據(jù)庫(kù)要選吧模型用云 API 還是本地 Ollama技能目錄怎么放手機(jī)上還想跑一個(gè)部署端……我一圈試下來(lái)發(fā)現(xiàn)大多數(shù)人不是卡在“不會(huì)敲命令”而是卡在“不知道這些零件是怎么咬合在一起的”。這篇文章就把我實(shí)際跑通的配置路徑拆開(kāi)講從基礎(chǔ)環(huán)境、模型接入、技能編寫到安卓 Termux、電商和 ROS2 仿真場(chǎng)景的擴(kuò)展最后附一份排查速查表。適合剛拿到 OpenClaw 的新手也適合已經(jīng)在用其他智能體框架、想快速切換過(guò)來(lái)的開(kāi)發(fā)者。1. 先搞清楚 OpenClaw 是什么再動(dòng)手配置1.1 它解決什么問(wèn)題OpenClaw 是一個(gè)開(kāi)源的個(gè)人 AI 助手項(xiàng)目核心不是“陪你聊天”而是讓你通過(guò)聊天或者本地接口指揮它做事查日程、發(fā)提醒、查數(shù)據(jù)庫(kù)、跑腳本、調(diào)接口。傳統(tǒng)大模型只能生成文字OpenClaw 相當(dāng)于給模型裝了一雙手通過(guò)技能模塊去執(zhí)行真實(shí)操作。我見(jiàn)過(guò)很多人一上來(lái)就照著網(wǎng)上的命令裝依賴裝完 MySQL 又裝數(shù)據(jù)庫(kù)結(jié)果項(xiàng)目根本起不來(lái)原因就是沒(méi)理解它是個(gè)組件拼裝型項(xiàng)目。OpenClaw 的運(yùn)行至少需要四樣?xùn)|西模型、存儲(chǔ)、消息渠道、技能。模型負(fù)責(zé)理解和決策存儲(chǔ)負(fù)責(zé)記錄消息和長(zhǎng)期記憶消息渠道負(fù)責(zé)接收你的指令技能負(fù)責(zé)真正把指令落地。配置教程的本質(zhì)就是把這四樣?xùn)|西分別接通再讓它們互相認(rèn)識(shí)。搞清楚這一點(diǎn)之后你就不會(huì)再問(wèn)“為什么我裝了個(gè) MySQL 項(xiàng)目還是不動(dòng)”這種問(wèn)題了。MySQL 只是存儲(chǔ)層的一個(gè)選項(xiàng)模型連不上、技能沒(méi)配、消息渠道沒(méi)監(jiān)聽(tīng)任何一個(gè)環(huán)節(jié)斷了整個(gè)項(xiàng)目都表現(xiàn)異常。所以后面的所有步驟都是圍繞這條鏈路來(lái)做的。1.2 配置前先做一張清單我每次部署新環(huán)境都會(huì)先在紙上列一張清單把下面幾個(gè)問(wèn)題寫清楚再動(dòng)手。配置項(xiàng)作用常見(jiàn)選擇運(yùn)行環(huán)境提供 Node.js 執(zhí)行環(huán)境Windows / Ubuntu / Termux 安卓環(huán)境代碼管理拉取項(xiàng)目、管理技能Git模型大腦負(fù)責(zé)語(yǔ)義理解與工具調(diào)用云 API、本地 Ollama、任意 OpenAI 兼容接口存儲(chǔ)保存消息、業(yè)務(wù)數(shù)據(jù)、記憶SQLite、MySQL消息渠道接收用戶指令并返回結(jié)果本地 HTTP、命令行、聊天應(yīng)用接口技能讓模型具備執(zhí)行外部操作的能力內(nèi)置技能、社區(qū)技能、自寫技能這張表里的每一項(xiàng)都不是可選項(xiàng)而是必選項(xiàng)只是不同場(chǎng)景的選型不同。比如你只想在電腦上自己試用SQLite 就夠了你要是想把它當(dāng)成一個(gè)長(zhǎng)期跑的本地服務(wù)MySQL 會(huì)更順暢。先列清單再動(dòng)手能少走很多彎路這也是我反復(fù)強(qiáng)調(diào)的第一步。1.3 配置文件的整體結(jié)構(gòu)OpenClaw 的配置一般會(huì)拆成幾類文件而不是全部塞在一個(gè)文件里。這里給出一套最常見(jiàn)的目錄劃分方式具體文件名以你拉下來(lái)的項(xiàng)目 README 為準(zhǔn)但分層邏輯基本一致openclaw-project/ ├── .env # 密鑰、模型端點(diǎn)、環(huán)境差異配置 ├── openclaw.json # 主配置存儲(chǔ)、渠道、技能目錄 ├── persona.md # 人設(shè)與回復(fù)風(fēng)格 ├── skills/ │ └── current_time/ # 技能目錄 └── data/ └── openclaw.db # SQLite 數(shù)據(jù)庫(kù)文件為什么拆開(kāi)因?yàn)?env里放著 API Key、數(shù)據(jù)庫(kù)密碼這種敏感信息絕對(duì)不能提交到 Git而openclaw.json是機(jī)器配置可以隨項(xiàng)目走persona.md是給人看、給模型看的行為描述換模型也能復(fù)用。把這三者分開(kāi)你換一臺(tái)機(jī)器部署時(shí)只需要拷配置和技能不用把整個(gè)環(huán)境都折騰一遍。openclaw.json最常見(jiàn)的骨架長(zhǎng)這樣字段名在不同版本里可能有差異但表達(dá)的意思是一致的{ 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 }配置基本是啟動(dòng)時(shí)讀取的改完必須重啟進(jìn)程。很多人改完模型參數(shù)發(fā)現(xiàn)沒(méi)反應(yīng)往往就是沒(méi)重啟或者.env沒(méi)被正確加載。2. 基礎(chǔ)環(huán)境安裝Git、Node.js、數(shù)據(jù)庫(kù)2.1 Windows 上的完整安裝流程Windows 是不少人的主力環(huán)境我先把 Windows 的配置流程完整走一遍。先后順序建議是Git → Node.js → MySQL → SQLite因?yàn)轫?xiàng)目拉取和運(yùn)行依賴前兩個(gè)存儲(chǔ)層后面再定。Git 的安裝沒(méi)什么技術(shù)含量一路 Next 就行但有兩個(gè)地方要注意。一是安裝完必須配置用戶名和郵箱否則提交技能代碼時(shí)會(huì)報(bào)錯(cuò)二是要把 Git Bash 加入 PATH方便在終端里直接使用。配置命令很簡(jiǎn)單git config --global user.name 你的名字 git config --global user.email 你的郵箱 git config --global core.autocrlf truecore.autocrlf true是 Windows 上最容易忽略的一項(xiàng)它能把行尾符自動(dòng)轉(zhuǎn)換避免從倉(cāng)庫(kù)拉下來(lái)的腳本因?yàn)閾Q行符問(wèn)題在 Windows 上報(bào)錯(cuò)。Node.js 建議裝 LTS 版本。OpenClaw 這類項(xiàng)目對(duì) Node 版本有最低要求太老的版本裝依賴時(shí)會(huì)看到一堆 engine 相關(guān)的警告。裝完之后打開(kāi)終端驗(yàn)證node -v npm -v如果出現(xiàn)版本號(hào)這一步就算過(guò)了。MySQL 8 的 zip 方式配置我用過(guò)很多次。從 MySQL 官網(wǎng)下載mysql-8.x-winx64.zip解壓到一個(gè)不含空格的路徑比如C:\mysql-8.x-winx64。然后在這個(gè)目錄下手動(dòng)建一個(gè)my.ini[mysqld] basedirC:/mysql-8.x-winx64 datadirC:/mysql-8.x-winx64/data port3306 character-set-serverutf8mb4用管理員身份打開(kāi) PowerShell進(jìn)入解壓目錄的bin文件夾執(zhí)行初始化命令.\mysqld --initialize-insecure這個(gè)命令會(huì)生成一個(gè)無(wú)密碼的 root 賬號(hào)并創(chuàng)建data目錄。接著注冊(cè) Windows 服務(wù).\mysqld --install OpenClawMySQL net start OpenClawMySQL服務(wù)啟動(dòng)后登錄數(shù)據(jù)庫(kù).\mysql -u root然后給 root 設(shè)置密碼創(chuàng)建項(xiàng)目庫(kù)ALTER USER rootlocalhost IDENTIFIED BY 你的密碼; CREATE DATABASE openclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;utf8mb4一定要選否則后續(xù)存儲(chǔ)中文內(nèi)容會(huì)出現(xiàn)亂碼。這一步是很多中文用戶踩坑的重災(zāi)區(qū)默認(rèn)的 latin1 字符集存不了中文。2.2 Ubuntu 24.04 LTS 上的環(huán)境配置如果用的是 Linux 服務(wù)器Ubuntu 24.04 LTS 是我的首選。安裝命令比 Windows 簡(jiǎn)單很多sudo apt update sudo apt install -y git nodejs npm mysql-server sqlite3裝完之后檢查版本node -v git --version mysql --versionUbuntu 下 MySQL 的 root 賬號(hào)默認(rèn)使用 auth_socket 認(rèn)證直接sudo mysql就能登錄但 OpenClaw 用普通密碼連接時(shí)會(huì)失敗。建議創(chuàng)建一個(gè)專用賬號(hào)而不是去折騰 rootsudo mysql進(jìn)入 MySQL 后執(zhí)行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賬號(hào)連openclaw庫(kù)權(quán)限邊界清楚不會(huì)動(dòng)不動(dòng)拿 root 去跑應(yīng)用。2.3 SQLite 還是 MySQL我的選擇邏輯很多人會(huì)在 SQLite 和 MySQL 之間糾結(jié)。我的建議很簡(jiǎn)單單機(jī)自用無(wú)腦選 SQLite準(zhǔn)備長(zhǎng)期跑服務(wù)、多端訪問(wèn)再上 MySQL。SQLite 的配置成本幾乎為零數(shù)據(jù)就是一個(gè)文件備份直接復(fù)制文件即可。OpenClaw 在本地開(kāi)發(fā)階段用 SQLite 最舒服項(xiàng)目出問(wèn)題刪掉數(shù)據(jù)庫(kù)文件就能重置。但它不適合并發(fā)寫多的場(chǎng)景如果多個(gè)渠道同時(shí)寫入數(shù)據(jù)庫(kù)文件會(huì)被鎖住。MySQL 適合作為獨(dú)立服務(wù)運(yùn)行能扛住更多連接也方便你在服務(wù)器上部署后從別處訪問(wèn)。代價(jià)是你得多管一個(gè)服務(wù)多處理一套權(quán)限和認(rèn)證問(wèn)題。MySQL 8 默認(rèn)的caching_sha2_password認(rèn)證插件和部分老版本驅(qū)動(dòng)不兼容如果連接時(shí)報(bào)認(rèn)證錯(cuò)誤可以在 MySQL 里單獨(dú)改一下ALTER USER openclawlocalhost IDENTIFIED WITH mysql_native_password BY 你的密碼;SQLite 沒(méi)有這種煩惱Windows 和 Linux 下基本開(kāi)箱即用。如果你只是想在電腦上體驗(yàn) OpenClaw別為了“正式”去裝 MySQL那是給自己找麻煩。2.4 Git 初始化與項(xiàng)目拉取環(huán)境裝完后把項(xiàng)目拉下來(lái)。我建議優(yōu)先用 SSH 方式而不是 HTTPS避免每次操作都輸密碼。生成密鑰ssh-keygen -t ed25519 -C 你的郵箱然后查看公鑰并添加到代碼托管平臺(tái)cat ~/.ssh/id_ed25519.pub添加完公鑰后從項(xiàng)目主頁(yè)復(fù)制 SSH 格式的倉(cāng)庫(kù)地址執(zhí)行g(shù)it clone 你的OpenClaw倉(cāng)庫(kù)地址 cd 項(xiàng)目目錄 npm install這一步如果報(bào)權(quán)限錯(cuò)誤多半是 SSH key 沒(méi)配好如果報(bào)依賴錯(cuò)誤先看 Node 版本。npm install完成后項(xiàng)目的基礎(chǔ)運(yùn)行環(huán)境就緒下面開(kāi)始接模型。3. 模型接入云 API 與本地 Ollama 全覆蓋3.1 先回答那個(gè)高頻問(wèn)題搜索里經(jīng)?？吹接腥藛?wèn)“OpenClaw 只能用接入 API 的方式使用算力嗎”這是個(gè)誤解。OpenClaw 在模型層是模型無(wú)關(guān)的凡是提供 OpenAI 兼容接口的模型都能接入。所謂算力可以來(lái)自云端廠商也可以來(lái)自你自己的電腦或服務(wù)器。云 API 的優(yōu)點(diǎn)是模型大、聰明缺點(diǎn)是每次調(diào)用都要走網(wǎng)絡(luò)、按量付費(fèi)。本地 Ollama 的優(yōu)點(diǎn)是數(shù)據(jù)不出門、不花錢、斷網(wǎng)也能用缺點(diǎn)是受機(jī)器性能限制只能跑參數(shù)較小的模型。OpenClaw 本身不綁定算力來(lái)源你在配置里填不同的baseUrl它就會(huì)去不同的地方找模型。這個(gè)設(shè)計(jì)很實(shí)用開(kāi)發(fā)階段用本地模型上線后切云端大模型只改配置不改代碼。3.2 Ollama 部署與配置步驟Ollama 是目前最簡(jiǎn)單易用的本地模型運(yùn)行工具支持 Windows、macOS、Linux。安裝完成后終端里執(zhí)行ollama pull qwen2.5:7b國(guó)內(nèi)中文場(chǎng)景我優(yōu)先選 Qwen 系列中文理解和生成質(zhì)量在線。拉取完成后驗(yàn)證ollama list看到模型列表就說(shuō)明本地服務(wù)已經(jīng)起來(lái)了。默認(rèn)情況下 Ollama 會(huì)監(jiān)聽(tīng)http://localhost:11434而且提供了 OpenAI 兼容接口路徑是/v1。這就是 OpenClaw 能直接接入的原因。在 OpenClaw 的.env里這樣寫OPENCLAW_MODEL_BASE_URLhttp://localhost:11434/v1 OPENCLAW_MODEL_API_KEYollama OPENCLAW_MODEL_NAMEqwen2.5:7b很多本地接口不校驗(yàn) Key隨便填一個(gè)占位符就行。配置好后可以用 curl 快速驗(yàn)證curl http://localhost:11434/v1/models能返回 JSON 模型列表說(shuō)明鏈路通。這時(shí)啟動(dòng) OpenClaw發(fā)一條消息測(cè)試它應(yīng)該就能通過(guò)本地模型回復(fù)了。如果 OpenClaw 跑在另一臺(tái)機(jī)器上要把上面的localhost改成 Ollama 所在機(jī)器的局域網(wǎng) IP并且 Ollama 需要監(jiān)聽(tīng)外部地址OLLAMA_HOST0.0.0.0 ollama serve不加這一步跨設(shè)備訪問(wèn)會(huì)被拒絕。我自己測(cè)試時(shí)踩過(guò)一次坑OpenClaw 始終連不上查半天才發(fā)現(xiàn) Ollama 只監(jiān)聽(tīng)了127.0.0.1。3.3 “中文版”不是安裝包是配置搜索“OpenClaw 中文版”的人很多實(shí)際上 OpenClaw 并沒(méi)有一個(gè)獨(dú)立的中文安裝包它是一個(gè)配置化項(xiàng)目“中文版”是在配置層面實(shí)現(xiàn)的。要做三件事選擇中文友好的模型、用中文寫 persona、把模型參數(shù)里的語(yǔ)言偏好調(diào)成中文。最影響體驗(yàn)的是模型選型。用本地推理就選 Qwen、GLM 系列云端服務(wù)可以用支持中文更好的大模型。模型選好后寫persona.md你是一個(gè)名叫小爪的個(gè)人 AI 助手。 默認(rèn)使用簡(jiǎn)體中文回復(fù)。 回答要簡(jiǎn)潔、直接不要重復(fù)用戶的話。 如果用戶沒(méi)有指定格式優(yōu)先給出可執(zhí)行的操作步驟。這段內(nèi)容不要寫得像功能說(shuō)明書(shū)要寫得像對(duì)一個(gè)人的行為要求。模型會(huì)把它當(dāng)成系統(tǒng)提示詞來(lái)遵循。你會(huì)發(fā)現(xiàn)同樣的模型寫清楚人設(shè)后回復(fù)質(zhì)量提升非常明顯。很多人說(shuō)“中文版不好用”其實(shí)是人設(shè)文件寫得太籠統(tǒng)模型不知道該怎么表現(xiàn)。3.4 密鑰與安全模型接入涉及 API Key安全習(xí)慣要從第一天就養(yǎng)成。Key 只放.env不要寫進(jìn)openclaw.json更不要提交到 Git。.gitignore里必須加上.env還要盡量給云端 API 設(shè)置調(diào)用額度上限防止 Key 泄露后被刷爆。本地 Ollama 雖然沒(méi)有 Key 概念但如果開(kāi)放了局域網(wǎng)訪問(wèn)最好限制在可信內(nèi)網(wǎng)別直接暴露到公網(wǎng)。這些都是配置之外最容易忽略的事但恰恰是最重要的。4. 技能Skill配置實(shí)戰(zhàn)4.1 技能的設(shè)計(jì)邏輯OpenClaw 的能力上限很大程度取決于技能怎么配。技能的本質(zhì)是給模型提供一份“工具使用說(shuō)明書(shū)”和一個(gè)可執(zhí)行腳本。模型本身不會(huì)直接執(zhí)行代碼它看到用戶消息后根據(jù)技能的描述判斷該調(diào)用哪個(gè)工具然后運(yùn)行對(duì)應(yīng)的腳本再把腳本輸出拿回來(lái)加工成回復(fù)。打個(gè)比方模型是大腦技能是手。大腦不能直接拿杯子但大腦知道“伸手”這個(gè)動(dòng)作可以拿杯子于是它指揮手去執(zhí)行。OpenClaw 里SKILL.md就是大腦看到的動(dòng)作描述腳本就是手。這個(gè)設(shè)計(jì)也解釋了為什么技能的描述必須寫清楚否則大腦不知道什么時(shí)候該伸手。4.2 寫一個(gè)最小可用技能我建議新手第一個(gè)技能不要搞復(fù)雜就寫一個(gè)查詢當(dāng)前時(shí)間的技能跑通完整鏈路。在skills目錄下建一個(gè)子目錄skills/ current_time/ SKILL.md script.jsSKILL.md內(nèi)容如下--- name: current_time description: 查詢當(dāng)前日期和時(shí)間。當(dāng)用戶問(wèn)“現(xiàn)在幾點(diǎn)”“今天幾號(hào)”“現(xiàn)在時(shí)間”時(shí)使用。 command: node script.js ---script.js只需要一行console.log(new Date().toString());然后在openclaw.json里確認(rèn)skillsDir指向./skills重啟 OpenClaw。之后用戶說(shuō)“現(xiàn)在幾點(diǎn)”模型會(huì)看到current_time的描述調(diào)用腳本把時(shí)間輸出返回給用戶。整個(gè)流程走通后你就理解了 OpenClaw 的核心機(jī)制模型的判斷 技能的執(zhí)行。寫技能時(shí)有幾個(gè)細(xì)節(jié)要注意。一是description要寫清楚觸發(fā)場(chǎng)景太模糊的技能模型不會(huì)調(diào)用二是腳本一定要處理異常不然模型拿到錯(cuò)誤信息也不知道怎么辦三是腳本輸出要簡(jiǎn)潔最好只輸出結(jié)果別把一堆日志也丟給模型那會(huì)干擾回復(fù)生成。4.3 社區(qū)技能的使用原則社區(qū)里能搜到很多現(xiàn)成的技能用起來(lái)方便但風(fēng)險(xiǎn)也在。我的原則是不直接運(yùn)行沒(méi)看過(guò)的技能。拿到一個(gè)技能包先打開(kāi)SKILL.md看它聲明了什么操作再看腳本依賴了哪些第三方庫(kù)最后看有沒(méi)有網(wǎng)絡(luò)外發(fā)、文件刪除這類危險(xiǎn)動(dòng)作。技能一旦掛載模型就可能在特定條件下調(diào)用它等于給外部腳本開(kāi)了一個(gè)執(zhí)行口子。有一次我下載了一個(gè)“天氣查詢”技能結(jié)果腳本里還藏了一段上傳用戶目錄文件的代碼。從那以后我對(duì)社區(qū)技能一律先審查再掛載。這個(gè)習(xí)慣在配置 OpenClaw 時(shí)非常重要因?yàn)樗皇羌兞奶鞈?yīng)用它真的會(huì)執(zhí)行命令。5. 進(jìn)階場(chǎng)景安卓 Termux、電商、ROS25.1 Termux 安卓部署把 OpenClaw 跑在安卓手機(jī)上等于隨身帶了一個(gè)離線助手。搜索里提到的“Termux 安裝 OpenClaw 手機(jī)版”邏輯上不是安裝 APK而是在安卓環(huán)境里搭一個(gè)完整的 Node.js 運(yùn)行環(huán)境。Termux 不要從應(yīng)用商店下載版本太舊建議通過(guò) F-Droid 獲取。安裝后先換源更新軟件包pkg update pkg upgrade然后安裝依賴pkg install nodejs-lts git sqlite openssh安裝完 SSH 后可以用電腦遠(yuǎn)程連接手機(jī)終端操作體驗(yàn)會(huì)好很多。接下來(lái)克隆項(xiàng)目、安裝依賴git clone 你的OpenClaw倉(cāng)庫(kù)地址 cd 項(xiàng)目目錄 npm install配置方面存儲(chǔ)層直接用 SQLite省內(nèi)存模型可以指向局域網(wǎng)內(nèi)電腦上的 Ollama也可以直接在手機(jī)上跑小模型但手機(jī)會(huì)發(fā)熱明顯實(shí)際用下來(lái)不如遠(yuǎn)程調(diào)用順暢。啟動(dòng)命令和電腦上一樣根據(jù)項(xiàng)目 README 使用npm start或入口文件。一個(gè)必須處理的問(wèn)題是安卓后臺(tái)殺進(jìn)程鎖屏后 Termux 進(jìn)程容易被回收。執(zhí)行termux-wake-lock可以暫時(shí)阻止系統(tǒng)休眠這是 Termux 部署必須記住的一條命令否則第二天醒來(lái)會(huì)發(fā)現(xiàn)助手已經(jīng)斷了。5.2 電商客服與訂單場(chǎng)景怎么配OpenClaw 在電商場(chǎng)景里完全可以當(dāng)做一個(gè)“業(yè)務(wù)查詢助手”。很多后臺(tái)系統(tǒng)的訂單、庫(kù)存數(shù)據(jù)都在數(shù)據(jù)庫(kù)里OpenClaw 要做的不是直接暴露數(shù)據(jù)庫(kù)而是通過(guò)技能封裝查詢邏輯。我設(shè)計(jì)電商場(chǎng)景時(shí)最喜歡用的模式是數(shù)據(jù)庫(kù)只存數(shù)據(jù)技能提供查詢?nèi)肟谀Ｐ拓?fù)責(zé)理解用戶問(wèn)法。比如你先建一張商品表CREATE TABLE products ( id INT PRIMARY KEY, name VARCHAR(200), price DECIMAL(10,2), stock INT );然后寫一個(gè)query_product技能接收keyword參數(shù)在腳本里執(zhí)行 SQL 查詢只返回結(jié)果 JSON。模型收到用戶消息“幫我查一下保溫杯的價(jià)格”它看到技能描述提取關(guān)鍵詞“保溫杯”調(diào)用腳本最終返回價(jià)格信息。這種設(shè)計(jì)的一個(gè)核心原則是把數(shù)據(jù)庫(kù)讀寫操作控制在技能腳本里不要讓模型生成 SQL。模型生成的 SQL 可能不準(zhǔn)確也可能帶了破壞性語(yǔ)句。電商場(chǎng)景更要謹(jǐn)慎查詢訂單、改庫(kù)存、發(fā)通知這些操作要分成只讀技能和寫入技能寫入類技能必須增加確認(rèn)環(huán)節(jié)。比如用戶說(shuō)“把訂單 123 的快遞單號(hào)發(fā)給客戶”這個(gè)操作應(yīng)該先展示擬發(fā)送內(nèi)容確認(rèn)后再執(zhí)行不能直接讓模型一把梭。5.3 機(jī)器人仿真OpenClaw ROS2 Humble Gazebo搜索里有“rosclaw openclaw ros2 humble gazebo”這明顯是把 OpenClaw 當(dāng)成機(jī)器人仿真環(huán)境的“大腦”來(lái)用。ROS2 是機(jī)器人領(lǐng)域的標(biāo)準(zhǔn)中間件Gazebo 是常見(jiàn)仿真環(huán)境OpenClaw 在里面的角色是自然語(yǔ)言控制入口。先說(shuō)版本組合。ROS2 Humble 官方主要支持 Ubuntu 22.04如果你用的是 Ubuntu 24.04 LTS我建議直接上 ROS2 Jazzy配置思路完全一樣。在 Ubuntu 22.04 上按官方文檔裝完 Humble 和 Gazebo 后每次使用終端要加載環(huán)境source /opt/ros/humble/setup.bash這個(gè) source 動(dòng)作很關(guān)鍵ROS2 命令依賴環(huán)境變量直接在 OpenClaw 的技能腳本里要用bash -c包一層例如寫一個(gè)機(jī)器人控制技能--- name: robot_cmd description: 向 ROS2 仿真環(huán)境發(fā)布控制指令。當(dāng)用戶需要移動(dòng)機(jī)器人或設(shè)置線速度、角速度時(shí)使用。 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 ---這個(gè)技能的效果是你在 OpenClaw 里說(shuō)“讓機(jī)器人前進(jìn)”模型識(shí)別意圖后調(diào)用技能向 Gazebo 里的仿真機(jī)器人發(fā)布速度消息。先把環(huán)境 source 進(jìn)去再執(zhí)行ros2 topic pub這樣腳本能正常運(yùn)行。實(shí)際調(diào)試中要注意ROS2 的 topic 消息格式要求嚴(yán)格括號(hào)和引號(hào)容易出錯(cuò)。建議先手動(dòng)在終端跑一遍命令確認(rèn)機(jī)器人動(dòng)了再掛到技能腳本里。安全第一在仿真環(huán)境里可以隨便試真機(jī)環(huán)境一定要加急停邏輯。5.4 和其他常見(jiàn)開(kāi)發(fā)工具鏈共存熱搜詞里還有一些開(kāi)發(fā)工具配置比如 XAMPP、Tomcat、若依、Zotero。這些工具和 OpenClaw 不是替代關(guān)系更多是共存。核心撞車點(diǎn)只有兩個(gè)端口和數(shù)據(jù)庫(kù)。XAMPP 自帶 MySQL 和 Apache如果已啟動(dòng)默認(rèn)占 3306 和 80/443 端口。OpenClaw 要用同一個(gè) MySQL要么復(fù)用 XAMPP 的 MySQL要么把其中一個(gè)改端口。Tomcat 默認(rèn) 8080若依這類 Java 后臺(tái)也會(huì)用到 MySQL 和 Redis只要端口不沖突完全可以在同一臺(tái)機(jī)器上并存。Zotero 是文獻(xiàn)管理工具它能作為 OpenClaw 的知識(shí)來(lái)源。思路是把 Zotero 數(shù)據(jù)庫(kù)當(dāng)成只讀數(shù)據(jù)源寫一個(gè)技能定期導(dǎo)出條目或者直接在技能腳本里查詢 Zotero 的 SQLite 數(shù)據(jù)庫(kù)文件。這樣你可以在 OpenClaw 里問(wèn)“我上個(gè)月存的文獻(xiàn)有哪些”它會(huì)從 Zotero 的數(shù)據(jù)里找到答案。這個(gè)玩法不是必須的但可以體現(xiàn) OpenClaw 的擴(kuò)展方式只要數(shù)據(jù)能被讀取就能被模型使用。6. 常見(jiàn)問(wèn)題與排查速查6.1 問(wèn)題速查表配置過(guò)程中會(huì)遇到很多重復(fù)問(wèn)題我整理了一張速查表照著查效率最高。癥狀可能原因排查方法啟動(dòng)報(bào)錯(cuò)提示找不到模塊Node 版本太低或依賴沒(méi)裝全node -v檢查版本刪除node_modules后重裝模型一直不回復(fù)baseUrl不通或模型名錯(cuò)誤用 curl 直接請(qǐng)求模型接口驗(yàn)證Ollama 跨設(shè)備連不上服務(wù)只監(jiān)聽(tīng)了本機(jī)地址用OLLAMA_HOST0.0.0.0啟動(dòng)連接 MySQL 報(bào)認(rèn)證錯(cuò)誤認(rèn)證插件不兼容改用mysql_native_password認(rèn)證中文回復(fù)夾雜英文模型選型或人設(shè)問(wèn)題換成中文友好模型重寫persona.md技能始終不觸發(fā)description寫得太模糊重寫技能的觸發(fā)場(chǎng)景描述手機(jī)鎖屏后進(jìn)程斷掉系統(tǒng)回收了后臺(tái)進(jìn)程在 Termux 里執(zhí)行termux-wake-lock改完配置沒(méi)生效沒(méi)有重啟進(jìn)程重啟 OpenClaw配置是啟動(dòng)時(shí)加載的端口被占用其他服務(wù)占用了 3000/3306/8080查看占用進(jìn)程修改端口配置這張表基本覆蓋了我在 Windows、Ubuntu、Termux 三端部署時(shí)遇到的高頻問(wèn)題。每一條背后都對(duì)應(yīng)一次真實(shí)排查經(jīng)歷照著做比從頭看日志要快得多。6.2 我踩過(guò)的幾個(gè)坑第一個(gè)坑是 Windows 下 MySQL 初始化失敗。問(wèn)題出在my.ini里的路徑用反斜杠寫成了C:\mysql...MySQL 解析時(shí)容易出問(wèn)題。改成正斜杠C:/mysql...后一次通過(guò)。所以寫配置文件時(shí)路徑分隔符要統(tǒng)一別混用。第二個(gè)坑是讓模型直接查數(shù)據(jù)庫(kù)。早期圖省事給模型開(kāi)放了 SQL 權(quán)限結(jié)果用戶問(wèn)訂單時(shí)模型生成了錯(cuò)誤 SQL把整張表掃了一遍。后來(lái)我改成所有查詢都走技能腳本把 SQL 寫死在腳本里只讓模型傳參數(shù)。數(shù)據(jù)訪問(wèn)更安全響應(yīng)也更可預(yù)測(cè)。第三個(gè)坑是 Ollama 模型文件過(guò)大導(dǎo)致手機(jī)不堪重負(fù)。在安卓 Termux 上跑 7B 模型雖然能跑但同時(shí)跑 OpenClaw 和模型推理手機(jī)會(huì)非常燙。后來(lái)我把手機(jī)端模型層去掉讓手機(jī)只作為前端模型統(tǒng)一走局域網(wǎng)里電腦上的 Ollama。這樣分工才合理不能什么都往手機(jī)上塞。第四個(gè)坑是.env被提交到 Git。有一次做示例項(xiàng)目沒(méi)注意.gitignore漏了.env結(jié)果密鑰全被推到倉(cāng)庫(kù)里只能緊急撤下并且把 Key 全部重置。從那以后我所有項(xiàng)目的第一件事就是先寫好.gitignore把.env、node_modules、data目錄全部排除掉。這個(gè)習(xí)慣從來(lái)沒(méi)有讓我后悔過(guò)。最后再分享一個(gè)小習(xí)慣把openclaw.json、persona.md和整個(gè)skills目錄納入 Git但.env永遠(yuǎn)不進(jìn)倉(cāng)庫(kù)。我本地、服務(wù)器、手機(jī)三份環(huán)境共用一套代碼差異只靠.env切換。以后想換模型只需要改一行ENV變量不用動(dòng)任何邏輯。這樣管理配置類項(xiàng)目長(zhǎng)期用下來(lái)是最省心的。