OpenClaw AI智能体框架部署指南：从零搭建本地大模型驱动的自动化工作流

福桃九分饱

329人浏览 · 2026-08-05 09:24:21

福桃九分饱 · 2026-08-05 09:24:21 发布

1. 项目概述：为什么OpenClaw值得你花时间折腾？

最近在AI智能体这个圈子里，OpenClaw这个名字出现的频率越来越高。如果你也像我一样，对让AI自动帮你处理工作流、回复消息、甚至管理任务感兴趣，那OpenClaw绝对是一个绕不开的工具。简单来说，它就是一个开源的AI智能体框架，你可以把它理解为一个“AI大脑”的操作系统。它能接入各种大语言模型，比如你本地跑的Ollama里的Llama、Qwen，或者云端API如OpenAI、DeepSeek，然后通过编写或配置“技能”，让这个AI大脑去自动执行一系列任务。

我最初接触OpenClaw，是因为厌倦了在不同客服平台、项目管理工具和社交软件之间反复横跳。想象一下，一个能7x24小时待命，能根据预设规则和上下文自动回复飞书/微信消息，能处理电商客服中80%的常见问题，甚至能根据对话内容自动生成图像的AI助手，这能解放多少生产力？OpenClaw的目标就是成为这样一个“超级副驾”。但说实话，它的官方文档对于新手，尤其是非开发背景的朋友来说，门槛不低。Docker、环境变量、模型配置、技能编写……一堆概念砸过来，很容易让人在第一步“安装部署”上就卡住，更别提后面接入飞书、微信，或者处理“第二天就忘记会话”这种实际使用中的坑了。

所以，这篇内容就是来解决这个“从入门到放弃”的第一步。我不会给你堆砌命令和配置文件，而是带你走一遍我亲自趟过的路，从零开始，用最详细、最白话的方式，在Ubuntu系统上完成OpenClaw的部署，并初步配置一个本地大模型。过程中你会遇到网络问题、端口冲突、模型加载失败等等，这些我都会一一拆解。我们的目标很简单：让你在半小时内，看到一个运行起来的OpenClaw Web界面，并能让它和你本地的大模型“说上话”。准备好了吗？我们开始。

2. 环境准备：给OpenClaw一个安稳的家

在开始安装任何软件之前，打好地基是关键。对于OpenClaw来说，这个地基就是你的服务器或本地电脑环境。我强烈推荐使用Ubuntu 22.04 LTS或24.04 LTS作为操作系统，这是社区支持最完善、坑最少的版本。如果你是Windows用户，建议使用WSL2（Windows Subsystem for Linux）安装一个Ubuntu发行版，这能避免大量原生Windows环境下的兼容性问题。Mac用户则相对省心，但部分依赖的安装命令需要稍作调整。

2.1 系统基础检查与更新

首先，我们需要确保系统是最新的，并且安装了必要的编译工具。打开你的终端，执行以下命令：

# 更新软件包列表
sudo apt update

# 升级所有已安装的软件包
sudo apt upgrade -y

# 安装一些基础工具，如curl、wget、git等
sudo apt install -y curl wget git build-essential software-properties-common

这一步看似简单，但很重要。 apt update 是刷新本地软件源信息， upgrade 是实际升级。有时候一些旧的库文件会导致后续安装失败，先升级能避免很多奇怪的问题。安装 build-essential 是为了后续可能需要的源码编译环节（虽然一键脚本会处理，但有备无患）。

2.2 Docker与Docker Compose的安装与验证

OpenClaw的官方推荐部署方式就是Docker，因为它能完美解决环境依赖和隔离的问题。我们将使用Docker官方提供的一键安装脚本，这是目前最可靠的方法。

# 下载并执行Docker安装脚本
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 将当前用户添加到docker组，避免每次都要sudo
sudo usermod -aG docker $USER

执行完 usermod 命令后， 你需要完全退出当前终端会话，并重新登录 ，或者直接重启系统，这个用户组变更才会生效。否则，后续执行 docker 命令还是会报权限错误。这是新手最容易忽略的一个点。

验证Docker是否安装成功：

docker --version

应该会输出类似 Docker version 24.0.7, build afdd53b 的信息。

接下来安装Docker Compose。它是一个用于定义和运行多容器Docker应用程序的工具，OpenClaw的部署会用到它。

# 下载Docker Compose的稳定版本（以v2.23.0为例，可查看官网获取最新版本号）
sudo curl -L "https://github.com/docker/compose/releases/download/v2.23.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 赋予执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version

应该输出类似 Docker Compose version v2.23.0 的信息。

注意：国内服务器访问GitHub可能很慢甚至超时。如果 curl 下载失败，你可以尝试多次执行，或者先通过能正常访问的机器下载好 docker-compose 文件，再上传到服务器对应目录。也可以考虑使用国内镜像源，但步骤会稍复杂一些。

2.3 端口与资源检查

OpenClaw默认会使用一些端口来提供服务，我们需要确保这些端口没有被其他程序占用。

3000端口 ：这是OpenClaw前端Web界面的默认端口。
7860端口 ：这是OpenClaw后端API服务的默认端口。

检查端口占用情况：

sudo lsof -i :3000
sudo lsof -i :7860

如果这两个命令没有返回任何信息，说明端口是空闲的。如果被占用（比如你之前安装过其他应用），你有两个选择：一是停止占用端口的服务；二是在后续的OpenClaw配置中修改默认端口。为了简化，我们假设端口都是空闲的。

另外，确保你的系统有足够的资源。运行OpenClaw本身消耗不大，但后续接入的大模型（尤其是本地模型）是内存和CPU消耗大户。建议至少准备4GB以上的空闲内存。可以使用 free -h 命令查看。

3. 核心部署：详解“一键脚本”的里里外外

环境准备好了，现在进入核心环节——部署OpenClaw。网上有很多所谓的“一键脚本”，但如果不明白脚本在做什么，一旦出错就会束手无策。我们来拆解一个典型、稳定的一键安装流程，并理解每一步的意义。

3.1 获取部署文件与目录准备

我们不推荐直接运行来源不明的脚本。最安全的方式是从OpenClaw的官方GitHub仓库获取部署文件。虽然它可能更新，但结构和逻辑是清晰的。

# 创建一个专门的工作目录
mkdir -p ~/openclaw-deploy
cd ~/openclaw-deploy

# 克隆官方仓库（如果网络不畅，可以尝试使用ghproxy等镜像）
git clone https://github.com/openclaw-ai/openclaw.git
cd openclaw

如果 git clone 速度太慢，你可以去GitHub仓库页面手动下载ZIP包并解压到 ~/openclaw-deploy 目录下。关键是要获取到里面的 docker-compose.yml 文件和 .env.example 文件。

3.2 配置文件解析与关键修改

OpenClaw通过环境变量文件（ .env ）来控制整个应用的行为。我们需要基于模板创建自己的配置文件。

# 复制环境变量模板
cp .env.example .env

现在，用你喜欢的文本编辑器（如 nano 或 vim ）打开 .env 文件。我们来看几个最关键的配置项，这些决定了OpenClaw能否成功启动并连接到大模型。

nano .env

后端服务配置 ( OPENCLAW_BACKEND_PORT ) ：
```
OPENCLAW_BACKEND_PORT=7860
```
这是后端API服务的端口，保持默认即可，除非7860端口被占用。
前端服务配置 ( OPENCLAW_FRONTEND_PORT ) ：
```
OPENCLAW_FRONTEND_PORT=3000
```
这是Web界面的访问端口，同样保持默认。
模型配置 – 这是重中之重 ( LLM_API_BASE , DEFAULT_MODEL ) ：
```
# 如果你使用OpenAI的API
# LLM_API_BASE=https://api.openai.com/v1
# DEFAULT_MODEL=gpt-4o-mini

# 如果你使用本地Ollama（这是我们本次的重点）
LLM_API_BASE=http://host.docker.internal:11434
DEFAULT_MODEL=llama3.2:1b
```
- LLM_API_BASE ：告诉OpenClaw去哪里找大模型服务。当我们在Docker容器内运行OpenClaw时，要访问宿主机（你的电脑）上运行的Ollama服务，不能直接用 localhost 或 127.0.0.1 ，因为容器有自己的网络空间。 host.docker.internal 是Docker提供的一个特殊域名，指向宿主机，这是关键技巧。
- DEFAULT_MODEL ：指定默认使用哪个模型。这里我填的是 llama3.2:1b ，这是Meta一个很小的模型，下载快，适合测试。你之后可以换成 qwen2.5:7b 、 llama3.1:8b 等更大更强的模型。
数据库配置（可选，但建议设置） ：
```
DATABASE_URL=postgresql://openclaw:your_strong_password@db:5432/openclaw
```
默认配置可能使用SQLite，但对于生产或长期使用，PostgreSQL更稳定。上面的配置是使用Docker Compose中另一个PostgreSQL容器的示例。你需要将 your_strong_password 替换成一个复杂的密码。
密钥与安全配置 ：
```
# 生成一个随机的密钥，用于加密等安全操作
echo $RANDOM | md5sum | head -c 32
```
将上面命令的输出（一串32位的十六进制字符）填入 SECRET_KEY 环境变量。不要使用示例中的默认值。

修改完成后，保存并退出编辑器。

3.3 一键启动与日志监控

配置文件就绪后，启动就非常简单了。Docker Compose会帮你拉取镜像、创建网络、启动所有定义的服务（OpenClaw后端、前端、数据库等）。

# 在包含 docker-compose.yml 和 .env 文件的目录下执行
docker-compose up -d

-d 参数代表“后台运行”。执行这个命令后，Docker会开始工作。第一次运行需要从Docker Hub拉取镜像，速度取决于你的网络。

如何知道启动是否成功？查看日志是最直接的方式：

# 查看所有服务的综合日志
docker-compose logs -f

# 或者只看后端服务的日志
docker-compose logs -f backend

-f 参数表示“跟随”，会实时输出新的日志。当你看到后端日志中出现类似 Application startup complete. 或 Uvicorn running on http://0.0.0.0:7860 的信息，前端服务也显示正常时，通常就表示启动成功了。

此时，打开你的浏览器，访问 http://你的服务器IP:3000 （如果是本地安装，就是 http://localhost:3000 ）。你应该能看到OpenClaw的登录或注册界面。

踩坑记录 ：如果访问不了，首先检查防火墙是否放行了3000和7860端口（对于云服务器尤其重要）。其次，用 docker-compose ps 命令查看所有容器状态是否为 Up 。如果有容器是 Exit 状态，用 docker-compose logs [服务名] 查看具体错误信息。常见错误包括： .env 文件配置错误（比如模型地址不对）、端口冲突、数据库连接失败等。

4. 模型连接实战：让OpenClaw拥有“大脑”

OpenClaw服务跑起来了，但它现在还是个“空壳”，因为它没有连接任何AI模型，无法进行对话或处理任务。接下来，我们要解决“大脑”的问题。我们将使用Ollama在本地运行大模型，并让OpenClaw连接到它。

4.1 本地模型引擎Ollama的安装与配置

Ollama是目前在本地运行和部署大模型最简单易用的工具。我们在宿主机（而不是Docker容器里）安装它。

# 使用Ollama官方的一键安装脚本
curl -fsSL https://ollama.com/install.sh | sh

安装完成后，启动Ollama服务：

# 启动服务并设置开机自启
sudo systemctl enable ollama
sudo systemctl start ollama

检查Ollama服务状态： sudo systemctl status ollama ，应该显示 active (running) 。

4.2 拉取并测试第一个模型

Ollama安装好后，我们需要拉取一个模型。为了快速测试，我们先拉取一个小模型。

# 拉取Llama 3.2 1B参数的小模型
ollama pull llama3.2:1b

这个模型只有1B参数，体积小，下载快，几乎所有机器都能跑起来。等待下载完成。

下载完成后，测试一下模型是否能正常工作：

ollama run llama3.2:1b

在出现的 >>> 提示符后，输入 Hello ，看模型是否能正常回复。输入 /bye 退出交互模式。这个步骤验证了Ollama本身和模型都是没问题的。

4.3 在OpenClaw中配置并验证模型连接

这是最关键的一步，确保OpenClaw（在Docker容器内）能访问到宿主机上的Ollama服务。我们之前已经在 .env 文件中配置了 LLM_API_BASE=http://host.docker.internal:11434 。这个配置在Linux和Mac的Docker Desktop环境下通常有效，但在纯Linux服务器（无Desktop）或某些WSL2环境下可能失效。

验证连接是否通畅：

首先，进入OpenClaw的后端容器内部执行测试：

# 找到后端容器的名字或ID
docker-compose ps
# 假设后端服务名是`backend`，进入容器
docker-compose exec backend bash

在容器内部，尝试curl Ollama的API：
```
curl http://host.docker.internal:11434/api/tags
```
如果返回一个JSON，列出了你拉取的模型（如 llama3.2:1b ），那么恭喜，网络是通的。输入 exit 退出容器。
如果上一步失败 （返回 Connection refused ），说明 host.docker.internal 解析不了。这是Linux原生Docker的常见问题。解决方案是使用宿主机的实际IP地址。首先在宿主机上执行 hostname -I 获取IP（比如 192.168.1.100 ），然后修改 .env 文件：
```
LLM_API_BASE=http://192.168.1.100:11434
```
重要：确保宿主机的防火墙（如 ufw ）允许11434端口的入站连接： sudo ufw allow 11434 。

修改完 .env 后，需要重启OpenClaw服务以使配置生效：

docker-compose down
docker-compose up -d

4.4 在Web界面完成模型绑定与首次对话

服务重启后，再次访问 http://localhost:3000 。

注册/登录 ：首次使用需要创建一个账户。
进入模型设置 ：登录后，在Web界面中找到模型设置或Profile设置区域（不同版本界面可能不同，通常在左下角用户图标或设置齿轮图标里）。
配置模型 ：你应该会看到一个下拉菜单或输入框，用于选择或输入模型。如果前面网络配置正确，这里应该能自动检测到或允许你输入我们在 .env 中设置的 DEFAULT_MODEL （ llama3.2:1b ）。选择或确认这个模型。
发起对话 ：找到创建新对话的按钮，随便问一个问题，比如“介绍一下你自己”。如果一切顺利，你应该能收到来自 llama3.2:1b 模型的回复。

至此，你已经成功部署了一个带有“本地大脑”的OpenClaw AI智能体平台！你可以开始探索它的基础功能了。

5. 进阶配置与高频问题排雷

基础功能跑通只是第一步。在实际使用中，你会遇到各种问题。下面我分享几个最常见的进阶配置和踩坑点。

5.1 如何添加和管理多个大模型？

你不可能只满足于一个小模型。OpenClaw支持同时配置多个模型，并在不同场景下切换使用。

方法一：通过环境变量预设（推荐） 在 .env 文件中，你可以预设多个模型。虽然 DEFAULT_MODEL 只能指定一个，但OpenClaw的后端通常会读取Ollama提供的模型列表。确保你的Ollama里拉取了多个模型：

ollama pull qwen2.5:7b
ollama pull llama3.1:8b

重启OpenClaw后端后，在Web界面的模型选择下拉菜单里，你应该能看到所有可用的模型。

方法二：通过OpenClaw技能动态调用 在编写自定义技能（Skill）时，你可以在代码中指定使用哪个模型的API端点。这需要一定的开发能力，但提供了最大的灵活性。例如，一个技能可以调用GPT-4处理复杂逻辑，另一个技能调用本地模型处理简单问答。

5.2 解决“失忆症”：会话记忆与数据库持久化

你提到的“第二天就不知道昨天会话的内容了”，这是AI对话的一个核心问题—— 长上下文记忆 。OpenClaw本身提供基础的会话记忆功能，但默认可能只存在于内存中，服务重启就消失了。

解决方案：启用并正确配置数据库持久化。 这就是为什么我之前建议在 .env 中配置 DATABASE_URL 指向PostgreSQL。当使用数据库后，OpenClaw可以将对话历史、用户信息、技能状态等持久化存储。

确保 docker-compose.yml 中包含了PostgreSQL服务（官方配置通常包含）。
在 .env 中配置正确的 DATABASE_URL （用户名、密码、数据库名需与 docker-compose.yml 中定义的一致）。
重启服务： docker-compose down && docker-compose up -d 。

重启后，OpenClaw会自动进行数据库迁移。此后，你的对话历史就会被保存下来。在Web界面中，你应该能看到历史会话列表。

更进一步：向量数据库与长期记忆 对于更复杂的、需要从大量历史对话中检索相关信息的“记忆”功能，需要引入向量数据库（如Chroma, Weaviate）。这属于高级用法，OpenClaw可能通过插件或特定技能支持。你需要查阅其关于“Memory”或“Vector Store”的进阶文档。

5.3 网络与端口冲突的深度排查

如果始终无法访问Web界面或模型连接失败，请按以下顺序排查：

容器状态 ： docker-compose ps 。所有服务必须是 Up 状态。如果有 Exit ，用 docker-compose logs [服务名] 看错误日志。
端口占用 ：在宿主机执行 sudo ss -tulpn | grep :3000 和 sudo ss -tulpn | grep :7860 ，确认端口是否被Docker进程正确监听。
防火墙 ：云服务器（如阿里云、腾讯云）需要在安全组规则中放行3000和7860端口。本地防火墙（ ufw ）也需要放行： sudo ufw allow 3000 && sudo ufw allow 7860 。
Docker网络 ：执行 docker network ls 和 docker network inspect openclaw_default （网络名可能不同），查看容器IP和网络连通性。确保后端容器能ping通宿主机的IP。
Ollama API可访问性 ：在宿主机上直接执行 curl http://localhost:11434/api/tags ，确保Ollama本身服务正常。然后在OpenClaw后端容器内，尝试curl宿主机的IP（如 curl http://192.168.1.100:11434/api/tags ）。

5.4 常见错误“openclaw llamap svr operator(): got exception”解析

这个错误信息是不完整的，但它指向了OpenClaw后端（ llamap svr 可能指LLM API Server）在调用大模型服务时出现了异常，通常伴随一个400或500的错误码。

原因1：模型名称错误 。 .env 中的 DEFAULT_MODEL 名称与Ollama中拉取的模型标签不完全一致。Ollama的模型名是 作者/模型名:标签 的格式，有时只需要 模型名:标签 。用 ollama list 确认准确的模型名称。
原因2：API地址错误 。 LLM_API_BASE 配置错误，导致连接不上Ollama。按照4.3节的方法进行容器内网络测试。
原因3：模型未加载或加载失败 。Ollama虽然拉取了模型，但该模型可能损坏或不适配当前系统。尝试在Ollama中重新拉取： ollama rm 模型名 然后 ollama pull 模型名 。
原因4：请求格式或参数错误 。OpenClaw向后端模型发送的请求不符合Ollama的API规范。这可能是OpenClaw的bug或版本不匹配。查看OpenClaw后端容器的详细日志，找到完整的错误信息，通常会包含更具体的错误描述。

排查步骤 ：

打开OpenClaw后端日志： docker-compose logs --tail=100 backend 。
找到包含该错误信息的完整段落。
根据具体的错误码和描述，对照上述原因进行排查。如果是400错误，多半是请求参数问题（模型名）；如果是连接错误，就是网络问题。

6. 下一步：从安装到实际应用

成功安装并连接模型，只是打开了OpenClaw世界的大门。接下来，你可以探索以下几个方向，让它真正为你所用：

探索内置技能 ：OpenClaw预置了一些基础技能，比如网页搜索、代码执行、文件读取等。在Web界面的技能市场或设置里看看，尝试启用和配置它们。
接入飞书/微信 ：这是非常实用的功能。OpenClaw提供了机器人适配器。以飞书为例，你需要：
- 在飞书开放平台创建一个企业自建应用，获取 App ID 和 App Secret 。
- 在OpenClaw的后台配置页面，找到飞书机器人配置项，填入这些凭证。
- 配置飞书事件订阅和消息回调URL（指向你的OpenClaw服务器地址）。
- 这个过程涉及网络穿透（如果你没有公网IP，可能需要内网穿透工具），是第一个综合性的挑战。
编写自定义技能 ：这是OpenClaw的精髓。你可以用Python编写技能，定义AI能执行的具体任务。例如，一个“天气查询”技能，一个“自动整理会议纪要”技能。官方文档会提供Skill SDK的使用方法。
尝试不同的模型 ：把默认的小模型换成更强的 qwen2.5:14b 或 llama3.1:70b （如果你的硬件足够强大），感受对话质量和逻辑能力的提升。
研究Agent工作流 ：OpenClaw的核心是智能体（Agent）。学习如何配置Agent的提示词（Prompt）、规划器（Planner）和执行器（Executor），让AI能够自动分解复杂任务并调用不同的技能来完成。