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用户建议使用WSL2Windows 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_PORT7860这是后端API服务的端口保持默认即可除非7860端口被占用。前端服务配置 (OPENCLAW_FRONTEND_PORT)OPENCLAW_FRONTEND_PORT3000这是Web界面的访问端口同样保持默认。模型配置 – 这是重中之重 (LLM_API_BASE,DEFAULT_MODEL)# 如果你使用OpenAI的API # LLM_API_BASEhttps://api.openai.com/v1 # DEFAULT_MODELgpt-4o-mini # 如果你使用本地Ollama这是我们本次的重点 LLM_API_BASEhttp://host.docker.internal:11434 DEFAULT_MODELllama3.2:1bLLM_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_URLpostgresql://openclaw:your_strong_passworddb: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_BASEhttp://host.docker.internal:11434。这个配置在Linux和Mac的Docker Desktop环境下通常有效但在纯Linux服务器无Desktop或某些WSL2环境下可能失效。验证连接是否通畅首先进入OpenClaw的后端容器内部执行测试# 找到后端容器的名字或ID docker-compose ps # 假设后端服务名是backend进入容器 docker-compose exec backend bash在容器内部尝试curl Ollama的APIcurl 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_BASEhttp://192.168.1.100:11434重要确保宿主机的防火墙如ufw允许11434端口的入站连接sudo ufw allow 11434。修改完.env后需要重启OpenClaw服务以使配置生效docker-compose down docker-compose up -d4.4 在Web界面完成模型绑定与首次对话服务重启后再次访问http://localhost:3000。注册/登录首次使用需要创建一个账户。进入模型设置登录后在Web界面中找到模型设置或Profile设置区域不同版本界面可能不同通常在左下角用户图标或设置齿轮图标里。配置模型你应该会看到一个下拉菜单或输入框用于选择或输入模型。如果前面网络配置正确这里应该能自动检测到或允许你输入我们在.env中设置的DEFAULT_MODELllama3.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确认准确的模型名称。原因2API地址错误。LLM_API_BASE配置错误导致连接不上Ollama。按照4.3节的方法进行容器内网络测试。原因3模型未加载或加载失败。Ollama虽然拉取了模型但该模型可能损坏或不适配当前系统。尝试在Ollama中重新拉取ollama rm 模型名然后ollama pull 模型名。原因4请求格式或参数错误。OpenClaw向后端模型发送的请求不符合Ollama的API规范。这可能是OpenClaw的bug或版本不匹配。查看OpenClaw后端容器的详细日志找到完整的错误信息通常会包含更具体的错误描述。排查步骤打开OpenClaw后端日志docker-compose logs --tail100 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能够自动分解复杂任务并调用不同的技能来完成。安装只是起点真正的乐趣在于配置和创造。在这个过程中你一定会遇到更多问题善用日志、搜索引擎和开源社区的Issue页面大部分问题都有解决方案。记住每一步报错都是学习其运作原理的机会。