养龙虾，本地部署OpenClaw

一、最终架构（先理解）

很多朋友一开始可能会被几个名词绕晕，其实整个系统捋清楚了就是三层结构：

OpenClaw (AI Agent)
│
│
OpenAI Compatible API
▼
Ollama (本地模型服务)
│
▼
Qwen2.5 / Qwen3 / Llama3

这里有几个关键点需要弄清楚：

OpenClaw → 这是核心的智能体框架，专门负责调度工具、编排和执行任务。

Ollama → 充当本地大模型的“服务管家”，提供标准化的API接口。

Qwen → 真正的“大脑”，是执行推理和生成内容的基础模型。

请务必记住一个核心原则：OpenClaw本身不负责加载模型，它必须通过API来调用模型服务。

二、系统环境准备

1 确认 Node 版本

OpenClaw对运行环境有硬性要求，Node版本必须不低于22。这是第一步的基础检查。

打开终端，输入命令检查：

node -v

理想的输出应该是：

v22.x.x

如果版本不符，别急，用nvm管理工具可以轻松切换：

nvm install 22
nvm use 22

2 安装 pnpm

为了获得更好的依赖管理体验，官方推荐使用pnpm。安装起来很简单：

npm install -g pnpm

完成后，同样验证一下：

pnpm -v

三、安装 OpenClaw

环境就绪后，就可以安装主角了。推荐使用pnpm进行全局安装：

pnpm add -g openclaw

当然，用npm也一样：

npm install -g openclaw

安装是否成功，一条命令就能验证：

openclaw --version

如果能正常输出版本号，恭喜你，安装这一步就稳了。

四、第一次初始化 OpenClaw

安装完成，接下来就是首次运行和配置。打开终端，执行：

openclaw onboard

你会看到一个交互式的初始化界面，开头通常会有一段关于数据处理的声明：

I understand this is personal-by-default...

直接选择：

Yes

Onboarding Mode

接下来会问你选择哪种配置模式。对于初次使用者，答案很明确：

QuickStart

理由很简单：这个模式会自动生成一套基础配置，让我们快速跑通流程。至于高级定制，完全可以等系统运行起来之后再调整。

Gateway

这里要选择网关类型。为了简单起见，我们选择本地网关：

Local gateway

它会默认使用一个本地地址和端口：

ws://127.0.0.1:18789

记住这个地址，这是后续OpenClaw智能体对外通信的入口。

Network Binding

网络绑定选项。初次部署，为了最大化安全，建议选择：

Loopback (127.0.0.1)

这意味着服务只允许本机访问，杜绝了任何来自外部网络的潜在风险，对于本地开发和测试来说，这是最稳妥的方案。

五、安装本地模型服务

现在，智能体框架准备好了，但还没有“大脑”。我们需要安装Ollama来管理本地大模型。

一条命令搞定安装：

curl -fsSL https://ollama.ai/install.sh | bash

安装完成后，别忘了验证：

ollama -v

六、下载 Qwen 本地模型

Ollama只是个空壳，我们得给它装上“大脑”。建议先从一个小尺寸模型开始，下载快，测试也方便。

下载7B参数的轻量版模型：

ollama pull qwen2.5:7b

如果你的设备内存比较紧张，可以试试更小的3B版本：

ollama pull qwen2.5:3b

下载完成后，查看一下本地已有哪些模型：

ollama list

如果看到类似下面的输出，就说明模型已经就位了：

NAME
qwen2.5:7b

七、测试本地模型

模型下载好了，先别急着整合，单独测试一下确保它能正常工作。

运行模型进行对话测试：

ollama run qwen2.5:7b

在出现的对话提示符后，输入简单的问候：

hello

如果模型能够正常回应一段问候语，说明模型本身的加载和推理功能是没问题的。

测试完毕，按Ctrl + C退出对话。

八、启动 Ollama API

模型测试通过，现在需要把它变成一项服务，让OpenClaw能够调用。启动Ollama的API服务端：

ollama serve

这个命令会启动服务，默认API地址是：

http://127.0.0.1:11434

如何验证服务已启动？打开另一个终端标签页，执行：

curl http://127.0.0.1:11434

如果返回Ollama is running这行字，那就万事俱备了。

九、配置 OpenClaw 使用 Ollama

现在，我们要告诉OpenClaw：“你的大脑在这里”。这需要通过修改配置文件来实现。

打开OpenClaw的配置文件：

nano ~/.openclaw/config.yaml

找到模型和代理配置部分，关键是把模型提供者指向我们刚启动的Ollama服务。一个可用的配置示例如下：

models:
  providers:
    ollama:
      baseUrl: http://127.0.0.1:11434/v1
agents:
  default:
    model:
      primary: ollama/qwen2.5:7b

编辑完成后，按CTRL + X，然后按Y确认保存并退出。

十、启动 OpenClaw Gateway

所有配置都已就绪，是时候启动整个系统的网关了。

运行启动命令：

openclaw gateway start

如果启动成功，终端会显示网关已经运行，并告诉你访问地址，比如：

Gateway started
ws://127.0.0.1:18789

十一、测试 OpenClaw

激动人心的时刻到了，测试整个链路是否打通。

方式1：命令行聊天
直接在终端里和你的智能体对话：

openclaw chat

输入一个测试问题，例如：

解释一下Redis

如果智能体能基于本地模型生成一段关于Redis的解释，那么恭喜，整个本地AI智能体系统搭建成功！

方式2：Web界面访问
你还可以在浏览器中打开网关地址：

http://127.0.0.1:18789

十二、常见问题（100%会遇到）

问题1 Node版本错误

错误提示：

Node version too low

解决方案：
这说明Node.js版本不符合要求。请使用nvm安装并使用22版本：

nvm install 22
nvm use 22

问题2 OpenClaw命令不存在

问题原因：
通常是全局安装路径没有正确添加到系统的PATH环境变量中。

解决方案：
首先，查找npm的全局安装路径：

npm config get prefix

然后将该路径下的`bin`目录添加到你的PATH中。如果嫌麻烦，一个更直接的方法是重新安装一次：

npm install -g openclaw

问题3 Gateway启动失败

问题原因：
大概率是默认端口18789已被其他进程占用。

解决方案：
先检查端口占用情况：

lsof -i :18789

找到占用端口的进程ID (PID)，然后终止它：

kill -9 PID

最后重新启动网关：

openclaw gateway start

问题4 Ollama连接失败

诊断方法：
测试Ollama的API服务是否正常响应：

curl http://127.0.0.1:11434

解决方案：
如果连接失败，很可能是ollama serve服务没有在运行。只需在终端重新启动该服务即可。

问题5 模型不存在

诊断方法：
检查Ollama本地是否真的下载了模型：

ollama list

解决方案：
如果列表为空，说明还没拉取模型。执行下载命令：

ollama pull qwen2.5:7b

问题6 AI回复特别慢

问题原因：
这是本地大模型推理的常态，尤其当硬件算力有限或模型较大时。

解决方案：
最有效的办法是换用参数更少、规模更小的模型，速度会有明显改善：

qwen2.5:3b

十三、推荐模型（Mac）

对于使用Mac，特别是苹果自研芯片（M系列）的朋友，模型选择有讲究。

通用推荐（平衡性能与能力）：

qwen2.5:7b

或者：

llama3:8b

如果你的Mac内存足够豪华（≥ 32GB），可以挑战一下能力更强的版本：

qwen2.5:14b

十四、进阶玩法（重点）

让OpenClaw连接上一个本地模型，这仅仅是开始。它真正强大的地方在于“Tools + Agent”的架构，能让AI不再只是聊天，而是真正帮你干活。

举个例子：你可以配置一个数据库工具，然后直接对AI说：“查一下今天的订单总量”。AI在理解你的意图后，会自动生成并可能执行（取决于配置）相应的SQL语句：

用户：查今天订单量
AI：SELECT count(*) FROM orders WHERE date=curdate();

完整的进阶架构可以想象成这样：

OpenClaw
│
├── MySQL Tool
├── WebSearch Tool
├── File Tool
└── Shell Tool
│
▼
本地大模型

通过为智能体配备各种工具，它能做的事情边界就被极大地扩展了，这才是智能体框架的威力所在。