踐)
1. 項(xiàng)目概述OpenClaw是什么以及它為何值得關(guān)注如果你最近在關(guān)注本地AI智能體Agent的部署與應(yīng)用那么“OpenClaw”這個(gè)名字大概率已經(jīng)出現(xiàn)在你的視野里了。它不是一個(gè)新的大語(yǔ)言模型而是一個(gè)開源的、旨在讓AI智能體“開箱即用”的框架平臺(tái)。簡(jiǎn)單來(lái)說(shuō)OpenClaw提供了一個(gè)環(huán)境讓你能夠輕松地將不同的AI模型比如Llama、Qwen、DeepSeek等接入進(jìn)來(lái)并賦予它們執(zhí)行具體任務(wù)的能力比如自動(dòng)回復(fù)消息、處理文檔、調(diào)用外部工具等。你可以把它想象成一個(gè)“AI智能體操作系統(tǒng)”或者一個(gè)功能強(qiáng)大的“AI智能體運(yùn)行沙盒”。我最初接觸OpenClaw是因?yàn)閰捑肓藶槊恳粋€(gè)簡(jiǎn)單的自動(dòng)化需求去寫冗長(zhǎng)的腳本或研究復(fù)雜的API調(diào)用。市面上很多AI應(yīng)用要么是云端服務(wù)存在數(shù)據(jù)隱私和成本的顧慮要么部署起來(lái)極其復(fù)雜對(duì)新手極不友好。OpenClaw的出現(xiàn)恰好瞄準(zhǔn)了這個(gè)痛點(diǎn)它試圖將智能體的部署、配置和管理變得像安裝一個(gè)普通軟件一樣簡(jiǎn)單。通過(guò)Docker容器化部署它極大地降低了環(huán)境配置的復(fù)雜度通過(guò)清晰的技能Skill機(jī)制它讓擴(kuò)展AI能力變得模塊化。無(wú)論是想搭建一個(gè)自動(dòng)處理電商客服的助手還是創(chuàng)建一個(gè)能幫你總結(jié)文檔、生成圖片的個(gè)人AI伙伴OpenClaw都提供了一個(gè)極具潛力的起點(diǎn)。從網(wǎng)絡(luò)上的討論熱度來(lái)看大家關(guān)心的核心問(wèn)題非常集中如何安裝部署Docker、Ubuntu、Windows、Mac、如何配置接入不同的大模型Ollama、API、如何連接實(shí)際應(yīng)用飛書、微信以及在使用中遇到的具體問(wèn)題如會(huì)話記憶丟失、技能安裝。這恰恰說(shuō)明了OpenClaw正處于從技術(shù)嘗鮮走向?qū)嶋H應(yīng)用的關(guān)鍵階段社區(qū)在積極摸索最佳實(shí)踐。本文將基于這些真實(shí)需求為你拆解OpenClaw的核心概念、手把手帶你完成部署配置并分享從零到一構(gòu)建一個(gè)可用智能體的全過(guò)程與避坑經(jīng)驗(yàn)。2. OpenClaw核心架構(gòu)與設(shè)計(jì)思路拆解在動(dòng)手安裝之前理解OpenClaw的基本設(shè)計(jì)哲學(xué)和核心組件能讓你在后續(xù)的配置和問(wèn)題排查中事半功倍。OpenClaw的架構(gòu)可以粗略地分為三層基礎(chǔ)設(shè)施層、核心運(yùn)行時(shí)層和應(yīng)用連接層。2.1 基礎(chǔ)設(shè)施層容器化與模型服務(wù)這是OpenClaw的基石主要解決“在哪里運(yùn)行”和“用什么大腦”的問(wèn)題。容器化部署Docker這是官方最推薦也是問(wèn)題最少的部署方式。OpenClaw本身及其依賴的環(huán)境Python、各種庫(kù)被打包成一個(gè)Docker鏡像。這樣做的好處是環(huán)境隔離你不需要在宿主機(jī)上折騰復(fù)雜的Python版本和庫(kù)依賴沖突。docker-compose.yml文件定義了服務(wù)OpenClaw本身、數(shù)據(jù)庫(kù)等的編排。幾乎所有“極速部署”教程都基于此。模型服務(wù)后端OpenClaw自身不包含大模型它需要一個(gè)“大腦”供應(yīng)商。目前主流支持兩種方式Ollama這是在本地運(yùn)行開源模型最流行的工具。你需要在同一臺(tái)機(jī)器或網(wǎng)絡(luò)內(nèi)部署Ollama并在其中拉取pull你想要的模型如llama3.2:1b,qwen2.5:7b。OpenClaw通過(guò)配置OLLAMA_BASE_URL通常是http://host.docker.internal:11434用于Mac/Windows的Docker Desktop或http://宿主機(jī)IP:11434用于Linux來(lái)連接Ollama服務(wù)。OpenAI兼容API如果你使用云端API服務(wù)如OpenAI、DeepSeek、智譜AI等或者部署了像vLLM、text-generation-webui這類提供兼容API接口的本地模型服務(wù)也可以通過(guò)配置相應(yīng)的API Base URL和Key來(lái)接入。注意很多新手遇到的openclaw llamap svr operator(): got exception: { error: { code: 400這類錯(cuò)誤十有八九是這一層的連接配置出了問(wèn)題比如URL不對(duì)、模型名稱不匹配或者API密鑰無(wú)效。2.2 核心運(yùn)行時(shí)層智能體、技能與記憶這一層定義了OpenClaw如何工作。智能體Agent這是核心執(zhí)行單元。你可以創(chuàng)建多個(gè)具有不同角色、指令和能力的智能體。例如一個(gè)“客服助手”智能體和一個(gè)“文檔分析”智能體。每個(gè)智能體綁定一個(gè)特定的模型從基礎(chǔ)設(shè)施層配置的模型列表中選取并擁有自己的系統(tǒng)提示詞System Prompt來(lái)定義其行為準(zhǔn)則。技能Skill這是OpenClaw擴(kuò)展性的精髓。技能是一個(gè)個(gè)可插拔的功能模塊賦予智能體執(zhí)行具體任務(wù)的能力。例如web_search聯(lián)網(wǎng)搜索技能。code_interpreter代碼解釋與執(zhí)行技能。image_generation文生圖技能需配置額外畫圖模型如DALL-E或SD的API。社區(qū)技能處理Excel、發(fā)送郵件、操作數(shù)據(jù)庫(kù)等。 技能通過(guò)skill.json文件定義并通過(guò)安裝命令加載。智能體可以被配置允許使用哪些技能。記憶Memory這是實(shí)現(xiàn)連續(xù)對(duì)話和上下文關(guān)聯(lián)的關(guān)鍵。OpenClaw默認(rèn)會(huì)使用向量數(shù)據(jù)庫(kù)如Chroma在Docker部署中通常內(nèi)嵌來(lái)存儲(chǔ)和檢索對(duì)話歷史。用戶提到的“第二天就不知道昨天會(huì)話的內(nèi)容了”通常與記憶的持久化配置或會(huì)話Session管理有關(guān)。需要檢查數(shù)據(jù)庫(kù)是否被正確掛載Volume確保數(shù)據(jù)在容器重啟后不丟失。2.3 應(yīng)用連接層通道與消息流智能體最終需要與人或系統(tǒng)交互這就是通道Channel的作用。通道OpenClaw支持多種消息接入方式將外部平臺(tái)的用戶消息轉(zhuǎn)發(fā)給智能體并將智能體的回復(fù)傳回去。Web UI最直接的交互方式部署后通過(guò)瀏覽器訪問(wèn)一個(gè)本地網(wǎng)頁(yè)直接與智能體聊天。飛書Lark、微信、Slack、Discord等通過(guò)配置相應(yīng)的機(jī)器人Bot來(lái)實(shí)現(xiàn)。這需要你在對(duì)應(yīng)平臺(tái)申請(qǐng)機(jī)器人獲取App ID、Secret、Token等信息并在OpenClaw的通道配置中填寫。這是將智能體投入實(shí)際生產(chǎn)環(huán)境如客服的關(guān)鍵一步。消息流用戶消息通過(guò)通道進(jìn)入 - 路由到指定的智能體 - 智能體根據(jù)自身指令、可用技能和記憶歷史調(diào)用模型生成思考與行動(dòng) - 執(zhí)行技能如果需要- 生成最終回復(fù) - 通過(guò)通道返回給用戶。理解了這個(gè)三層架構(gòu)你就會(huì)明白部署OpenClaw本質(zhì)上就是1) 準(zhǔn)備好模型服務(wù)Ollama或API2) 通過(guò)Docker拉起OpenClaw核心服務(wù)并正確配置連接3) 在Web UI中創(chuàng)建智能體、配置技能4) 可選地配置外部通道如飛書進(jìn)行集成。3. 從零開始手把手部署OpenClaw全流程理論清晰后我們進(jìn)入實(shí)戰(zhàn)環(huán)節(jié)。我將以最常見的“Ubuntu服務(wù)器 Docker Compose Ollama本地模型”這一組合為例展示完整的部署流程。這個(gè)方案兼顧了性能、可控性和隱私性。3.1 環(huán)境準(zhǔn)備與前置條件假設(shè)你有一臺(tái)安裝了Ubuntu 20.04/22.04 LTS的服務(wù)器或虛擬機(jī)并擁有sudo權(quán)限。安裝Docker與Docker Compose如果系統(tǒng)沒(méi)有請(qǐng)先安裝。# 更新軟件包索引 sudo apt-get update # 安裝依賴 sudo apt-get install ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密鑰 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 設(shè)置倉(cāng)庫(kù) echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安裝Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 驗(yàn)證安裝 sudo docker --version sudo docker compose version安裝并配置Ollama我們將Ollama也通過(guò)Docker運(yùn)行便于管理。# 拉取Ollama官方鏡像 sudo docker pull ollama/ollama # 創(chuàng)建并運(yùn)行Ollama容器將模型數(shù)據(jù)持久化到本地目錄 sudo docker run -d -v /home/$(whoami)/.ollama:/root/.ollama -p 11434:11434 --name ollama --restart always ollama/ollama # 等待幾秒后測(cè)試Ollama是否運(yùn)行 curl http://localhost:11434/api/tags如果看到返回{models:[]}空列表因?yàn)檫€沒(méi)拉取模型說(shuō)明Ollama服務(wù)已就緒。3.2 獲取與配置OpenClaw獲取OpenClaw部署文件通常項(xiàng)目會(huì)提供docker-compose.yml和環(huán)境變量文件.env.example。# 創(chuàng)建一個(gè)工作目錄 mkdir ~/openclaw cd ~/openclaw # 假設(shè)從官方倉(cāng)庫(kù)獲取請(qǐng)以實(shí)際項(xiàng)目地址為準(zhǔn)這里僅為示例流程 # 你可能需要git clone或者直接下載compose文件。 # 這里我們手動(dòng)創(chuàng)建一個(gè)典型的docker-compose.yml示例 cat docker-compose.yml EOF version: 3.8 services: openclaw: image: crestodian/openclaw:latest # 請(qǐng)?zhí)鎿Q為正確的鏡像名 container_name: openclaw restart: unless-stopped ports: - 3000:3000 # Web UI 端口 environment: - OLLAMA_BASE_URLhttp://host.docker.internal:11434 # 關(guān)鍵Mac/Windows Docker Desktop用這個(gè) # - OLLAMA_BASE_URLhttp://172.17.0.1:11434 # Linux下宿主機(jī)在Docker網(wǎng)橋的典型IP - DEFAULT_MODELllama3.2:1b # 默認(rèn)使用的模型名稱必須與Ollama中拉取的名稱一致 - OPENAI_API_KEYsk-xxx # 如果使用OpenAI兼容API在此填寫 - OPENAI_BASE_URLhttps://api.openai.com/v1 # 如果使用OpenAI兼容API在此填寫 # 數(shù)據(jù)庫(kù)等其它環(huán)境變量... volumes: - ./data:/app/data # 持久化數(shù)據(jù)包括記憶、配置 depends_on: # - db # 如果有獨(dú)立數(shù)據(jù)庫(kù)服務(wù) - ollama # 聲明依賴Ollama服務(wù) networks: - openclaw-net # 如果Ollama也在這里編排可以取消注釋。但我們之前已經(jīng)單獨(dú)運(yùn)行了。 # ollama: # image: ollama/ollama # container_name: ollama # restart: unless-stopped # ports: # - 11434:11434 # volumes: # - /home/$(whoami)/.ollama:/root/.ollama # networks: # - openclaw-net networks: openclaw-net: driver: bridge EOF重要提示上面的docker-compose.yml是一個(gè)簡(jiǎn)化示例。你必須使用OpenClaw官方或社區(qū)維護(hù)的真實(shí)、最新的docker-compose.yml文件。鏡像名crestodian/openclaw:latest僅為示意請(qǐng)根據(jù)項(xiàng)目文檔替換。關(guān)鍵點(diǎn)在于OLLAMA_BASE_URL環(huán)境變量。在Linux服務(wù)器上Docker容器通常無(wú)法通過(guò)host.docker.internal訪問(wèn)宿主機(jī)需要改為宿主機(jī)的實(shí)際IP如172.17.0.1可通過(guò)ip addr show docker0查看或使用network_mode: host不推薦有安全風(fēng)險(xiǎn)。配置關(guān)鍵環(huán)境變量創(chuàng)建.env文件來(lái)管理配置。cp .env.example .env # 如果項(xiàng)目提供了示例文件 # 編輯 .env 文件至少修改以下關(guān)鍵項(xiàng) nano .env在.env文件中你需要關(guān)注OLLAMA_BASE_URLhttp://宿主機(jī)IP:11434Linux環(huán)境DEFAULT_MODEL你打算用的模型名如llama3.2:1b數(shù)據(jù)庫(kù)連接字符串如果使用外部數(shù)據(jù)庫(kù)。各種API密鑰如用于聯(lián)網(wǎng)搜索、畫圖等。3.3 啟動(dòng)服務(wù)與初始化在Ollama中拉取模型在宿主機(jī)上執(zhí)行因?yàn)镺llama容器已經(jīng)映射了11434端口到宿主機(jī)。# 拉取一個(gè)較小的模型進(jìn)行測(cè)試?yán)?Llama 3.2 1B curl -X POST http://localhost:11434/api/pull -d {name: llama3.2:1b} # 或者使用ollama命令行如果宿主機(jī)安裝了ollama二進(jìn)制 # ollama pull llama3.2:1b等待模型下載完成。你可以通過(guò)curl http://localhost:11434/api/tags查看已拉取的模型列表。啟動(dòng)OpenClaw服務(wù)cd ~/openclaw sudo docker compose up -d-d參數(shù)表示后臺(tái)運(yùn)行。使用sudo docker compose logs -f openclaw可以實(shí)時(shí)查看啟動(dòng)日志排查錯(cuò)誤。驗(yàn)證部署等待幾分鐘后在瀏覽器中訪問(wèn)http://你的服務(wù)器IP:3000。如果看到OpenClaw的Web UI登錄或初始化界面說(shuō)明核心服務(wù)啟動(dòng)成功。3.4 基礎(chǔ)配置創(chuàng)建第一個(gè)智能體通過(guò)Web UI通常首次訪問(wèn)需要設(shè)置管理員賬號(hào)后你可以開始配置模型管理在設(shè)置中檢查“模型提供商”是否已經(jīng)列出了你在.env中配置的Ollama服務(wù)以及可用的模型如llama3.2:1b。如果列表為空說(shuō)明OLLAMA_BASE_URL配置有誤需要檢查。創(chuàng)建智能體點(diǎn)擊“創(chuàng)建智能體”。輸入名稱如“我的助手”。在“模型”下拉框中選擇剛才看到的llama3.2:1b。在“系統(tǒng)提示詞”中定義它的角色和能力例如“你是一個(gè)有幫助的AI助手請(qǐng)用中文簡(jiǎn)潔、清晰地回答用戶的問(wèn)題?！北４妗y(cè)試對(duì)話在聊天界面選擇你創(chuàng)建的智能體發(fā)送一條消息如“你好”。如果收到合理的回復(fù)恭喜你最基礎(chǔ)的本地AI智能體已經(jīng)跑通了4. 核心功能進(jìn)階配置與使用技巧基礎(chǔ)部署成功后OpenClaw的真正威力在于其技能系統(tǒng)和外部集成。下面我們深入幾個(gè)最受關(guān)注的高級(jí)功能。4.1 技能Skill的安裝與使用技能是擴(kuò)展智能體能力的法寶。以安裝“聯(lián)網(wǎng)搜索”技能為例尋找技能OpenClaw的技能通常以Git倉(cāng)庫(kù)或壓縮包的形式存在。你需要在項(xiàng)目Wiki、文檔或社區(qū)如GitHub、Discord中查找技能的安裝方式。假設(shè)一個(gè)技能倉(cāng)庫(kù)地址是https://github.com/xxx/openclaw-web-search-skill。安裝技能通常有兩種方式通過(guò)Web UI如果支持在技能市場(chǎng)或管理頁(yè)面直接點(diǎn)擊安裝。通過(guò)命令行更通用你需要進(jìn)入OpenClaw的容器內(nèi)部執(zhí)行安裝命令。# 進(jìn)入openclaw容器 sudo docker exec -it openclaw /bin/bash # 在容器內(nèi)部使用項(xiàng)目提供的安裝工具或直接git clone到技能目錄 # 例如假設(shè)項(xiàng)目要求使用 claw 命令行工具 claw skill install https://github.com/xxx/openclaw-web-search-skill # 或者手動(dòng)操作 cd /app/skills # 假設(shè)技能目錄在此 git clone https://github.com/xxx/openclaw-web-search-skill # 然后可能需要安裝Python依賴 cd openclaw-web-search-skill pip install -r requirements.txt注意安裝技能前務(wù)必閱讀技能的README它通常會(huì)要求你配置API密鑰如SerpAPI或SearXNG的密鑰到OpenClaw的環(huán)境變量或配置文件中。安裝后需要在Web UI中編輯你的智能體在“可用技能”列表里勾選新安裝的技能。使用技能當(dāng)你問(wèn)智能體“今天北京天氣怎么樣”時(shí)如果它啟用了聯(lián)網(wǎng)搜索技能它可能會(huì)先調(diào)用搜索技能獲取實(shí)時(shí)信息再組織答案回復(fù)你。你可以在對(duì)話中觀察它的“思考過(guò)程”如果UI支持看它是否觸發(fā)了技能。4.2 接入飛書Lark實(shí)戰(zhàn)將OpenClaw接入飛書可以讓你的智能體在辦公協(xié)作場(chǎng)景中直接使用。在飛書開放平臺(tái)創(chuàng)建應(yīng)用登錄 飛書開放平臺(tái) 創(chuàng)建企業(yè)自建應(yīng)用。記錄下App ID和App Secret。在“事件訂閱”中設(shè)置“請(qǐng)求地址URL”為https://你的公網(wǎng)域名或IP:端口/feishu/events端口通常是3000但取決于你映射的端口且必須有公網(wǎng)IP或域名飛書才能回調(diào)。這對(duì)于本地測(cè)試是個(gè)挑戰(zhàn)可以考慮使用內(nèi)網(wǎng)穿透工具如ngrok、frp將本地3000端口暴露到一個(gè)公網(wǎng)地址。在“事件訂閱”中訂閱“接收消息”等所需權(quán)限。在“權(quán)限管理”中為應(yīng)用開通“獲取用戶發(fā)給機(jī)器人的單聊消息”、“獲取用戶在群聊中機(jī)器人的消息”等權(quán)限。發(fā)布版本并確保企業(yè)管理員審核通過(guò)。在OpenClaw中配置飛書通道在OpenClaw的Web UI中找到“通道”或“集成”設(shè)置。添加“飛書”通道。填寫從開放平臺(tái)獲取的App ID和App Secret。填寫“加密密鑰”在開放平臺(tái)“事件訂閱”頁(yè)面和“驗(yàn)證令牌”在開放平臺(tái)“安全設(shè)置”頁(yè)面。保存配置。OpenClaw會(huì)驗(yàn)證這些信息。測(cè)試與交互在飛書開放平臺(tái)將應(yīng)用添加到測(cè)試企業(yè)。在飛書聊天中找到該機(jī)器人發(fā)送消息。如果配置正確消息會(huì)轉(zhuǎn)發(fā)到你的OpenClaw智能體并回復(fù)到飛書。4.3 配置多模型與模型切換OpenClaw支持同時(shí)連接多個(gè)模型后端。配置多個(gè)模型提供商在.env或環(huán)境變量中你可以配置多個(gè)模型端點(diǎn)。例如同時(shí)使用本地Ollama和一個(gè)云端API。# Ollama 本地模型 OLLAMA_BASE_URLhttp://172.17.0.1:11434 # DeepSeek 云端API (示例) DEEPSEEK_API_KEYsk-xxx DEEPSEEK_BASE_URLhttps://api.deepseek.com在OpenClaw的模型管理頁(yè)面正確配置后你應(yīng)該能看到來(lái)自O(shè)llama和DeepSeek的模型列表。為不同智能體分配不同模型創(chuàng)建智能體時(shí)在模型選擇下拉框中你可以選擇任意一個(gè)已配置的模型。例如一個(gè)需要復(fù)雜推理的“代碼助手”智能體可以使用更強(qiáng)的云端模型如DeepSeek Coder而一個(gè)簡(jiǎn)單的“閑聊機(jī)器人”則使用本地的輕量模型以節(jié)省成本。5. 常見問(wèn)題排查與運(yùn)維心得在實(shí)際部署和使用中你幾乎一定會(huì)遇到各種問(wèn)題。以下是我踩過(guò)坑后總結(jié)的常見問(wèn)題速查表。問(wèn)題現(xiàn)象可能原因排查步驟與解決方案啟動(dòng)失敗日志報(bào)錯(cuò)數(shù)據(jù)庫(kù)連接問(wèn)題數(shù)據(jù)庫(kù)服務(wù)未啟動(dòng)或連接配置錯(cuò)誤。1. 檢查docker-compose.yml中數(shù)據(jù)庫(kù)服務(wù)定義。2. 檢查.env中的數(shù)據(jù)庫(kù)連接字符串主機(jī)名、端口、用戶名、密碼、數(shù)據(jù)庫(kù)名。3. 查看數(shù)據(jù)庫(kù)容器日志docker compose logs db。Web UI能打開但創(chuàng)建/對(duì)話時(shí)提示模型錯(cuò)誤llamap svr operator(): got exception: 400OpenClaw無(wú)法連接到大模型服務(wù)或模型名稱不對(duì)。1.檢查模型服務(wù)是否運(yùn)行curl http://宿主機(jī)IP:11434/api/tags(Ollama) 或測(cè)試API端點(diǎn)。2.檢查環(huán)境變量確認(rèn)OLLAMA_BASE_URL或OPENAI_BASE_URL在容器內(nèi)可訪問(wèn)。在容器內(nèi)執(zhí)行curl ${OLLAMA_BASE_URL}/api/tags。3.檢查模型名稱確認(rèn)DEFAULT_MODEL或智能體選擇的模型名與模型服務(wù)中的完全一致大小寫敏感。4.檢查網(wǎng)絡(luò)確保OpenClaw容器和Ollama容器在同一個(gè)Docker網(wǎng)絡(luò)或宿主機(jī)防火墻放行了相關(guān)端口。智能體無(wú)法使用已安裝的技能技能未正確啟用或配置缺失。1. 在智能體編輯頁(yè)面確認(rèn)已勾選該技能。2. 檢查技能所需的API密鑰等環(huán)境變量是否已在OpenClaw中配置。3. 查看OpenClaw應(yīng)用日志看技能加載時(shí)是否有報(bào)錯(cuò)docker compose logs openclaw | grep -i skill。4. 進(jìn)入容器檢查技能目錄/app/skills下是否有對(duì)應(yīng)的技能文件夾且結(jié)構(gòu)完整。飛書/微信機(jī)器人收不到回復(fù)或無(wú)法驗(yàn)證網(wǎng)絡(luò)不通或配置信息錯(cuò)誤。1.公網(wǎng)可達(dá)性確保OpenClaw的回調(diào)地址如https://your-domain.com/feishu/events能從公網(wǎng)訪問(wèn)。使用curl或在線工具測(cè)試。2.配置信息逐字核對(duì)飛書開放平臺(tái)和OpenClaw中填寫的App ID,App Secret,Encrypt Key,Verification Token。一個(gè)字符都不能錯(cuò)。3.日志排查查看OpenClaw日志看是否收到飛書的回調(diào)請(qǐng)求以及處理過(guò)程中是否有錯(cuò)誤。對(duì)話沒(méi)有記憶每次都是新會(huì)話記憶存儲(chǔ)未持久化或會(huì)話管理問(wèn)題。1.檢查數(shù)據(jù)持久化確認(rèn)docker-compose.yml中OpenClaw的volumes映射了數(shù)據(jù)目錄如./data:/app/data并且宿主機(jī)目錄有寫入權(quán)限。2.檢查向量數(shù)據(jù)庫(kù)如果使用Chroma等確認(rèn)其數(shù)據(jù)也持久化了。3.理解會(huì)話邊界Web UI中不同的瀏覽器標(biāo)簽或“新對(duì)話”按鈕可能會(huì)開啟新會(huì)話。飛書等通道中通常以聊天線程為單位管理會(huì)話。Docker容器內(nèi)無(wú)法訪問(wèn)宿主機(jī)的Ollama服務(wù)Docker網(wǎng)絡(luò)配置問(wèn)題host.docker.internal在Linux上無(wú)效。1.方案一推薦在docker-compose.yml中將OLLAMA_BASE_URL改為宿主機(jī)的Docker網(wǎng)橋IP如172.17.0.1需確保Ollama服務(wù)監(jiān)聽在0.0.0.0。2.方案二將Ollama服務(wù)也定義在同一個(gè)docker-compose.yml中讓它們?cè)谕粋€(gè)自定義網(wǎng)絡(luò)內(nèi)通信使用服務(wù)名作為主機(jī)名如http://ollama:11434。3.方案三簡(jiǎn)單粗暴適合開發(fā)使用network_mode: host讓容器共享宿主機(jī)網(wǎng)絡(luò)但會(huì)帶來(lái)安全和管理問(wèn)題。一些實(shí)操心得從輕量模型開始初次部署務(wù)必先用llama3.2:1b、qwen2.5:1.5b這類小參數(shù)模型測(cè)試流程。下載快資源消耗低能快速驗(yàn)證整個(gè)鏈路是否通暢。善用日志docker compose logs -f [service_name]是你最好的朋友。任何異常首先看日志。OpenClaw的日志通常會(huì)比較清晰地指出是配置錯(cuò)誤、連接超時(shí)還是內(nèi)部異常。環(huán)境變量管理所有敏感信息API密鑰、數(shù)據(jù)庫(kù)密碼和配置URL、模型名都通過(guò).env文件管理不要硬編碼在docker-compose.yml中。確保.env文件不被提交到版本控制系統(tǒng)已加入.gitignore。資源監(jiān)控運(yùn)行大模型尤其是7B以上參數(shù)時(shí)注意監(jiān)控服務(wù)器的CPU、內(nèi)存和GPU顯存使用情況。Ollama可以通過(guò)ollama ps查看模型加載狀態(tài)和資源占用。社區(qū)是寶庫(kù)遇到奇怪的問(wèn)題先去項(xiàng)目的GitHub Issues、Discord或相關(guān)論壇搜索你遇到的大部分問(wèn)題很可能已經(jīng)有人遇到并解決了。 OpenClaw本地AI智能體部署指南：從Docker到飛書集成的全流程實(shí)踐
1. 項(xiàng)目概述OpenClaw是什么以及它為何值得關(guān)注如果你最近在關(guān)注本地AI智能體Agent的部署與應(yīng)用那么“OpenClaw”這個(gè)名字大概率已經(jīng)出現(xiàn)在你的視野里了。它不是一個(gè)新的大語(yǔ)言模型而是一個(gè)開源的、旨在讓AI智能體“開箱即用”的框架平臺(tái)。簡(jiǎn)單來(lái)說(shuō)OpenClaw提供了一個(gè)環(huán)境讓你能夠輕松地將不同的AI模型比如Llama、Qwen、DeepSeek等接入進(jìn)來(lái)并賦予它們執(zhí)行具體任務(wù)的能力比如自動(dòng)回復(fù)消息、處理文檔、調(diào)用外部工具等。你可以把它想象成一個(gè)“AI智能體操作系統(tǒng)”或者一個(gè)功能強(qiáng)大的“AI智能體運(yùn)行沙盒”。我最初接觸OpenClaw是因?yàn)閰捑肓藶槊恳粋€(gè)簡(jiǎn)單的自動(dòng)化需求去寫冗長(zhǎng)的腳本或研究復(fù)雜的API調(diào)用。市面上很多AI應(yīng)用要么是云端服務(wù)存在數(shù)據(jù)隱私和成本的顧慮要么部署起來(lái)極其復(fù)雜對(duì)新手極不友好。OpenClaw的出現(xiàn)恰好瞄準(zhǔn)了這個(gè)痛點(diǎn)它試圖將智能體的部署、配置和管理變得像安裝一個(gè)普通軟件一樣簡(jiǎn)單。通過(guò)Docker容器化部署它極大地降低了環(huán)境配置的復(fù)雜度通過(guò)清晰的技能Skill機(jī)制它讓擴(kuò)展AI能力變得模塊化。無(wú)論是想搭建一個(gè)自動(dòng)處理電商客服的助手還是創(chuàng)建一個(gè)能幫你總結(jié)文檔、生成圖片的個(gè)人AI伙伴OpenClaw都提供了一個(gè)極具潛力的起點(diǎn)。從網(wǎng)絡(luò)上的討論熱度來(lái)看大家關(guān)心的核心問(wèn)題非常集中如何安裝部署Docker、Ubuntu、Windows、Mac、如何配置接入不同的大模型Ollama、API、如何連接實(shí)際應(yīng)用飛書、微信以及在使用中遇到的具體問(wèn)題如會(huì)話記憶丟失、技能安裝。這恰恰說(shuō)明了OpenClaw正處于從技術(shù)嘗鮮走向?qū)嶋H應(yīng)用的關(guān)鍵階段社區(qū)在積極摸索最佳實(shí)踐。本文將基于這些真實(shí)需求為你拆解OpenClaw的核心概念、手把手帶你完成部署配置并分享從零到一構(gòu)建一個(gè)可用智能體的全過(guò)程與避坑經(jīng)驗(yàn)。2. OpenClaw核心架構(gòu)與設(shè)計(jì)思路拆解在動(dòng)手安裝之前理解OpenClaw的基本設(shè)計(jì)哲學(xué)和核心組件能讓你在后續(xù)的配置和問(wèn)題排查中事半功倍。OpenClaw的架構(gòu)可以粗略地分為三層基礎(chǔ)設(shè)施層、核心運(yùn)行時(shí)層和應(yīng)用連接層。2.1 基礎(chǔ)設(shè)施層容器化與模型服務(wù)這是OpenClaw的基石主要解決“在哪里運(yùn)行”和“用什么大腦”的問(wèn)題。容器化部署Docker這是官方最推薦也是問(wèn)題最少的部署方式。OpenClaw本身及其依賴的環(huán)境Python、各種庫(kù)被打包成一個(gè)Docker鏡像。這樣做的好處是環(huán)境隔離你不需要在宿主機(jī)上折騰復(fù)雜的Python版本和庫(kù)依賴沖突。docker-compose.yml文件定義了服務(wù)OpenClaw本身、數(shù)據(jù)庫(kù)等的編排。幾乎所有“極速部署”教程都基于此。模型服務(wù)后端OpenClaw自身不包含大模型它需要一個(gè)“大腦”供應(yīng)商。目前主流支持兩種方式Ollama這是在本地運(yùn)行開源模型最流行的工具。你需要在同一臺(tái)機(jī)器或網(wǎng)絡(luò)內(nèi)部署Ollama并在其中拉取pull你想要的模型如llama3.2:1b,qwen2.5:7b。OpenClaw通過(guò)配置OLLAMA_BASE_URL通常是http://host.docker.internal:11434用于Mac/Windows的Docker Desktop或http://宿主機(jī)IP:11434用于Linux來(lái)連接Ollama服務(wù)。OpenAI兼容API如果你使用云端API服務(wù)如OpenAI、DeepSeek、智譜AI等或者部署了像vLLM、text-generation-webui這類提供兼容API接口的本地模型服務(wù)也可以通過(guò)配置相應(yīng)的API Base URL和Key來(lái)接入。注意很多新手遇到的openclaw llamap svr operator(): got exception: { error: { code: 400這類錯(cuò)誤十有八九是這一層的連接配置出了問(wèn)題比如URL不對(duì)、模型名稱不匹配或者API密鑰無(wú)效。2.2 核心運(yùn)行時(shí)層智能體、技能與記憶這一層定義了OpenClaw如何工作。智能體Agent這是核心執(zhí)行單元。你可以創(chuàng)建多個(gè)具有不同角色、指令和能力的智能體。例如一個(gè)“客服助手”智能體和一個(gè)“文檔分析”智能體。每個(gè)智能體綁定一個(gè)特定的模型從基礎(chǔ)設(shè)施層配置的模型列表中選取并擁有自己的系統(tǒng)提示詞System Prompt來(lái)定義其行為準(zhǔn)則。技能Skill這是OpenClaw擴(kuò)展性的精髓。技能是一個(gè)個(gè)可插拔的功能模塊賦予智能體執(zhí)行具體任務(wù)的能力。例如web_search聯(lián)網(wǎng)搜索技能。code_interpreter代碼解釋與執(zhí)行技能。image_generation文生圖技能需配置額外畫圖模型如DALL-E或SD的API。社區(qū)技能處理Excel、發(fā)送郵件、操作數(shù)據(jù)庫(kù)等。 技能通過(guò)skill.json文件定義并通過(guò)安裝命令加載。智能體可以被配置允許使用哪些技能。記憶Memory這是實(shí)現(xiàn)連續(xù)對(duì)話和上下文關(guān)聯(lián)的關(guān)鍵。OpenClaw默認(rèn)會(huì)使用向量數(shù)據(jù)庫(kù)如Chroma在Docker部署中通常內(nèi)嵌來(lái)存儲(chǔ)和檢索對(duì)話歷史。用戶提到的“第二天就不知道昨天會(huì)話的內(nèi)容了”通常與記憶的持久化配置或會(huì)話Session管理有關(guān)。需要檢查數(shù)據(jù)庫(kù)是否被正確掛載Volume確保數(shù)據(jù)在容器重啟后不丟失。2.3 應(yīng)用連接層通道與消息流智能體最終需要與人或系統(tǒng)交互這就是通道Channel的作用。通道OpenClaw支持多種消息接入方式將外部平臺(tái)的用戶消息轉(zhuǎn)發(fā)給智能體并將智能體的回復(fù)傳回去。Web UI最直接的交互方式部署后通過(guò)瀏覽器訪問(wèn)一個(gè)本地網(wǎng)頁(yè)直接與智能體聊天。飛書Lark、微信、Slack、Discord等通過(guò)配置相應(yīng)的機(jī)器人Bot來(lái)實(shí)現(xiàn)。這需要你在對(duì)應(yīng)平臺(tái)申請(qǐng)機(jī)器人獲取App ID、Secret、Token等信息并在OpenClaw的通道配置中填寫。這是將智能體投入實(shí)際生產(chǎn)環(huán)境如客服的關(guān)鍵一步。消息流用戶消息通過(guò)通道進(jìn)入 - 路由到指定的智能體 - 智能體根據(jù)自身指令、可用技能和記憶歷史調(diào)用模型生成思考與行動(dòng) - 執(zhí)行技能如果需要- 生成最終回復(fù) - 通過(guò)通道返回給用戶。理解了這個(gè)三層架構(gòu)你就會(huì)明白部署OpenClaw本質(zhì)上就是1) 準(zhǔn)備好模型服務(wù)Ollama或API2) 通過(guò)Docker拉起OpenClaw核心服務(wù)并正確配置連接3) 在Web UI中創(chuàng)建智能體、配置技能4) 可選地配置外部通道如飛書進(jìn)行集成。3. 從零開始手把手部署OpenClaw全流程理論清晰后我們進(jìn)入實(shí)戰(zhàn)環(huán)節(jié)。我將以最常見的“Ubuntu服務(wù)器 Docker Compose Ollama本地模型”這一組合為例展示完整的部署流程。這個(gè)方案兼顧了性能、可控性和隱私性。3.1 環(huán)境準(zhǔn)備與前置條件假設(shè)你有一臺(tái)安裝了Ubuntu 20.04/22.04 LTS的服務(wù)器或虛擬機(jī)并擁有sudo權(quán)限。安裝Docker與Docker Compose如果系統(tǒng)沒(méi)有請(qǐng)先安裝。# 更新軟件包索引 sudo apt-get update # 安裝依賴 sudo apt-get install ca-certificates curl gnupg lsb-release # 添加Docker官方GPG密鑰 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 設(shè)置倉(cāng)庫(kù) echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安裝Docker引擎 sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin # 驗(yàn)證安裝 sudo docker --version sudo docker compose version安裝并配置Ollama我們將Ollama也通過(guò)Docker運(yùn)行便于管理。# 拉取Ollama官方鏡像 sudo docker pull ollama/ollama # 創(chuàng)建并運(yùn)行Ollama容器將模型數(shù)據(jù)持久化到本地目錄 sudo docker run -d -v /home/$(whoami)/.ollama:/root/.ollama -p 11434:11434 --name ollama --restart always ollama/ollama # 等待幾秒后測(cè)試Ollama是否運(yùn)行 curl http://localhost:11434/api/tags如果看到返回{models:[]}空列表因?yàn)檫€沒(méi)拉取模型說(shuō)明Ollama服務(wù)已就緒。3.2 獲取與配置OpenClaw獲取OpenClaw部署文件通常項(xiàng)目會(huì)提供docker-compose.yml和環(huán)境變量文件.env.example。# 創(chuàng)建一個(gè)工作目錄 mkdir ~/openclaw cd ~/openclaw # 假設(shè)從官方倉(cāng)庫(kù)獲取請(qǐng)以實(shí)際項(xiàng)目地址為準(zhǔn)這里僅為示例流程 # 你可能需要git clone或者直接下載compose文件。 # 這里我們手動(dòng)創(chuàng)建一個(gè)典型的docker-compose.yml示例 cat docker-compose.yml EOF version: 3.8 services: openclaw: image: crestodian/openclaw:latest # 請(qǐng)?zhí)鎿Q為正確的鏡像名 container_name: openclaw restart: unless-stopped ports: - 3000:3000 # Web UI 端口 environment: - OLLAMA_BASE_URLhttp://host.docker.internal:11434 # 關(guān)鍵Mac/Windows Docker Desktop用這個(gè) # - OLLAMA_BASE_URLhttp://172.17.0.1:11434 # Linux下宿主機(jī)在Docker網(wǎng)橋的典型IP - DEFAULT_MODELllama3.2:1b # 默認(rèn)使用的模型名稱必須與Ollama中拉取的名稱一致 - OPENAI_API_KEYsk-xxx # 如果使用OpenAI兼容API在此填寫 - OPENAI_BASE_URLhttps://api.openai.com/v1 # 如果使用OpenAI兼容API在此填寫 # 數(shù)據(jù)庫(kù)等其它環(huán)境變量... volumes: - ./data:/app/data # 持久化數(shù)據(jù)包括記憶、配置 depends_on: # - db # 如果有獨(dú)立數(shù)據(jù)庫(kù)服務(wù) - ollama # 聲明依賴Ollama服務(wù) networks: - openclaw-net # 如果Ollama也在這里編排可以取消注釋。但我們之前已經(jīng)單獨(dú)運(yùn)行了。 # ollama: # image: ollama/ollama # container_name: ollama # restart: unless-stopped # ports: # - 11434:11434 # volumes: # - /home/$(whoami)/.ollama:/root/.ollama # networks: # - openclaw-net networks: openclaw-net: driver: bridge EOF重要提示上面的docker-compose.yml是一個(gè)簡(jiǎn)化示例。你必須使用OpenClaw官方或社區(qū)維護(hù)的真實(shí)、最新的docker-compose.yml文件。鏡像名crestodian/openclaw:latest僅為示意請(qǐng)根據(jù)項(xiàng)目文檔替換。關(guān)鍵點(diǎn)在于OLLAMA_BASE_URL環(huán)境變量。在Linux服務(wù)器上Docker容器通常無(wú)法通過(guò)host.docker.internal訪問(wèn)宿主機(jī)需要改為宿主機(jī)的實(shí)際IP如172.17.0.1可通過(guò)ip addr show docker0查看或使用network_mode: host不推薦有安全風(fēng)險(xiǎn)。配置關(guān)鍵環(huán)境變量創(chuàng)建.env文件來(lái)管理配置。cp .env.example .env # 如果項(xiàng)目提供了示例文件 # 編輯 .env 文件至少修改以下關(guān)鍵項(xiàng) nano .env在.env文件中你需要關(guān)注OLLAMA_BASE_URLhttp://宿主機(jī)IP:11434Linux環(huán)境DEFAULT_MODEL你打算用的模型名如llama3.2:1b數(shù)據(jù)庫(kù)連接字符串如果使用外部數(shù)據(jù)庫(kù)。各種API密鑰如用于聯(lián)網(wǎng)搜索、畫圖等。3.3 啟動(dòng)服務(wù)與初始化在Ollama中拉取模型在宿主機(jī)上執(zhí)行因?yàn)镺llama容器已經(jīng)映射了11434端口到宿主機(jī)。# 拉取一個(gè)較小的模型進(jìn)行測(cè)試?yán)?Llama 3.2 1B curl -X POST http://localhost:11434/api/pull -d {name: llama3.2:1b} # 或者使用ollama命令行如果宿主機(jī)安裝了ollama二進(jìn)制 # ollama pull llama3.2:1b等待模型下載完成。你可以通過(guò)curl http://localhost:11434/api/tags查看已拉取的模型列表。啟動(dòng)OpenClaw服務(wù)cd ~/openclaw sudo docker compose up -d-d參數(shù)表示后臺(tái)運(yùn)行。使用sudo docker compose logs -f openclaw可以實(shí)時(shí)查看啟動(dòng)日志排查錯(cuò)誤。驗(yàn)證部署等待幾分鐘后在瀏覽器中訪問(wèn)http://你的服務(wù)器IP:3000。如果看到OpenClaw的Web UI登錄或初始化界面說(shuō)明核心服務(wù)啟動(dòng)成功。3.4 基礎(chǔ)配置創(chuàng)建第一個(gè)智能體通過(guò)Web UI通常首次訪問(wèn)需要設(shè)置管理員賬號(hào)后你可以開始配置模型管理在設(shè)置中檢查“模型提供商”是否已經(jīng)列出了你在.env中配置的Ollama服務(wù)以及可用的模型如llama3.2:1b。如果列表為空說(shuō)明OLLAMA_BASE_URL配置有誤需要檢查。創(chuàng)建智能體點(diǎn)擊“創(chuàng)建智能體”。輸入名稱如“我的助手”。在“模型”下拉框中選擇剛才看到的llama3.2:1b。在“系統(tǒng)提示詞”中定義它的角色和能力例如“你是一個(gè)有幫助的AI助手請(qǐng)用中文簡(jiǎn)潔、清晰地回答用戶的問(wèn)題?！北４妗y(cè)試對(duì)話在聊天界面選擇你創(chuàng)建的智能體發(fā)送一條消息如“你好”。如果收到合理的回復(fù)恭喜你最基礎(chǔ)的本地AI智能體已經(jīng)跑通了4. 核心功能進(jìn)階配置與使用技巧基礎(chǔ)部署成功后OpenClaw的真正威力在于其技能系統(tǒng)和外部集成。下面我們深入幾個(gè)最受關(guān)注的高級(jí)功能。4.1 技能Skill的安裝與使用技能是擴(kuò)展智能體能力的法寶。以安裝“聯(lián)網(wǎng)搜索”技能為例尋找技能OpenClaw的技能通常以Git倉(cāng)庫(kù)或壓縮包的形式存在。你需要在項(xiàng)目Wiki、文檔或社區(qū)如GitHub、Discord中查找技能的安裝方式。假設(shè)一個(gè)技能倉(cāng)庫(kù)地址是https://github.com/xxx/openclaw-web-search-skill。安裝技能通常有兩種方式通過(guò)Web UI如果支持在技能市場(chǎng)或管理頁(yè)面直接點(diǎn)擊安裝。通過(guò)命令行更通用你需要進(jìn)入OpenClaw的容器內(nèi)部執(zhí)行安裝命令。# 進(jìn)入openclaw容器 sudo docker exec -it openclaw /bin/bash # 在容器內(nèi)部使用項(xiàng)目提供的安裝工具或直接git clone到技能目錄 # 例如假設(shè)項(xiàng)目要求使用 claw 命令行工具 claw skill install https://github.com/xxx/openclaw-web-search-skill # 或者手動(dòng)操作 cd /app/skills # 假設(shè)技能目錄在此 git clone https://github.com/xxx/openclaw-web-search-skill # 然后可能需要安裝Python依賴 cd openclaw-web-search-skill pip install -r requirements.txt注意安裝技能前務(wù)必閱讀技能的README它通常會(huì)要求你配置API密鑰如SerpAPI或SearXNG的密鑰到OpenClaw的環(huán)境變量或配置文件中。安裝后需要在Web UI中編輯你的智能體在“可用技能”列表里勾選新安裝的技能。使用技能當(dāng)你問(wèn)智能體“今天北京天氣怎么樣”時(shí)如果它啟用了聯(lián)網(wǎng)搜索技能它可能會(huì)先調(diào)用搜索技能獲取實(shí)時(shí)信息再組織答案回復(fù)你。你可以在對(duì)話中觀察它的“思考過(guò)程”如果UI支持看它是否觸發(fā)了技能。4.2 接入飛書Lark實(shí)戰(zhàn)將OpenClaw接入飛書可以讓你的智能體在辦公協(xié)作場(chǎng)景中直接使用。在飛書開放平臺(tái)創(chuàng)建應(yīng)用登錄 飛書開放平臺(tái) 創(chuàng)建企業(yè)自建應(yīng)用。記錄下App ID和App Secret。在“事件訂閱”中設(shè)置“請(qǐng)求地址URL”為https://你的公網(wǎng)域名或IP:端口/feishu/events端口通常是3000但取決于你映射的端口且必須有公網(wǎng)IP或域名飛書才能回調(diào)。這對(duì)于本地測(cè)試是個(gè)挑戰(zhàn)可以考慮使用內(nèi)網(wǎng)穿透工具如ngrok、frp將本地3000端口暴露到一個(gè)公網(wǎng)地址。在“事件訂閱”中訂閱“接收消息”等所需權(quán)限。在“權(quán)限管理”中為應(yīng)用開通“獲取用戶發(fā)給機(jī)器人的單聊消息”、“獲取用戶在群聊中機(jī)器人的消息”等權(quán)限。發(fā)布版本并確保企業(yè)管理員審核通過(guò)。在OpenClaw中配置飛書通道在OpenClaw的Web UI中找到“通道”或“集成”設(shè)置。添加“飛書”通道。填寫從開放平臺(tái)獲取的App ID和App Secret。填寫“加密密鑰”在開放平臺(tái)“事件訂閱”頁(yè)面和“驗(yàn)證令牌”在開放平臺(tái)“安全設(shè)置”頁(yè)面。保存配置。OpenClaw會(huì)驗(yàn)證這些信息。測(cè)試與交互在飛書開放平臺(tái)將應(yīng)用添加到測(cè)試企業(yè)。在飛書聊天中找到該機(jī)器人發(fā)送消息。如果配置正確消息會(huì)轉(zhuǎn)發(fā)到你的OpenClaw智能體并回復(fù)到飛書。4.3 配置多模型與模型切換OpenClaw支持同時(shí)連接多個(gè)模型后端。配置多個(gè)模型提供商在.env或環(huán)境變量中你可以配置多個(gè)模型端點(diǎn)。例如同時(shí)使用本地Ollama和一個(gè)云端API。# Ollama 本地模型 OLLAMA_BASE_URLhttp://172.17.0.1:11434 # DeepSeek 云端API (示例) DEEPSEEK_API_KEYsk-xxx DEEPSEEK_BASE_URLhttps://api.deepseek.com在OpenClaw的模型管理頁(yè)面正確配置后你應(yīng)該能看到來(lái)自O(shè)llama和DeepSeek的模型列表。為不同智能體分配不同模型創(chuàng)建智能體時(shí)在模型選擇下拉框中你可以選擇任意一個(gè)已配置的模型。例如一個(gè)需要復(fù)雜推理的“代碼助手”智能體可以使用更強(qiáng)的云端模型如DeepSeek Coder而一個(gè)簡(jiǎn)單的“閑聊機(jī)器人”則使用本地的輕量模型以節(jié)省成本。5. 常見問(wèn)題排查與運(yùn)維心得在實(shí)際部署和使用中你幾乎一定會(huì)遇到各種問(wèn)題。以下是我踩過(guò)坑后總結(jié)的常見問(wèn)題速查表。問(wèn)題現(xiàn)象可能原因排查步驟與解決方案啟動(dòng)失敗日志報(bào)錯(cuò)數(shù)據(jù)庫(kù)連接問(wèn)題數(shù)據(jù)庫(kù)服務(wù)未啟動(dòng)或連接配置錯(cuò)誤。1. 檢查docker-compose.yml中數(shù)據(jù)庫(kù)服務(wù)定義。2. 檢查.env中的數(shù)據(jù)庫(kù)連接字符串主機(jī)名、端口、用戶名、密碼、數(shù)據(jù)庫(kù)名。3. 查看數(shù)據(jù)庫(kù)容器日志docker compose logs db。Web UI能打開但創(chuàng)建/對(duì)話時(shí)提示模型錯(cuò)誤llamap svr operator(): got exception: 400OpenClaw無(wú)法連接到大模型服務(wù)或模型名稱不對(duì)。1.檢查模型服務(wù)是否運(yùn)行curl http://宿主機(jī)IP:11434/api/tags(Ollama) 或測(cè)試API端點(diǎn)。2.檢查環(huán)境變量確認(rèn)OLLAMA_BASE_URL或OPENAI_BASE_URL在容器內(nèi)可訪問(wèn)。在容器內(nèi)執(zhí)行curl ${OLLAMA_BASE_URL}/api/tags。3.檢查模型名稱確認(rèn)DEFAULT_MODEL或智能體選擇的模型名與模型服務(wù)中的完全一致大小寫敏感。4.檢查網(wǎng)絡(luò)確保OpenClaw容器和Ollama容器在同一個(gè)Docker網(wǎng)絡(luò)或宿主機(jī)防火墻放行了相關(guān)端口。智能體無(wú)法使用已安裝的技能技能未正確啟用或配置缺失。1. 在智能體編輯頁(yè)面確認(rèn)已勾選該技能。2. 檢查技能所需的API密鑰等環(huán)境變量是否已在OpenClaw中配置。3. 查看OpenClaw應(yīng)用日志看技能加載時(shí)是否有報(bào)錯(cuò)docker compose logs openclaw | grep -i skill。4. 進(jìn)入容器檢查技能目錄/app/skills下是否有對(duì)應(yīng)的技能文件夾且結(jié)構(gòu)完整。飛書/微信機(jī)器人收不到回復(fù)或無(wú)法驗(yàn)證網(wǎng)絡(luò)不通或配置信息錯(cuò)誤。1.公網(wǎng)可達(dá)性確保OpenClaw的回調(diào)地址如https://your-domain.com/feishu/events能從公網(wǎng)訪問(wèn)。使用curl或在線工具測(cè)試。2.配置信息逐字核對(duì)飛書開放平臺(tái)和OpenClaw中填寫的App ID,App Secret,Encrypt Key,Verification Token。一個(gè)字符都不能錯(cuò)。3.日志排查查看OpenClaw日志看是否收到飛書的回調(diào)請(qǐng)求以及處理過(guò)程中是否有錯(cuò)誤。對(duì)話沒(méi)有記憶每次都是新會(huì)話記憶存儲(chǔ)未持久化或會(huì)話管理問(wèn)題。1.檢查數(shù)據(jù)持久化確認(rèn)docker-compose.yml中OpenClaw的volumes映射了數(shù)據(jù)目錄如./data:/app/data并且宿主機(jī)目錄有寫入權(quán)限。2.檢查向量數(shù)據(jù)庫(kù)如果使用Chroma等確認(rèn)其數(shù)據(jù)也持久化了。3.理解會(huì)話邊界Web UI中不同的瀏覽器標(biāo)簽或“新對(duì)話”按鈕可能會(huì)開啟新會(huì)話。飛書等通道中通常以聊天線程為單位管理會(huì)話。Docker容器內(nèi)無(wú)法訪問(wèn)宿主機(jī)的Ollama服務(wù)Docker網(wǎng)絡(luò)配置問(wèn)題host.docker.internal在Linux上無(wú)效。1.方案一推薦在docker-compose.yml中將OLLAMA_BASE_URL改為宿主機(jī)的Docker網(wǎng)橋IP如172.17.0.1需確保Ollama服務(wù)監(jiān)聽在0.0.0.0。2.方案二將Ollama服務(wù)也定義在同一個(gè)docker-compose.yml中讓它們?cè)谕粋€(gè)自定義網(wǎng)絡(luò)內(nèi)通信使用服務(wù)名作為主機(jī)名如http://ollama:11434。3.方案三簡(jiǎn)單粗暴適合開發(fā)使用network_mode: host讓容器共享宿主機(jī)網(wǎng)絡(luò)但會(huì)帶來(lái)安全和管理問(wèn)題。一些實(shí)操心得從輕量模型開始初次部署務(wù)必先用llama3.2:1b、qwen2.5:1.5b這類小參數(shù)模型測(cè)試流程。下載快資源消耗低能快速驗(yàn)證整個(gè)鏈路是否通暢。善用日志docker compose logs -f [service_name]是你最好的朋友。任何異常首先看日志。OpenClaw的日志通常會(huì)比較清晰地指出是配置錯(cuò)誤、連接超時(shí)還是內(nèi)部異常。環(huán)境變量管理所有敏感信息API密鑰、數(shù)據(jù)庫(kù)密碼和配置URL、模型名都通過(guò).env文件管理不要硬編碼在docker-compose.yml中。確保.env文件不被提交到版本控制系統(tǒng)已加入.gitignore。資源監(jiān)控運(yùn)行大模型尤其是7B以上參數(shù)時(shí)注意監(jiān)控服務(wù)器的CPU、內(nèi)存和GPU顯存使用情況。Ollama可以通過(guò)ollama ps查看模型加載狀態(tài)和資源占用。社區(qū)是寶庫(kù)遇到奇怪的問(wèn)題先去項(xiàng)目的GitHub Issues、Discord或相關(guān)論壇搜索你遇到的大部分問(wèn)題很可能已經(jīng)有人遇到并解決了。