镝不咸最近社区里“openclaw小龙虾”这个词出现的频率有点高，不少群里都在讨论怎么把它跑起来。我也花时间折腾了一番，从 Windows 到 Docker，从本地模型到接入 IM，踩了不少坑。这篇东西我不打算讲太多虚的，就围绕“10分钟跑通部署”这个目标，把整个流程、关键配置、常见报错和后续玩法都掰开揉碎讲清楚。不管你是第一次接触本地大模型应用部署，还是已经玩过 Dify、AnythingLLM 想换换口味，这篇文章应该都能让你少走弯路。
1. 部署前必须先想清楚的三个问题：模型怎么选、Docker 还是原生、配置要多少
很多人拿到 openclaw 的第一反应就是找命令然后开跑，结果跑到一半发现要么模型连不上，要么内存爆了，再回来重新折腾。我在重复部署了几遍之后，反而觉得最关键的其实是动手前把三件事想明白：用哪类模型、用什么方式部署、机器能不能扛住。这三件事直接决定了后面所有步骤能不能顺利走完。
1.1 本地模型还是云端 API：两种路线的取舍
openclaw 本身是一个 AI Agent 框架，它不是一个自带模型的工具，它负责的是“调度模型、执行动作、管理对话流程”。所以你必须先决定模型从哪里来。目前常见的有两条路线：
第一条是走云端 API，比如 DeepSeek、MiniMax H3、豆包这类厂商提供的接口。优点是本地几乎不占资源，响应速度快，而且这些模型的中文能力通常比一些小参数本地模型强很多。缺点是你要注册账号、申请 API Key，有些服务需要充值，而且对话内容会经过第三方服务器，对数据隐私有要求的人会介意。
第二条是走本地模型，也就是通过 Ollama 跑 Qwen、Llama、DeepSeek 的蒸馏版等开源权重。这种方式很适合需要断网使用、对数据敏感的场景，也适合“玩”的心态——毕竟本地跑起来的成就感是真的不一样。但代价是显存要够大，7B 级别的量化模型至少需要 8GB 显存，14B 以上建议 16GB 起步，纯 CPU 推理不是不行，但体验会让人着急。
我的建议是：如果你只为了快速体验 openclaw 的调度能力，先用云端 API 跑通，之后再切换到本地模型。如果你本身就对隐私要求高，或者想在离线环境里跑，那就一步到位用 Ollama。
1.2 原生安装还是 Docker：按你的系统和使用习惯来
这个问题没有绝对答案，但我可以给你一个非常直接的判断逻辑：系统环境干净、依赖齐全，就选原生安装；系统环境复杂、或者你不想污染本机、或者你的系统是 Windows，就优先选 Docker。
从社区反馈来看，Windows 上跑原生安装遇到的环境问题最多，很多报错都跟 Node.js 版本、Python 版本冲突有关。而 Docker 方式把 openclaw 的运行时、Node 环境、Python 依赖全都封装在了容器里，宿主机上只要有一个 Docker 环境就行，本质上规避了大部分环境兼容问题。如果你用的是 Mac Mini 这类设备，用 Docker 部署也很方便，资源和进程隔离都做得不错。
当然，Docker 也不是完全没有学习成本。你要懂一点镜像、容器、端口映射的概念，但我会把最常用的命令写出来，你只需要复制粘贴。
1.3 硬件配置到底要多少
先给结论：openclaw 框架本身吃资源不大，真正吃资源的是模型。如果把模型排除在外，openclaw 本体在 Docker 容器里跑，大概也就占 300MB 左右的内存。但如果你同时要跑 7B 级别以上的量化模型，那内存和显存就要认真算一下了。
以 Ollama 跑 Qwen2.5 7B Q4 量化为例：
- 模型文件大约 4.7GB，加载进显存之后占 5-6GB；
- 推理过程中的 KV Cache 会额外占 1-2GB；
- 操作系统、浏览器（如果你用 Control UI 的话）、Docker 本身再加 4GB 左右。
所以一台 16GB 内存 + 8GB 显存的机器跑 7B 模型是够用的，但也没多少余量。如果你想跑更大的模型，建议把内存加到 32GB，并且优先考虑 NVIDIA 显卡，因为 CUDA 生态对 Ollama 的支持最成熟，AMD 和 Apple Silicon 虽然也能用，但有些加速参数要单独配。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备清单：基础工具安装、模型拉取、项目源码获取
这一步是整个部署过程中最枯燥但也最关键的。我见过太多人卡在环境准备阶段，不是因为不会，而是因为漏掉了某个小步骤。下面我按顺序列出来，每一条都建议你别跳过。
2.1 安装 Docker 和 Git 基础环境
无论你走 Docker 还是原生安装，Git 都是必须的，因为项目源码要用 Git 拉取。Docker 的话，Windows 用户我建议直接装 Docker Desktop，它自带 Docker Engine 和 docker-compose，装完以后在 PowerShell 里执行 docker --version 确认一下。
Mac 用户也一样，直接下载 Docker Desktop 安装。Linux 用户则取决于发行版，Ubuntu 系用 apt 装 docker.io 或者 docker-ce 都可以。装完后记得验证一下：
bash复制docker --version
docker compose version
如果你发现 docker compose 提示命令不存在，说明你装的是旧版 Docker 或者没有安装 compose 插件。新版 Docker Desktop 和 docker-ce 都自带 compose 插件，旧版的可以用 docker-compose 命令替代，但建议还是把 Docker 升级到新版本。
2.2 安装 Ollama 并拉取本地模型
如果你决定用本地模型，那 Ollama 是绕不开的。它是一个非常简单的大模型运行工具，安装包直接去官网下载，Windows、macOS、Linux 都有对应版本。装完之后在终端跑：
bash复制ollama --version
然后拉取一个适合中文场景的模型。我用得最多的是 Qwen 系列：
bash复制ollama pull qwen2.5:7b
这条命令会下载 4.7GB 左右的文件，具体时间取决于网速。拉到之后可以先试跑一下：
bash复制ollama run qwen2.5:7b
能正常回复就说明本地模型环境没问题。这里提醒一句：不要同时拉太多模型，硬盘空间和显存都是有限资源，先保证一个能用的模型，后续再按需增加。
2.3 获取 openclaw 项目源码和配置文件
openclaw 的开源项目地址，社区里叫它“小龙虾仓库”。用 Git 克隆到本地：
bash复制git clone https://github.com/openclaw/openclaw.git
这里如果网络访问 GitHub 比较慢，可以换镜像地址或者用代理，具体自己调整就好。克隆完之后，进入项目目录：
bash复制cd openclaw
你会发现目录下有一堆文件，其中最关键的是配置文件，一般叫 config.yaml 或 .env.example。先把示例配置复制成正式配置：
bash复制cp .env.example .env
然后你需要编辑这个 .env 文件，把模型相关的配置填进去。如果你用 Ollama 本地模型，关键配置如下：
bash复制MODEL_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
MODEL_NAME=qwen2.5:7b
如果你用云端 API，比如 DeepSeek，那就是这样：
bash复制MODEL_PROVIDER=deepseek
DEEPSEEK_API_KEY=你的密钥
MODEL_NAME=deepseek-chat
具体字段名可能会跟随项目版本更新而变化，但大致的逻辑就是这样——指定提供商、指定接口地址、指定模型名称。
3. 核心部署实战：从下载到启动，全程复制粘贴
环境准备好之后，真正的部署反而很简单。这一节我分两条路线来讲：Docker 方式适合绝大多数人，原生方式适合喜欢直接操作、对 Python/Node 生态很熟的人。
3.1 Docker Compose 方式启动 openclaw
进入项目源码目录后，查看一下有没有 docker-compose.yml 文件。如果有，那就是官方给的标准部署方式。我建议不要直接 docker compose up，先看一眼文件内容，确认里面端口映射和挂载目录，避免端口冲突。
确认无误后，直接运行：
bash复制docker compose up -d
-d 参数表示后台运行，这样终端不会一直被日志刷屏。首次启动会拉取镜像，openclaw 镜像本体包含 Node.js 运行时、Python 解释器以及项目依赖，体积通常在 1-2GB 左右，慢慢等它拉完就行。
启动完成后，查看容器状态：
bash复制docker compose ps
如果状态是 Up，说明容器起来了。接着看日志：
bash复制docker compose logs -f
日志里会出现一些初始化信息。当你看到类似 Control UI is running at http://localhost:3000 这样的输出时，恭喜你，核心服务已经跑起来了。
3.2 原生方式安装 openclaw 的步骤
如果你坚持用原生方式部署，流程大概是：先确认本机有 Node.js 18+ 和 Python 3.10+，然后安装项目依赖。一般来说 openclaw 项目会同时包含 Python 和 Node 两部分，后端核心是 Python，前端页面是 Node 构建的。所以要分别安装依赖：
bash复制pip install -r requirements.txt
npm install
这两个命令执行的时间会根据网络状况变化，如果遇到某个依赖安装失败，一般是因为网络问题导致下载超时。npm 可以用国内的镜像源加速：
bash复制npm config set registry https://registry.npmmirror.com
Python 包也可以切换国内 PyPI 源：
bash复制pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
依赖安装完成后，启动方式一般也在项目 README 里，常见的是：
bash复制python main.py
看到日志输出 Control UI 地址就算成功了。
3.3 验证部署是否成功的三个步骤
跑起来不代表真的成功，我每次部署完都习惯做三层验证：
第一步，检查 Control UI 是否能打开。浏览器访问 http://localhost:3000（端口根据你实际配置），能看到聊天界面说明前端正常。
第二步，发一条测试消息。在对话框里输入“你好”，如果模型能正常回复，说明 openclaw 到模型之间的链路是通的。
第三步，检查日志里有没有异常报错。当你发送消息时，后端日志会打印出调用的模型名称、耗时和 token 消耗，如果日志中出现红色 ERROR，哪怕页面看起来正常，我也建议先停下来排查，不然整个链路后面一定会出问题。
4. 老手也会踩的坑：常见报错排查思路和解决方案
部署最让人头疼的不是部署本身，而是报错。这节我整理了几个社区里出现频率最高的问题，每个问题都附上我自己的排查链路，方便你举一反三。
4.1 Control UI did not start：前端页面打不开
这个报错的字面意思是 Control UI 没有启动。出现这种问题的原因有很多，最常见的两个：一是 Node.js 进程挂了，二是端口被占用。
先看日志。Docker 方式直接 docker compose logs，原生安装就看终端输出。如果日志里出现 EADDRINUSE，说明端口被别的程序占用了。这时候我习惯用下面的命令查是谁占用了端口：
bash复制lsof -i :3000
找到进程 PID 之后，要么把它杀掉，要么改 openclaw 的端口配置。改端口的话，在 .env 文件里找到 CONTROL_UI_PORT 之类的字段，换一个没被占用的端口就行。
如果日志里没有端口报错，而是直接显示进程退出，那就要检查 Node.js 版本是否满足要求。openclaw 对 Node 的版本有硬性要求，版本太低或太高都可能启动失败。
4.2 Agent failed before reply unknown model
这个报错的意思是：Agent 在回复之前就失败了，原因是模型不存在。我遇到这个问题的场景是：配置文件里写了一个模型名，但 Ollama 里根本没有这个模型。
排查分三步走。第一步，确认 Ollama 里有什么模型：
bash复制ollama list
第二步，对比一下 openclaw 配置里的 MODEL_NAME 是否跟 ollama list 的输出完全一致。注意，有时候 Ollama 里的模型带 :latest 标签，你在配置里写 qwen2.5 和写 qwen2.5:latest 是有区别的。
第三步，如果你在 openclaw 配置里同时启用了多模型，比如给不同 Agent 指定不同模型，检查一下是不是某个 Agent 的配置里引用了不存在的模型名。特别是从示例配置复制过来的时候，很容易忘记把测试模型名改成自己实际拉取的模型。
4.3 Node Runtime Not Found：Windows 安装时的老大难
这类问题在社区里有个经典报错：oneclaw node runtime not found。我分析过这个报错，本质是 openclaw 在启动时找不到 Node.js 运行时。造成这个问题的原因通常是：你虽然装了 Node.js，但安装路径没有被系统环境变量 PATH 包含，或者 openclaw 在初始化时检测的是特定路径下的 Node。
排查方法是先在终端确认 Node 是否可用：
bash复制node -v
如果能输出版本号，说明 Node 没问题。接着检查 openclaw 配置里是否指定了 Node 路径参数，如果有，确认路径是否正确。还有一种情况是你装了多个 Node 版本，用了 nvm 这类版本管理工具，openclaw 检测到的不是你当前激活的版本。这时候最好的解决方案是：卸载 nvm，安装官方 Node.js LTS 版本，重新安装后再启动。
实际上这类环境路径问题在 Windows 上特别常见，这也是为什么我在前面一直推荐 Docker 部署。Docker 容器内部环境是固定的，Node 运行时被封装在镜像里，根本不依赖宿主机装了什么。如果你被困在这种报错里超过半小时，我真心建议换个思路，直接用 Docker。
4.4 接入微信或飞书失败：回调地址和鉴权参数
很多人跑通 Control UI 之后，下一步就是接入微信或飞书。但接 IM 平台跟本地跑 Web UI 完全是两回事。IM 平台要求你的服务有一个公网可访问的回调地址，而且微信公众平台的接口要求回调地址必须以 HTTP/HTTPS 形式暴露，本地 localhost 是没法用的。
我试过的方案有几种：一是用内网穿透工具，把本地端口暴露到公网，得到一个临时域名填到微信后台；二是直接用一台云服务器来跑 openclaw；三是在同一台服务器上部署反代。每种方案的稳定性和成本都不一样，你要按自己实际情况来选。
另外，微信接入的时候还容易遇到签名校验失败的问题。这里的排查思路是：确认服务端的 Token 跟微信公众平台里填写的 Token 完全一致，注意大小写和空格；确认回调地址能通过微信平台发的验证请求，这个请求是一个 GET 请求，带 signature、timestamp、nonce、echostr 参数，你的服务端需要对签名做校验并返回 echostr。
飞书那边的情况类似，主要是 App ID、App Secret 和事件订阅回调地址三个要素都要配好，任何一个不对都会导致收不到消息或验证失败。
5. 跑通之后的进阶玩法：多模型切换、Skill 扩展、Control UI 的实际使用感受
当你能跟小龙虾正常聊天之后，它对你的价值才刚开始体现。openclaw 真正好玩的地方在于它不是一个单纯的聊天机器人，而是一个带行动能力的 Agent 框架。下面我分享几个我觉得非常实用的进阶方向。
5.1 通过 Ollama 实现多模型热切换
openclaw 支持在同一个配置里定义多个模型，然后通过参数切换。比如我本地拉了 qwen2.5:7b 和 qwen2.5:14b，小模型用来处理日常闲聊和快速响应，大模型用来处理复杂推理任务。切换可以在配置里指定，也有支持在 Control UI 的模型选择器里直接切换的版本。
多模型的配置逻辑一般是这样的：在配置文件的模型列表里，按 provider 区分。比如：
yaml复制models:
- name: "local-fast"
provider: ollama
model: qwen2.5:7b
- name: "local-powerful"
provider: ollama
model: qwen2.5:14b
- name: "cloud-deepseek"
provider: deepseek
model: deepseek-chat
然后在 Agent 的配置里引用 local-fast 或 cloud-deepseek 作为默认模型。这么做的优势很明显：你可以在不同任务上使用不同模型，花更少的钱办更多的事。
有一点要注意：本地模型如果同时加载两个，显存占用是叠加的。我实测 8GB 显存跑两个 7B 模型会非常吃力，经常出现 OOM（显存溢出）。建议设备资源有限时只留一个本地模型常驻，另一个用云端 API 补充。
5.2 编写自定义 Skill 接入外部 API
openclaw 有一套 Skill 机制，可以让 Agent 调用外部工具的 API。比如你想让小龙虾能查天气、查新闻、做计算，都可以通过编写 Skill 来实现。Skill 本质上就是一组带描述和参数定义的 Python 函数，openclaw 在对话中根据语义自动判断要不要调用。
我举个简单例子，如果你要让 Agent 支持查询天气，你需要写一个这样的 Skill：
python复制from openclaw.skill import Skill
class WeatherQuery(Skill):
name = "weather_query"
description = "查询指定城市的当前天气"
parameters = [
{"name": "city", "type": "string", "required": True, "description": "城市名"}
]
def execute(self, city: str) -> str:
# 在这里调用天气 API
return "晴，25度"
写完之后把文件放到 skills/ 目录下，重启服务，Agent 就能在适当的时候自动调用它。
掌握这个机制之后，你就能把 openclaw 接到任何你想接的系统里，比如公司内部的知识库、订单系统、甚至是 Home Assistant 智能家居。这也是 openclaw 相比普通聊天机器人最核心的价值差异。
关于 API Key 的安全问题，我多说一句：Skill 里如果涉及外部 API，不要把密钥硬编码在代码里，应该放到 .env 环境变量文件里统一管理，避免泄漏。
5.3 Control UI 实际使用感受和替代方案
openclaw 自带的 Control UI 是一个基于 Web 的管理界面，初次使用感觉很清爽，会话管理、模型切换、Agent 状态查看都挺直观。但它本质是一个调试工具，如果你想把它嵌入到自己的业务系统里，官方也提供 HTTP API 接口，你完全可以自己写一个前端界面来对接。
从这个角度看，我建议你把 Control UI 当作部署验证工具，而不是长期使用入口。跑通之后，优先研究它的 API 文档，弄清接口的请求和响应格式，这样你才能根据自己的需求定制交互方式。
我在实际项目里会把 openclaw 作为后端服务，前面接一个企业微信机器人，或者接入到一个自定义的管理后台，这样做的好处是用户不需要知道 openclaw 的存在，他们只是通过你提供的入口使用背后的模型能力。
6. 部署完之后，我的一些个人体会
openclaw 这类工具的部署难度其实并不高，真正难的是你对整个链路有没有清晰的理解。我见过很多人部署失败，复盘下来都不是因为命令敲错了，而是因为不知道为什么敲这些命令。比如环境变量里的 MODEL_PROVIDER 决定了 openclaw 底层调用的是哪个 SDK，这个字段错了，其他全对都没有用。
所以我建议你在跟着本文部署的过程中，多花一点时间理解配置文件里每个字段的含义。等你把 openclaw 部署完全跑通之后，再回头去看那些 AI 应用框架，你会发现它们的思路都差不多——都是模型调度、工具调用、任务编排这几件事的组合。那时候你看别的新框架，基本一眼就能看懂它的设计。
最后再分享一个小技巧：如果你在部署过程中实在卡住了，先不用急着问别人“为什么不行”，而是先把日志从头到尾读一遍，很多报错信息本身就告诉了你解决方向。把日志里的关键词复制到搜索框里，通常能找到对应的 GitHub issue，十有八九下一秒你的问题就被解决了。