OpenClaw 自托管部署全指南：从环境配置到日常运维

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 先选路线，别两头都折腾

很多教程会把两条路线混在一起讲，结果读者反而乱了。我用一个表格把关键差异列出来：

个人建议：没有特殊需求就无脑走容器化。等真正需要改代码时再切换，反正数据目录可以共用，配置也可以迁移。不要一开始就搞"我既想容器又想改代码"的混合模式，配置复杂度会在你还没用熟项目时就劝退你。

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: - PORT=8787 - DATABASE_PATH=/data/openclaw.db - LOG_LEVEL=info 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_URL=https://api.example-model-service.com/v1 LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx LLM_MODEL=your-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 高频故障排查表

下面这些是我在部署和日常维护中最常遇到的问题：

排查的基本功是"先看日志，再猜原因"。不要一上来就怀疑项目有 bug，先把时间线拉出来：是什么时候开始坏的？最近改了配置还是升级了？日志里第一条异常是在什么时间出现的？按这个思路，九成问题都能在十分钟内定位。剩下的那部分，多半是文档里写过的已知问题，去仓库的 issue 区搜一搜关键词就有答案了。

7. 收尾：一点从实际部署中攒下的体会

部署 OpenClaw 这类自托管 AI 服务，最容易被低估的是长期维护成本。头两天你会很有成就感，因为一个完全可控的 AI 助理在自家机器上跑起来了；但一个月后，你要面对的是升级、密钥轮换、磁盘扩容、日志轮转这些不那么性感的工作。我的建议是，从一开始就把可维护性写进习惯：所有配置集中到一个 .env，数据目录固定在一个地方，升级前总是先备份，容器设置好重启策略。

另一个体会是权限最小化。AI 助手跑起来之后，你会忍不住把所有插件都打开，让它读文件、执行命令、发消息。但请记住，你部署它是为了省时间，不是为了给自己埋雷。每次打开一个新工具前，问自己一句：如果它在全权限下误操作一次，我能不能立刻止损？不能的话，就先把工具关掉，或者加一个人工确认环节。

最后，如果你只是想在局域网里体验一把，源码部署和容器化其实差别不大；可一旦你想让它稳定服务半年以上，容器化加定时备份几乎是必选项。希望这篇教程能帮你少走一些我走过的弯路。遇到奇怪的报错，建议先按第 6 节的排查顺序走一遍，多数时候答案就在日志里。