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

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

1. 后端服务配置 (OPENCLAW_BACKEND_PORT)：

   OPENCLAW_BACKEND_PORT=7860

   这是后端API服务的端口，保持默认即可，除非7860端口被占用。

2. 前端服务配置 (OPENCLAW_FRONTEND_PORT)：

   OPENCLAW_FRONTEND_PORT=3000

   这是Web界面的访问端口，同样保持默认。

3. 模型配置 – 这是重中之重 (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等更大更强的模型。

4. 数据库配置（可选，但建议设置）：

   DATABASE_URL=postgresql://openclaw:your_strong_password@db:5432/openclaw

   默认配置可能使用SQLite，但对于生产或长期使用，PostgreSQL更稳定。上面的配置是使用Docker Compose中另一个PostgreSQL容器的示例。你需要将your_strong_password替换成一个复杂的密码。

5. 密钥与安全配置：

   # 生成一个随机的密钥，用于加密等安全操作 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环境下可能失效。

验证连接是否通畅：

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

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

2. 在容器内部，尝试curl Ollama的API：

   curl http://host.docker.internal:11434/api/tags

   如果返回一个JSON，列出了你拉取的模型（如llama3.2:1b），那么恭喜，网络是通的。输入exit退出容器。

3. 如果上一步失败（返回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。

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

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

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

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

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

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

1. 容器状态：docker-compose ps。所有服务必须是Up状态。如果有Exit，用docker-compose logs [服务名]看错误日志。
2. 端口占用：在宿主机执行sudo ss -tulpn | grep :3000和sudo ss -tulpn | grep :7860，确认端口是否被Docker进程正确监听。
3. 防火墙：云服务器（如阿里云、腾讯云）需要在安全组规则中放行3000和7860端口。本地防火墙（ufw）也需要放行：sudo ufw allow 3000 && sudo ufw allow 7860。
4. Docker网络：执行docker network ls和docker network inspect openclaw_default（网络名可能不同），查看容器IP和网络连通性。确保后端容器能ping通宿主机的IP。
5. 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后端容器的详细日志，找到完整的错误信息，通常会包含更具体的错误描述。

排查步骤：

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

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

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

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

安装只是起点，真正的乐趣在于配置和创造。在这个过程中，你一定会遇到更多问题，善用日志、搜索引擎和开源社区的Issue页面，大部分问题都有解决方案。记住，每一步报错都是学习其运作原理的机会。