1. OpenClaw 部署前先想清楚它到底帮你解决什么问题OpenClaw 部署这个关键词最近在自托管圈子里出现得挺频繁。乍一看又是一个开源 AI 助手项目但真要把这坨东西跑在自己机器上跟用别人搭好的在线服务完全是两码事。它本质上是一个自托管的 AI 助理框架把对话、任务执行、文件管理和日常自动化塞进一个服务里然后暴露成网页、API或者挂到几个常见聊天工具上。适合的人群很明确想拥有独立 AI 助理、不想把数据全交给外部服务、并且愿意自己承担运维责任的人。动手部署 OpenClaw 之前我一直提醒自己这不是一个安装完就结束的软件而是一套需要持续维护的小系统。它通常由一个核心服务端、一个界面、若干渠道入口和一堆可插拔的工具组成。你在部署阶段需要做的不只是把代码跑起来还要把密钥、存储、权限、入口这四件事一次性安排好。这篇教程会按我实际跑通的顺序来讲尽量少贴废话多给可以直接照做的操作步骤和经验教训。1.1 它解决的痛点市面上的 AI 助手要么封闭在某个厂商生态里要么只给你一个网页聊天框你的文件、日程、邮件都要在别人服务器上过一遍。OpenClaw 这类项目把助理拆成服务端和客户端你把它装在自己的机器上模型接口由你自己指定数据也落在你控制的目录里。它给的是一种很朴素的安全感服务是我的数据是我的规则也是我定的。但要强调一个容易误解的地方OpenClaw 本身不包含大模型。它负责的是调度、记忆、工具调用和交互入口至于脑子用哪家的模型、是本机推理还是云端接口这些是部署时你自己填的配置项。所以部署 OpenClaw 的前提是你至少有一个能用的模型访问地址不管是订阅的在线 API还是自己搭的本地推理服务。没有这个前提后面一切功能都无从谈起。1.2 部署从来不是把命令敲完很多人上来就 git clone 然后安装依赖结果跑起来发现日志疯狂报错第一反应是项目有问题。其实大多数时候是没搞清这套系统的依赖关系。它至少涉及四层运行环境Node 或 Python 这类运行时、数据层有些版本用 SQLite有些用外部数据库、模型接口密钥与地址、交互入口网页或外部回调。这四层任何一环没配好服务都能启动但功能会时好时坏。我建议在心态上把它当成一个微型 SaaS 产品来部署而不是一个脚本。所谓的部署本质是你在扮演这家 SaaS 的运维工程师。配置要集中管理日志要养成看的习惯升级要有回滚预案。这几件事做好了OpenClaw 能跑得很稳做不好三天两头出幺蛾子到时候你会把时间全花在为什么昨天还能用今天就不行了这类问题上。1.3 先确认你要部署的是哪个版本开源项目迭代非常快一个月前的教程很可能已经过时这行最不缺的就是过期教程。动手前先去项目仓库的 README 看三样东西默认端口、环境变量列表、官方推荐的部署方式是 Docker Compose 还是裸进程。很多版本已经将 Docker Compose 作为首选路径因为能省掉大部分依赖地狱也有些版本只提供源码构建方式那你就得老老实实准备运行环境。我下面给的方案是基于官方提供了 Compose 模板这一常见实践来写的。如果你的版本没有模板也不用慌直接跳到源码部署那一节思路是通用的。另外尽量切到稳定版本或打了 release 标签的提交别用最新主分支就开跑。主分支通常承载着开发中的功能稳定性没法保证生产环境用它属于给自己找麻烦。2. 部署前的环境盘点这些没准备好后面全是坑很多人的部署失败不是技术问题而是环境没盘清楚就着急动手。我见过好几个案例内存只剩几百兆就开始拉镜像跑起来后服务直接被杀掉或者没确认系统架构就去拉镜像启动时提示exec format error非常尴尬。所以这一章把这些前置条件摊开讲一遍。2.1 硬件与系统选型OpenClaw 本身不跑大模型的时候资源占用并不高1 核 1G 的小机器也能转起来但这取决于你给它配了多少活儿。如果只是聊天和简单任务一个 2 核 2G 的实例足够日常使用如果还要挂文件索引、定时任务、多用户访问建议 4 核 4G 起步。如果模型推理也跑在本机那就是另一回事内存和显存的需求会直接翻好几倍建议把模型任务和 OpenClaw 服务拆到不同机器。系统方面Linux 是首选Ubuntu/Debian 系对 Docker 和依赖管理最省心。macOS 也可以但要注意芯片架构Apple Silicon 上跑容器时某些旧镜像会有兼容问题虽然现在大部分镜像都提供 arm64 版本但确认一下没有坏处。Windows 用户我建议不要裸跑直接用 WSL2 或 Docker Desktop否则环境变量、路径权限、文件监听这些都会变成额外的心智负担。2.2 依赖软件清单一句话优先装 Docker Engine 和 Docker Compose 插件。这个组合能把运行环境、系统库、版本冲突全部关进容器里是我试过最省事的路线。安装完成后先用下面几句把环境确认好再继续后续操作docker version docker compose version git --version源码部署则还需要 Git以及项目对应语言的运行时。常见的是 Node.js 20 或 Python 3.11版本具体要求以仓库标注为准。这里有个小经验安装完 Docker 后把自己加入 docker 用户组再重新登录能避免每次敲命令都带 sudo。许多新手在这上面卡住报错还是权限相关的看着莫名其妙。提醒容器化之所以推荐不只是因为不污染系统而是升级和回滚确实方便。你拉一个新镜像试出问题一条命令就能退回上一个标签源码部署想回滚得折腾 git 分支和重新编译时间成本完全不同。2.3 密钥和模型服务准备这是很多人卡住的第一步。OpenClaw 需要访问某个大模型接口所以你手上必须有三个东西接口地址通常叫 base_url、访问密钥API Key、模型名称model。如果用的是在线服务去对应控制台生成一把 Key如果想完全离线就自建一个本地推理服务把地址指到本机端口。安全习惯必须到位。密钥不要写死在代码或前端环境里统一放到 .env 文件里并且 .env 一定要加进 .gitignore。我见过不止一次因为 .env 被随手提交到仓库几个小时后额度就被薅走的事故。这种事一旦发生只能尽快吊销密钥重新生成没有别的补救办法。部署这种带外部资源访问权限的服务密钥管理和代码管理至少要分开。3. 两条部署路线容器化一键拉起还是源码构建跑通这里我把两条路线都讲清楚。你不用两条都走只看自己适合哪种就好。判断标准很简单你的目标是尽快跑起来、以后稳定维护走容器化你的目标是改源码做二次开发走源码构建。两者数据目录可以共用所以哪怕后面切换路线迁移成本也不高。3.1 先选路线别两头都折腾很多教程会把两条路线混在一起讲结果读者反而乱了。我用一个表格把关键差异列出来对比项Docker Compose源码部署首次上手快一条命令拉起全套慢依赖和构建环节多依赖隔离好容器内自洽一般容易和系统环境冲突升级回滚好换镜像标签即可中等依赖 git 管理调试改代码不方便要挂卷和看容器日志方便能直接改文件重启磁盘占用较大镜像和构建缓存叠加较小个人建议没有特殊需求就无脑走容器化。等真正需要改代码时再切换反正数据目录可以共用配置也可以迁移。不要一开始就搞我既想容器又想改代码的混合模式配置复杂度会在你还没用熟项目时就劝退你。3.2 路线一Docker Compose 一键拉起假设你已经装好 Docker 和 Compose。先建一个工作目录比如 /opt/openclaw然后在里面放一份 docker-compose.yml。下面是我按常见配置改的演示版端口、数据目录、环境变量需要以你所用版本的官方模板为准这里的作用是展示关键结构services: openclaw: image: openclaw/openclaw:latest # 具体镜像名以仓库为准 container_name: openclaw restart: unless-stopped ports: - 8787:8787 environment: - PORT8787 - DATABASE_PATH/data/openclaw.db - LOG_LEVELinfo volumes: - ./data:/data - ./.env:/app/.env:ro extra_hosts: - host.docker.internal:host-gateway这里几个关键点必须搞懂。第一数据目录一定要用卷挂出来否则容器一删除你所有会话和历史记录全没了。第二.env 用只读方式挂进容器配置和镜像分离这样升级时不会覆盖你的配置。第三extra_hosts 这行是为了让容器能访问宿主机上的本地模型服务。如果你的模型接口在云端这行可以删掉如果模型跑在本机没有这行容器里的 127.0.0.1 指向的是容器自己不是宿主机你会得到一堆连接超时。然后一行启动cd /opt/openclaw docker compose up -d docker compose logs -f openclaw第一次启动会拉镜像网络正常的话几分钟内能看到日志输出。看到服务启动完成或开始监听端口这类提示就说明基础服务已经活了。到这里先别急着开界面接着往下做健康检查。3.3 路线二源码部署适合改代码如果你确实想源码跑步骤大概是克隆仓库、切到稳定分支、安装依赖、配置环境变量、启动服务。以常见的 Node 项目为例git clone 仓库地址 /opt/openclaw-src cd /opt/openclaw-src git checkout 稳定版本tag cp .env.example .env npm install --production npm run build npm start这条路上我踩过最大的坑是依赖版本。开源项目通常会精确声明依赖你本机 Node 版本太低install 阶段就直接报错版本太高又可能触发原生模块编译问题。所以源码部署前一定先看仓库里写明的运行时版本比如 .nvmrc 文件或 package.json 里的 engines 字段再用版本管理工具把运行时切到指定版本。如果你的项目是用 Python 写的逻辑一样区别只是把 npm 换成 pip 或 uv把构建命令换成对应的入口脚本。核心思路不变先锁定官方要求的运行环境再装依赖再配环境变量最后启动。3.4 统一验证服务健康检查不管哪条路线跑起来后第一件事不是打开界面而是做健康检查。绝大多数这类服务都会暴露一个健康检查端点常见的是 /health 或 /api/health返回 JSON 结构。我习惯这样验证curl -s http://127.0.0.1:8787/health期望看到类似 {status:ok} 的结构。如果 curl 超时或返回 5xx别急着开浏览器先回去看容器日志或启动日志。这一步做得好能把前端白屏和后端没起来这两类问题快速分开省下大量瞎猜的时间。健康检查是部署冷启动后的第一个里程碑过了这关才能开始配置模型和功能。4. 首次启动后的核心配置这些不设好等于白装服务进程能跑了但离能用还有一段距离。这一章讲的配置项决定了 OpenClaw 是一个能打开的页面还是一个真正能帮你干活的助理。我见过太多人卡在页面能打开但问什么都是报错的环节其中九成是模型配置没填对剩下的是权限和存储没安排好。4.1 接入你的模型服务打开 .env把模型相关配置填上。常见的三段配置是这样的LLM_BASE_URLhttps://api.example-model-service.com/v1 LLM_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxx LLM_MODELyour-model-name如果你用的是本地推理服务地址要填 http://127.0.0.1:11434 这类端口但注意区分部署方式。容器部署时宿主机上的服务对容器来说要访问 host.docker.internal而不是 127.0.0.1源码部署则直接填 127.0.0.1 就行。这也是我在 Compose 里加 extra_hosts 的原因。配完之后先别急着测各种高级功能。用一个最简单的 Prompt 在界面里发一句你好确认能收到正常回复再继续下一步。很多后续功能报错根源都是模型没接对而不是功能本身坏了。模型接口通了你的 OpenClaw 才算真正活了。4.2 创建管理员账号与访问控制大多数自托管系统首次打开会引导你注册一个管理员账号。这里有两个安全选项要分清。第一关闭开放注册。如果这个服务要暴露在公网上开放注册基本等于给陌生人打开你家大门一定要在设置里把允许注册关掉只保留管理员邀请方式。第二给管理后台和普通访问设不同入口管理端尽量只允许白名单 IP 访问。我的建议排序是内网使用启动时固定一个管理员账号就够了公网访问至少要加一层反向代理加基础认证。别嫌多一层麻烦等到你发现后台被未知用户登录时再弥补的成本要高得多。访问控制这种事宁可一开始多配一步也不要事后补救。4.3 数据存储与备份边界OpenClaw 的会话、记忆、用户数据会落在你挂出来的数据目录里。你要搞清楚三件事数据库文件叫什么名字、有没有上传文件目录、日志写在哪里。这决定了你以后备份时到底要复制哪些东西。最简单的备份方式就是整个数据目录打包更讲究一点用数据库自带的导出命令做一致性备份防止在写入过程中打包出来的文件损坏。我见过有人备份时只备份了数据库文件漏掉了上传目录结果恢复了数据库却发现所有附件都不见了。这种问题在部署阶段就把数据边界搞清楚后面根本不会发生。4.4 工具与插件权限先做减法这类 AI 助理通常自带文件读取、命令执行、HTTP 请求等工具。强烈建议部署初期把不需要的工具全部关掉只保留聊天和基础记忆。原因很简单你还没摸清它对权限边界的判断能力就让它去执行任意命令真出一次乱操作挽救成本比你省下的配置时间高得多。等你在受控环境里充分测试过后再逐步打开需要的插件并为关键操作加上人工确认。这个优先级我觉得怎么强调都不过分AI 助理的价值在于省时间但前提是它不能给你埋雷。权限最小化不是限制它而是保护你自己。5. 把 OpenClaw 接到日常使用入口跑通核心功能后下一步是让它融入你的日常工作流。OpenClaw 的交互入口通常有三类网页界面、REST API、聊天渠道。这一章分别讲它们的配置要点和常见坑。5.1 网页界面最直接的验证入口跑通之后浏览器打开 http://你的服务器IP:8787就能看到管理界面。内网使用问题不大但如果要在浏览器长期使用我建议放到反向代理后面配上 HTTPS 和一个正经域名。明文 HTTP 在公网上裸奔不是什么好习惯尤其这个服务还会携带个人数据。反向代理配置本身不复杂把对应域名或路径转发到 8787 端口就行。有一个细节必须注意WebSocket 也要允许升级。很多这类服务会在网页上实现实时推送如果你的代理配置里没主动传 Upgrade 和 Connection 头页面会频繁断线重连表现为消息没提醒状态不同步特别难排查。5.2 通过 REST API 对接你自己的工具OpenClaw 一般会提供一套 HTTP API方便你把它嵌进自己的脚本或小程序里。调用时通常需要带访问令牌令牌在管理界面里生成。一个最朴素的对话请求长这样curl -X POST http://127.0.0.1:8787/v1/chat \ -H Authorization: Bearer 你的token \ -H Content-Type: application/json \ -d {message: 帮我整理一下今天的待办事项}拿到 200 和一段可读的回复说明 API 链路是通的。之后无论写定时任务、做自动化通知还是接别的平台思路都一样调 API、拿结果、处理异常。这里我想多说一句令牌要设有效期别一个 Token 用一年。定期轮换虽然麻烦一点但能大大降低泄露后的损失范围。5.3 聊天渠道接入把 OpenClaw 挂到常用聊天工具上是很多人的核心诉求。这一步的技术要点是回调你在聊天工具侧创建一个机器人拿到机器人的令牌然后在 OpenClaw 配置里填上令牌并把一个回调地址填回聊天工具侧。这个回调地址必须是公网可达的意味着你需要一个有效域名、HTTPS 和反向代理三层组合。提醒回调地址和业务 API 要分开看待。业务 API 是你主动访问服务webhook 是服务等别人来敲门的地址两者的网络暴露策略不一样。webhook 地址建议用独立路径并开启签名校验避免被伪造事件攻击。我刚接完渠道后遇到最多的现象是消息发送了但 OpenClaw 没反应。排查顺序是固定的先看聊天工具侧有没有报请求失败再看 OpenClaw 日志里有没有收到事件最后看回调网络通不通。绝大多数问题出在回调地址被防火墙拦截或证书不受信任真不是 OpenClaw 本身的问题。6. 升级、备份和常见故障排查维护才是持久战部署跑通只是第一步真正的考验在长期维护。很多自托管项目不是被安装难度劝退的而是被后续的升级和故障排查消磨光了耐心。这一章把维护期的关键技能拆开讲。6.1 小步升级别追新自托管服务最忌讳看到新版本就原地替换。我的操作顺序是固定的先备份再拉新镜像或代码然后看发布说明里有没有破坏性变更比如数据库迁移、环境变量改名最后再重启。容器化场景下大概是一分钟的事cd /opt/openclaw docker compose pull docker compose up -d docker compose logs -f openclaw如果升级后发现问题立刻用旧镜像标签重新启动即可回滚。这就是我一直强调要用镜像标签而不是 latest 的原因latest 会漂移你根本不知道自己回退到哪一版。源码部署也一样每次升级前记下当前提交哈希出问题就能精确回退。6.2 备份清单与一条命令备份对象包括整个数据目录、.env 文件以及自定义的插件或配置目录。一个粗粒度的定时备份脚本示例#!/usr/bin/env bash backup_dir/var/backups/openclaw/$(date %F) mkdir -p $backup_dir cp -r /opt/openclaw/data $backup_dir/ cp /opt/openclaw/.env $backup_dir/ find $backup_dir -type d -mtime 30 -exec rm -rf {} 建议至少每天跑一次并定期做恢复演练。备份的目的是能恢复不只是能备份。这句话我每次都要强调因为只有真到灾难发生时你才会发现某个目录漏掉了或者备份文件已经损坏到那时做什么都晚了。6.3 高频故障排查表下面这些是我在部署和日常维护中最常遇到的问题现象可能原因处理方式容器一直重启数据目录卷权限不对或 .env 格式错误检查数据目录属主用 docker compose config 检查配置API 一直超时模型接口地址不可达或密钥无效先单独请求模型接口排除基础连通问题日志提示数据库被锁SQLite 在多进程下冲突确认只有一个实例在运行必要时换外部数据库WebSocket 频繁断开反向代理未开启 WS 升级在代理配置中正确传递 Upgrade 和 Connection 头页面打开白屏但健康检查正常前端资源路径配置不对或端口映射不全检查 PUBLIC_URL 等参数打开浏览器开发者工具看具体请求排查的基本功是先看日志再猜原因。不要一上来就怀疑项目有 bug先把时间线拉出来是什么时候开始坏的最近改了配置还是升级了日志里第一条异常是在什么时间出现的按这个思路九成问题都能在十分钟内定位。剩下的那部分多半是文档里写过的已知问题去仓库的 issue 区搜一搜关键词就有答案了。7. 收尾一点从实际部署中攒下的体会部署 OpenClaw 这类自托管 AI 服务最容易被低估的是长期维护成本。头两天你会很有成就感因为一个完全可控的 AI 助理在自家机器上跑起来了但一个月后你要面对的是升级、密钥轮换、磁盘扩容、日志轮转这些不那么性感的工作。我的建议是从一开始就把可维护性写进习惯所有配置集中到一个 .env数据目录固定在一个地方升级前总是先备份容器设置好重启策略。另一个体会是权限最小化。AI 助手跑起来之后你会忍不住把所有插件都打开让它读文件、执行命令、发消息。但请记住你部署它是为了省时间不是为了给自己埋雷。每次打开一个新工具前问自己一句如果它在全权限下误操作一次我能不能立刻止损不能的话就先把工具关掉或者加一个人工确认环节。最后如果你只是想在局域网里体验一把源码部署和容器化其实差别不大可一旦你想让它稳定服务半年以上容器化加定时备份几乎是必选项。希望这篇教程能帮你少走一些我走过的弯路。遇到奇怪的报错建议先按第 6 节的排查顺序走一遍多数时候答案就在日志里。
