1. 项目概述为什么OpenClaw值得你花时间本地部署最近在AI圈子里OpenClaw这个名字出现的频率越来越高。你可能已经听说了它是一个开源的AI智能体框架简单来说它能让你的本地大语言模型比如通过Ollama部署的Llama、Qwen等拥有“手”和“脚”去执行一些具体的任务比如帮你操作电脑、分析网页、处理文件。这听起来是不是比单纯和AI聊天更有意思我之所以花大力气折腾它的本地部署核心原因就一个数据安全与完全可控。当你把AI智能体部署在自己的机器上所有的对话、你让它执行的操作、它访问的文件都只在你的本地环境里流转。这对于处理敏感信息、内部文档或者单纯就是不想把数据送到云端的朋友来说是刚需。另一个现实原因是很多云服务有调用限制或网络问题本地部署意味着7x24小时不间断的、稳定的服务能力。网上虽然有一些教程但要么步骤跳跃太大对新手不友好要么环境依赖没讲清楚跟着做一半就卡住。这篇内容我会结合自己从零开始在Ubuntu和macOS上的多次部署、踩坑、排错经历把整个过程掰开揉碎了讲。目标很明确让你能一次成功地把OpenClaw跑起来并且知道遇到常见问题时该怎么解决。我们会覆盖从基础环境准备、Docker部署、模型配置到接入飞书、处理典型报错的完整链路。2. 部署前的核心准备理清依赖与选型思路在动手敲任何命令之前理清思路比盲目操作更重要。OpenClaw的部署本质上是在搭建一个由多个组件协同工作的微服务环境。你需要理解这几个核心部分才能明白每一步在做什么。2.1 核心组件与它们的关系你可以把OpenClaw想象成一个“大脑”和“四肢”的组合体大脑LLM这是智能体的核心思考单元负责理解你的指令、规划步骤、生成回复。它通常是一个独立的大语言模型服务比如通过Ollama本地运行的模型Llama 3.2, Qwen2.5, DeepSeek等或者你也可以配置成使用云端API如OpenAI但本文聚焦本地。四肢Skill/Operator这是智能体的执行单元也就是所谓的“技能”。例如一个“读取文件”的技能、一个“点击浏览器”的技能。OpenClaw框架自带和社区提供了很多这样的技能。协调中心OpenClaw Server这是框架本身它接收你的请求比如从飞书机器人发来的消息调用“大脑”进行思考然后根据思考结果指挥对应的“四肢”去执行具体任务最后将结果整理好返回给你。对于本地部署最常见的架构就是Ollama提供大脑 Docker Compose快速拉起OpenClaw服务及其依赖。这也是本篇教程采用的方案因为它能最大程度地避免环境冲突实现一键部署。2.2 硬件与基础软件要求这不是一个轻量级应用请确保你的机器满足以下条件否则体验会非常糟糕CPU建议现代多核处理器Intel i5/Ryzen 5及以上。部分技能和模型推理会用到CPU。内存最低16GB强烈建议32GB或以上。大语言模型本身就很吃内存同时运行Ollama和OpenClaw服务内存不足是导致各种诡异失败的主要原因。存储至少预留50GB的可用空间。用于存放Docker镜像、模型文件一个7B参数的模型大约4-5GB、以及运行过程中产生的数据。操作系统LinuxUbuntu 20.04/22.04 CentOS 7/8等或 macOS建议使用Homebrew管理依赖是主要支持环境。Windows可以通过WSL2进行部署但本篇以Linux/macOS原生环境为主。网络需要能顺畅访问Docker Hub和GitHub以下载镜像和代码。如果身处网络环境特殊的地区请提前配置好可靠的网络连接。2.3 关键工具安装清单在开始部署OpenClaw之前你需要先确保以下工具已经正确安装Docker 与 Docker Compose这是容器化部署的基石。OpenClaw官方推荐使用Docker Compose来编排所有服务。Ubuntu安装命令示例# 安装Docker sudo apt-get update sudo apt-get install docker.io sudo systemctl start docker sudo systemctl enable docker # 将当前用户加入docker组避免每次用sudo sudo usermod -aG docker $USER # 需要重新登录生效 # 安装Docker Compose插件 sudo apt-get install docker-compose-plugin # 验证安装 docker compose versionmacOS用户可以通过Docker Desktop一键安装它包含了Docker和Compose。Git用于拉取OpenClaw的源代码仓库。# Ubuntu sudo apt-get install git # macOS (使用Homebrew) brew install gitOllama可选但推荐如果你想使用本地模型作为“大脑”这是最简单的方式。去Ollama官网下载对应系统的安装包或者用脚本安装。# Linux/macOS 一键安装脚本 curl -fsSL https://ollama.com/install.sh | sh # 启动Ollama服务 ollama serve # 拉取一个模型例如Llama 3.2 3B较小适合尝鲜 ollama pull llama3.2:3b注意安装Docker后务必执行usermod并重新登录终端否则会遇到权限不足导致docker命令需要sudo的问题这会在后续Compose文件中引发权限复杂的配置难题。3. 一步步详解使用Docker Compose部署OpenClaw这是最核心、最推荐的方式。官方提供了docker-compose.yml文件能帮你把OpenClaw服务、数据库PostgreSQL、缓存Redis等依赖一次性拉起来。3.1 获取部署文件与初始配置首先我们把代码仓库克隆到本地。# 找一个你喜欢的目录比如 ~/projects cd ~/projects git clone https://github.com/openclaw-ai/openclaw.git cd openclaw进入目录后你会看到很多文件。我们需要重点关注的是docker-compose.yml和.env.example。.env.example文件是环境变量的模板。我们需要复制一份并命名为.env然后根据我们的本地环境进行修改。cp .env.example .env现在用文本编辑器如nano,vim或 VSCode打开.env文件。下面我解释几个最关键的需要修改的配置项# 数据库配置一般用默认即可除非你本地已有冲突的PostgreSQL服务 POSTGRES_PASSWORDyour_strong_password_here # 务必改成一个强密码 # OpenClaw服务的关键配置 OPENCLAW_HOSThttp://localhost:3000 # 服务对外访问的地址本地调试通常是这个 OPENCLAW_SECRET_KEYyour_secret_key_here # 用于加密的密钥建议用长随机字符串 # 大模型配置 - 这是连接“大脑”的核心 # 方案A使用本地Ollama OPENCLAW_LLM_API_TYPEollama OPENCLAW_OLLAMA_BASE_URLhttp://host.docker.internal:11434 # 重点让Docker容器能访问宿主机的Ollama OPENCLAW_DEFAULT_MODELllama3.2:3b # 你通过Ollama拉取的模型名 # 方案B如果你要用OpenAI等云端API非本文重点仅作示例 # OPENCLAW_LLM_API_TYPEopenai # OPENCLAW_OPENAI_API_KEYsk-xxx # OPENCLAW_DEFAULT_MODELgpt-4o-mini关键解释OPENCLAW_OLLAMA_BASE_URL这里使用了host.docker.internal。这是一个特殊的DNS名称在Docker容器内部它指向宿主机的IP地址。这样运行在Docker容器里的OpenClaw服务才能访问到宿主机上运行的Ollama服务端口11434。在Linux上有时可能需要改用宿主机的实际IP如172.17.0.1但host.docker.internal在较新版本的Docker Desktop和Docker Engine中已被广泛支持。OPENCLAW_DEFAULT_MODEL这个模型名称必须和你在Ollama中拉取ollama pull的模型名称完全一致。你可以通过ollama list命令查看本地已有的模型。3.2 启动所有服务配置好.env文件后启动就变得非常简单。在openclaw项目根目录下执行docker compose up -d这个-d参数代表“后台运行”。命令执行后Docker会开始拉取PostgreSQL、Redis和OpenClaw的镜像并创建容器、配置网络最后启动它们。你可以用以下命令查看服务状态docker compose ps如果所有服务状态都是running那么恭喜你核心服务部署成功了。OpenClaw的Web界面通常运行在3000端口你可以在浏览器打开http://localhost:3000进行访问初始可能是一个管理界面或API文档。3.3 验证服务与初步交互部署完成不等于一切正常。我们需要进行连通性测试。首先确保Ollama服务正在运行且模型已加载。新开一个终端窗口测试一下# 测试Ollama服务是否响应 curl http://localhost:11434/api/generate -d {model: llama3.2:3b, prompt:Hello, stream: false}如果返回一段JSON里面有生成的文本说明Ollama正常。然后测试OpenClaw服务是否正常连接到了Ollama。这通常需要通过OpenClaw的API进行。你可以查阅启动后日志中的提示或者直接访问其健康检查端点# 查看OpenClaw容器的日志观察启动过程有无报错 docker compose logs -f openclaw在日志中你应该能看到类似Connected to LLM provider (ollama) successfully的信息。实操心得第一次启动时建议先不用-d参数直接运行docker compose up这样所有日志都会实时打印在终端上。一旦出现错误你能立刻看到红色的错误信息方便排查。确认启动无误后按CtrlC停止再用docker compose up -d后台启动。4. 核心配置详解如何让OpenClaw“学会”你的技能服务跑起来只是第一步让OpenClaw真正能为你干活关键在于配置尤其是模型和技能Skill的配置。4.1 多模型配置与管理你不可能只用一个模型。有些任务需要逻辑推理强的模型有些则需要代码能力强的。OpenClaw支持配置多个模型并在使用时指定。配置通常在OpenClaw的管理界面或配置文件中完成。如果你通过Web UI操作一般会有“模型管理”的页面你需要添加一个模型提供商Provider类型选择“Ollama”基础URL填写http://host.docker.internal:11434然后就可以添加多个从Ollama拉取的不同模型了。更直接的方式是修改部署时的环境变量或配置文件。在.env文件中我们设置了默认模型。但更灵活的做法是在OpenClaw的应用配置里进行管理。你需要找到OpenClaw的配置文件可能是config.yaml或通过环境变量注入添加一个模型列表# 假设的配置结构具体以OpenClaw最新版本文档为准 llm_providers: - name: local_ollama type: ollama base_url: http://host.docker.internal:11434 models: - name: llama3.2:3b display_name: Llama 3.2 (3B Fast) - name: qwen2.5:7b display_name: Qwen 2.5 (7B Balanced) - name: deepseek-coder:6.7b display_name: DeepSeek Coder (编程专用)这样在执行任务时你就可以根据需求选择不同的“大脑”。4.2 技能Skill的启用与配置技能是OpenClaw的“武器库”。默认安装可能只包含部分基础技能。你需要根据需求启用或安装额外技能。技能的管理一般有两种方式内置技能启用在OpenClaw的Web管理界面中通常有“技能中心”或“插件市场”之类的模块你可以浏览并启用已有的技能如“文件阅读器”、“网页浏览器”、“命令行执行”等。启用后可能需要配置一些权限比如允许访问哪些目录。安装自定义技能社区开发的技能可能需要手动安装。这通常涉及将技能代码放到特定的skills目录下并在配置文件中声明。具体步骤需要参考每个技能的README。一个关键技巧很多技能在执行时需要访问宿主机的资源比如读取/home/yourname/Documents下的文件。由于OpenClaw运行在Docker容器内它默认看不到宿主机的文件系统。解决方法是通过Docker的数据卷挂载。你需要修改docker-compose.yml文件在openclaw服务下添加volumes配置services: openclaw: # ... 其他配置 ... volumes: # 将宿主机的目录挂载到容器内 - /home/yourname/Documents:/app/data/documents:ro # :ro 表示只读 - /home/yourname/Downloads:/app/data/downloads # ... 其他配置 ...这样容器内的OpenClaw技能就能通过路径/app/data/documents访问到你宿主机的文件了。务必谨慎配置挂载的目录和权限ro只读是个好习惯避免安全风险。5. 实战集成将OpenClaw接入飞书机器人让OpenClaw在命令行或Web界面里工作还不够酷把它变成飞书群里的一个机器人助手才是提升日常效率的利器。下面是把OpenClaw服务配置为飞书机器人后端的完整过程。5.1 在飞书开放平台创建机器人登录 飞书开放平台 进入“开发者后台”。点击“创建企业自建应用”。给应用起个名字比如“我的AI助手”并上传图标。在应用功能栏启用“机器人”能力。在“权限管理”中为机器人添加必要的权限至少需要im:message发送与接收单聊、群组消息im:message.group_at_msg接收群聊中机器人的消息im:message.p2p_msg接收单聊消息 根据你需要的功能可能还要添加文件读写等权限。在“事件订阅”页面你会看到最重要的一个配置请求地址 URL。这就是飞书服务器把消息事件推送给你服务的地址。我们先记下这个位置等我们的服务有了公网地址再填。在“凭证与基础信息”页面找到App ID和App Secret复制保存好等下配置OpenClaw要用。5.2 配置OpenClaw的飞书适配器OpenClaw需要通过一个“适配器”来理解飞书的协议。这通常是一个社区提供的插件或Skill。你需要安装并配置它。假设有一个openclaw-feishu-adapter的组件。你可能需要将其添加到docker-compose.yml中作为一个独立服务或者作为OpenClaw的一个插件安装。更常见的做法是在OpenClaw的配置中启用飞书通道。这可能需要你设置以下环境变量在.env文件中添加# 飞书机器人配置 FEISHU_APP_ID你的App_ID FEISHU_APP_SECRET你的App_Secret FEISHU_ENCRYPT_KEY # 如果在事件订阅中配置了加密则需要 FEISHU_VERIFICATION_TOKEN # 同上 OPENCLAW_PUBLIC_URLhttps://your-public-domain.com # 重点你的OpenClaw服务公网可访问地址最关键的一步OPENCLAW_PUBLIC_URL。因为飞书的服务器需要能访问到你的OpenClaw服务来推送事件和验证URL。你在本地局域网飞书是访问不到的。5.3 使用内网穿透暴露本地服务为了解决公网访问问题我们需要一个内网穿透工具。ngrok和frp是常见选择。这里以 ngrok 为例注意ngrok免费版域名会变化仅适合测试。去 ngrok 官网注册获取你的Authtoken。在本地安装ngrok并配置token。启动穿透将本地的3000端口暴露到公网ngrok http 3000命令执行后ngrok会生成一个https://xxxxxx.ngrok-free.app这样的公网地址。这个就是你的OPENCLAW_PUBLIC_URL。5.4 完成飞书事件订阅配置回到飞书开放平台“事件订阅”页面。在“请求地址”里填写{你的OPENCLAW_PUBLIC_URL}/feishu/event具体路径取决于适配器要求可能是/webhook/feishu请以适配器文档为准。点击“保存”飞书会向这个地址发送一个带有verification token的GET请求进行验证。如果你的OpenClaw飞书适配器配置正确且服务正常运行验证会自动通过。在“事件订阅”下方你需要订阅“接收消息”等相关事件。最后在“版本管理与发布”中创建一个版本并申请发布。审核通过或企业自建应用直接通过后你就可以在飞书里搜索到你的机器人并把它拉进群聊了。避坑指南飞书事件订阅的验证失败90%的原因在于1. 公网地址OPENCLAW_PUBLIC_URL填写错误或带了多余的斜杠2. OpenClaw服务中飞书适配器的路由路径配置与飞书后台填写的路径不匹配3. 本地服务没有真正运行起来。务必通过curl {你的公网地址}/health先测试服务是否可从外网访问。6. 高频报错与问题排查手册即使按照教程一步步来也难免会遇到问题。这里我汇总了部署和运行OpenClaw时最常见的错误并提供排查思路和解决方案。6.1 Docker Compose启动失败端口冲突或权限问题现象运行docker compose up -d后某个服务如PostgreSQL状态一直是Exited (1)查看日志docker compose logs postgres显示端口被占用或权限错误。排查netstat -tulpn | grep :5432PostgreSQL默认端口检查端口是否被占用。检查docker-compose.yml中映射的宿主机端口如3000:3000是否已被其他程序使用。检查数据卷挂载的宿主机目录是否存在且Docker进程是否有权读写特别是用非root用户运行docker时。解决端口冲突修改docker-compose.yml中端口映射的前半部分宿主机端口例如将5432:5432改为5433:5432。权限问题确保挂载的目录存在mkdir -p并适当调整权限chmod或者更简单的方法是在docker-compose.yml中指定一个容器内用户user: 1000:1000需替换为你宿主机用户的UID和GID。6.2 OpenClaw连接Ollama失败Connection refused或Model not found现象OpenClaw日志中持续报错Failed to connect to Ollama at http://host.docker.internal:11434或Model ‘llama3.2:3b‘ not found。排查在宿主机上执行curl http://localhost:11434/api/tags看Ollama服务是否正常返回模型列表。进入OpenClaw的Docker容器内部测试docker compose exec openclaw curl http://host.docker.internal:11434/api/tags。如果这里失败说明容器内网络不通。检查.env文件中OPENCLAW_OLLAMA_BASE_URL和OPENCLAW_DEFAULT_MODEL是否配置正确。解决网络不通Linux常见在Linux上host.docker.internal可能不生效。尝试以下方法方法一使用宿主机的桥接网络IP。运行ip addr show docker0找到inet后面的IP通常是172.17.0.1将OPENCLAW_OLLAMA_BASE_URL改为http://172.17.0.1:11434。方法二在docker-compose.yml中将OpenClaw服务的网络模式改为network_mode: “host“不推荐有安全风险。方法三将Ollama也通过Docker运行并与OpenClaw放在同一个自定义Docker网络中这是最干净的方式。模型未找到确认模型名大小写完全一致。在宿主机执行ollama list核对名称并确保你已经在Ollama中拉取了该模型ollama pull 模型名。6.3 技能执行失败权限不足或路径错误现象机器人收到指令后返回错误提示技能执行失败日志显示Permission denied或No such file or directory。排查查看OpenClaw容器日志找到具体的错误信息。检查该技能所需的宿主机目录是否已通过volumes正确挂载到容器内。进入容器内部检查挂载点是否存在以及权限docker compose exec openclaw ls -la /app/data/。解决权限不足调整宿主机目录的权限或者修改docker-compose.yml中挂载卷的权限模式如:rw读写。更安全的方式是在Dockerfile或Compose文件中指定一个非root用户来运行应用。路径错误确保技能配置中使用的文件路径是容器内的路径即挂载后的路径而不是宿主机的原始路径。例如技能配置里应该写/app/data/documents/myfile.pdf而不是/home/yourname/Documents/myfile.pdf。6.4 飞书机器人无响应或验证失败现象飞书后台保存事件订阅URL时验证失败或者机器人被后毫无反应。排查验证失败首先确认你的公网URLngrok地址是https开头且可访问。用浏览器或curl直接访问{你的公网URL}/feishu/event看是否有响应可能是405错误这是正常的因为飞书用GET验证你的服务可能只处理POST。关键看网络请求是否通。无响应检查OpenClaw服务日志看是否收到了飞书的POST请求。如果没有说明事件订阅可能未成功如果有看是否在处理过程中报错如飞书App ID/Secret配置错误。检查飞书后台“权限管理”是否已添加并开通了所需权限。解决仔细核对飞书后台填写的“请求地址”与OpenClaw飞书适配器实际监听的路径是否完全一致包括末尾的斜杠。确保.env中的FEISHU_APP_ID和FEISHU_APP_SECRET与飞书后台的“凭证与基础信息”完全一致没有多余空格。查看OpenClaw飞书适配器的详细日志通常会有更具体的错误信息。7. 进阶维护与优化思路当你成功部署并运行起来后可能会考虑如何让它更稳定、更强大。这里分享几个进阶方向。7.1 使用Nginx反代与配置SSL长期使用ngrok免费版不是办法。如果你有云服务器和域名可以在云服务器上安装Docker和OpenClaw部署过程同上。使用Nginx作为反向代理服务器将域名如claw.yourdomain.com的请求转发到本地的localhost:3000。使用Let‘s Encrypt的 Certbot 工具为你的域名申请免费的SSL证书并在Nginx中配置HTTPS。这样你就有了一个固定的、安全的OPENCLAW_PUBLIC_URLhttps://claw.yourdomain.com。7.2 模型管理与性能调优模型量化如果感觉模型运行慢或内存占用高可以在Ollama中使用量化版模型。例如ollama pull llama3.2:3b-instruct-q4_K_Mq4_K_M表示4位量化能显著减少内存占用并提升推理速度精度损失在可接受范围内。GPU加速如果你的机器有NVIDIA GPU确保安装了正确的NVIDIA驱动和CUDA工具包。然后在运行Ollama时它会自动尝试使用GPU。你可以通过ollama run llama3.2:7b后观察任务管理器或nvidia-smi命令来确认GPU是否被调用。服务监控使用docker stats命令可以实时查看各个容器的CPU、内存占用。对于长期运行的服务可以考虑配置docker-compose.yml中的资源限制deploy.resources.limits和重启策略restart: unless-stopped。7.3 技能开发与自定义OpenClaw的魅力在于可扩展性。当你发现现有的技能不够用时可以尝试自己开发。一个最简单的技能通常包括一个Python类继承自基础的Skill类。实现execute方法在这里编写具体的任务逻辑比如调用一个外部API、处理一段数据。定义技能的描述description、所需参数parameters等元数据让LLM知道在什么情况下调用这个技能。将技能文件放到指定的skills目录并在配置中注册。社区是获取灵感和代码的最佳场所多逛逛GitHub上的OpenClaw相关项目。部署和调试OpenClaw的过程就像在组装一个乐高机器人。每一步的搭建、每一次的排错都会让你对AI智能体如何工作有更深刻的理解。从“跑起来”到“用得好”中间还有很长的路要走比如设计高效的提示词Prompt、组合复杂的技能工作流等。但无论如何拥有一个完全受控于自己、在本地安静运行的AI助手这种安全感和自由度是任何云端服务都无法替代的。希望这篇超详细的指南能帮你扫清入门路上的大多数障碍。如果在实际操作中遇到了本文未覆盖的新问题最好的方法是去查阅项目的官方GitHub Issues那里通常有来自开发者和社区用户最直接的解决方案。