OpenClaw 安装手册：Docker、源码与一键脚本三条路线

OpenClaw 是一款常驻运行的个人 AI 助手框架，装好之后它守在服务器上，替你收消息、跑定时任务、回提醒、汇总信息。安装本身不难，难的是选错路线：有人在只有一台轻量服务器的情况下硬上源码编译，有人明明要长期运行却图省事用了别人写的一键脚本，出问题连装在哪都说不清。本篇只讲安装本身：先按你的环境把路线定下来，再按步骤装起来、验证通过，最后把模型、渠道、反向代理与备份配好。服务器怎么选、安全基线怎么做，不在这里重复，动手之前先看 VPS 环境搭建与准备，那篇已经把选型和加固讲全了。

还有一句要先说明：OpenClaw 的镜像名、环境变量名、命令行参数会随版本变化，以下命令里的这类名字以官方仓库当前 README 为准，复制之前先核对一次。版本号、下载地址这类信息本文一律不写死，同样以官方仓库为准。

一、安装方式取舍：三条路线各适合谁

Docker Compose 是大多数人的默认选择。好处是环境隔离：依赖装在容器里，不污染宿主机；升级是一条拉取加重启的命令；数据放在挂载目录里，容器删了重建也不丢。代价是你要先会 Docker 的基本操作，出了问题先看容器日志，而不是直接看宿主机进程。打算长期运行、以后还要升级和备份，选 Docker。

源码安装适合两类人：一是想改代码、跟进最新提交的开发者；二是装不了 Docker，或者对容器有硬性限制的场景。好处是每一步都看得见，出问题能直接定位到某行配置或某段日志；代价是你要自己管 Node 运行时版本、依赖安装、进程守护和开机自启，升级也要自己拉代码、重装依赖、重启服务。只是想用起来、不打算改代码的人，不必走这条路。

一键脚本适合只想快速验证的人：脚本把装运行时、拉代码、写配置、起服务几步包在一起，一条命令跑完就能看到管理界面。但代价同样明显：脚本替你做的决定越多，你对这台机器的掌控就越少；脚本来源不可靠时，它往机器里写了什么你也不知道。所以一键脚本只建议用在两处：官方仓库自己提供的脚本，或者你完整读过、确认每一步都理解的第三方脚本；跑完验证通过后，仍建议按后文的配置要点把关键配置亲手过一遍。生产用途、长期运行，优先选 Docker。

三条路线装出来的 OpenClaw 在功能上没有区别，区别只在后续怎么维护。选路线时就问自己：半年后要升级、迁移、排障时，你希望面对的是一组容器命令、一份源码目录，还是一段别人写的脚本。答案就是路线。

二、路线一：Docker Compose 安装

这是本篇的主线，也是推荐给大多数人的路线。

准备工作

先确认两件事。第一，Docker 和 Docker Compose 已经装好并能正常运行，验证方法很简单：

docker --version
docker compose version
sudo docker run hello-world

看到 hello-world 的欢迎信息，说明 Docker 本身没有问题。第二，确认你要用的端口没有被占用。OpenClaw 默认的管理端口在后文的 compose 文件里映射出来，启动之前先查一下：

ss -tlnp | grep 8080

有输出说明端口已被占用，换一个主机端口，或者先停掉占用它的服务。

建目录与环境变量文件

给 OpenClaw 一个专用的工作目录，数据、配置、日志都放在里面，后续备份和迁移都只认这个目录：

mkdir -p /opt/openclaw
cd /opt/openclaw
mkdir -p data config logs
chmod -R 755 /opt/openclaw

目录里主要放两样东西：docker-compose.yml 和 .env。先写 .env，把会变的东西（端口、时区、模型密钥）集中在这里，compose 文件本身就不用每次改了：

nano .env

# OpenClaw 基础配置
TZ=Asia/Shanghai
CLAW_ENV=production
OPENCLAW_PORT=8080

# AI 模型 API 密钥，按需填写，占位符用你自己的密钥替换
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
GOOGLE_API_KEY=YOUR_GOOGLE_API_KEY

# 管理员账户
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com

写 .env 有两条规矩。第一，密钥只写占位符形式的真实值，不要把密钥贴到任何公开地方，也不要把 .env 提交进版本控制；如果这个目录初始化了 git，顺手加一条：

echo ".env" >> .gitignore

第二，管理员密码不要写在 .env 里，首次启动时在管理界面里交互设置，密码至少十二位，大小写字母、数字和特殊字符都要有。

写 docker-compose.yml

nano docker-compose.yml

services:
  openclaw:
    image: openclaw/core:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - '${OPENCLAW_PORT:-8080}:8080'
    environment:
      - TZ=${TZ:-Asia/Shanghai}
      - CLAW_ENV=${CLAW_ENV:-production}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
    volumes:
      - ./data:/app/data:rw
      - ./config:/app/config:rw
      - ./logs:/app/logs:rw
    networks:
      - openclaw-network
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  openclaw-network:
    driver: bridge

这份文件里有几处值得讲清楚。restart 写 unless-stopped，意思是容器退出就自动重启，只有你手动停掉它才停，服务器重启后服务自己回来。ports 的写法是主机端口在前、容器端口在后，冒号左边是你从浏览器访问的端口，右边是容器里 OpenClaw 监听的端口；想换访问端口只改 .env 里的 OPENCLAW_PORT，不用动 compose 文件。volumes 三行是数据持久化的关键：容器里的数据目录映射到宿主机的 data、config、logs，容器删了重建，数据还在。healthcheck 是健康检查，容器起来后定期访问它自己的健康检查地址，连续失败就判定为不健康，排障时看状态能少走弯路。镜像名和环境变量名以官方仓库为准，复制前核对一次。

启动与查看

启动之前先验证 compose 文件语法有没有问题：

docker compose config

没有报错会输出一份展开后的完整配置，有报错就按提示修，修好再启动：

docker compose up -d
docker compose logs -f

首次启动时 Docker 会先拉取镜像，再创建容器、初始化数据，这个过程需要几分钟，取决于网络速度。日志里出现服务就绪的提示后，按 Ctrl+C 退出日志查看，服务本身还在后台运行。

启动后确认三件事。第一，容器在运行且没有反复重启：

docker ps
docker stats openclaw

第二，端口确实在监听：

ss -tlnp | grep 8080
curl http://localhost:8080

第三，浏览器能打开管理界面。地址是服务器 IP 加端口，例如 http://服务器 IP:8080。如果浏览器打不开，先看容器日志，再看端口监听，最后看防火墙和云厂商安全组有没有放行这个端口；安全组的配置方法在 VPS 环境搭建与准备 里有，端口放行只放你实际用的那一个，不要图省事放行一段范围。

日常维护命令

装好之后最常用的就是下面这几条，背下来能省很多事：

# 停止服务
docker compose down

# 重启服务
docker compose restart

# 查看实时日志，只看最近一百行
docker compose logs -f --tail=100

# 进入容器内部调试
docker exec -it openclaw /bin/bash

# 更新到最新版本
docker compose pull
docker compose up -d

# 备份数据卷
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz data/ config/ .env docker-compose.yml

更新之前务必先备份，更新命令本身不丢数据，但万一新版本有不兼容的改动，备份是唯一的退路。备份文件不要和数据放在同一台机器上，至少要有一份在别处。

三、路线二：源码安装

源码路线的前提是你已经装好 Node 运行时，版本以官方仓库的要求为准，装之前先看仓库 README 里写的版本范围，差一个大版本就可能装不上依赖。

第一步是拉代码并装依赖：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install

依赖装完之后，先不要急着启动。源码运行需要一份配置文件，仓库里一般会带一份示例配置，复制出来改成自己的：

cp .env.example .env
nano .env

.env 里要填的东西和 Docker 路线一样：监听端口、模型密钥、数据目录。密钥同样只写自己的真实值，不要贴到公开地方。配置文件改好后，先以前台方式跑一次，看日志有没有报错：

npm start

前台跑通了，再考虑长期运行。长期运行不能靠前台窗口，窗口一关服务就停，正确做法是用进程守护工具。systemd 是最常见的一种，写一个服务单元文件：

sudo nano /etc/systemd/system/openclaw.service

[Unit]
Description=OpenClaw AI Agent
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/opt/openclaw
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

这里的 WorkingDirectory 要改成你实际拉代码的目录，User 改成实际运行它的用户，不要用 root 跑。写好之后启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

升级时按固定顺序走：先停服务，再拉代码、重装依赖，最后重启并看日志：

sudo systemctl stop openclaw
git pull
npm install
sudo systemctl start openclaw
sudo systemctl status openclaw

升级之前同样先备份数据目录和配置文件，源码升级出问题时，回退就是把代码切回上一个提交、重启服务，数据不动。

四、路线三：一键脚本安装

一键脚本的用法只有一句话：确认脚本来源可靠，读过脚本内容，再运行。官方仓库提供的脚本优先，第三方脚本要先看它到底做了什么：装了哪些软件包、改了哪些系统配置、有没有往机器里写你不知道的东西。看不懂的步骤不要跳过，看不懂就不要跑。

运行之前先把脚本下载到本地看一遍，不要直接用管道符把远程脚本送进 shell：

curl -fsSL https://example.com/install.sh -o install.sh
less install.sh
bash install.sh

这里的地址只是写法示例，真正的脚本地址以官方仓库公布的为准。脚本跑完之后，不要以为装好了就结束了，接着做三件事。第一，确认服务确实在运行，管理界面能打开，登录进去看一眼。第二，确认数据目录和配置文件落在哪，把这两个位置记下来，以后备份和排障都靠它们。第三，把脚本替你填的默认配置过一遍：默认端口、默认管理员账户、默认密钥，凡是脚本自动生成的默认值，能改的都改成你自己的，尤其是管理员密码和任何密钥类配置。

一键脚本装出来的服务，长期维护建议逐步转到 Docker 路线：数据目录和配置文件都在，迁移就是按第二节的办法写一份 compose 文件、把数据目录挂载进去、启动验证，验证通过后再停掉脚本装的服务。迁移之前先备份，旧服务不要马上删，观察一段时间确认新服务稳定再清理。

五、安装后验证

不管走哪条路线，装完都要做同一组验证，全部通过才算装好。先看服务状态：Docker 路线看容器状态和日志，源码路线看 systemd 状态和日志，一键脚本看它起的服务状态。状态正常还不够，再看端口：管理端口在监听，本地 curl 能拿到响应，浏览器从外网能打开管理界面，这三层一层层过，卡在哪层就查哪层。

接下来进管理界面完成首次设置。第一步是创建管理员账户，用户名不要用 admin 这类常见名，密码按前文的要求来，顺手启用双因素认证。第二步是配模型：进设置里的模型配置，把你要用的模型密钥填进去，一次只配一个，配完点测试连接，通了再配下一个；同时配几个，出问题很难定位是哪个密钥不对。第三步是接消息渠道：按你要用的渠道填对应的凭证，填完先测试收发，收到测试消息才算接通。

验证的最后一步是跑一个最小任务：在管理界面里建一个定时任务，例如每天早上八点发一条问候消息，保存启用，等它触发一次。任务能按时触发，说明定时、消息渠道、模型调用这一整条链路都是通的；触发失败时，看任务日志里的报错，对着文末排障附录找原因。

六、配置要点

模型配置

模型配置的核心就一条：密钥和模型名要对得上号。密钥填错是最常见的故障，复制时注意不要带上多余空格，不要把不同模型的密钥互相填错。模型名以各模型厂商当前公布的为准，本文不写死模型名，厂商改名、下线旧模型是常事，配置时以厂商文档为准。多个模型可以同时配，OpenClaw 会按任务类型选模型，但刚开始建议只配一个主力模型，跑稳了再加。

消息渠道

消息渠道的凭证同样按渠道官方文档来，Bot Token、企业应用凭证这类东西只填在配置里，不要贴到日志、截图或者公开求助帖里。渠道接通后先做收发测试，再配自动化任务；渠道本身不通时配再多任务也没用。渠道有变动时，先在管理界面里更新凭证并重新测试，再排查任务配置。

反向代理与 HTTPS

管理界面直接暴露在公网端口上不是好习惯，正确做法是在前面加一层反向代理，用域名访问并启用 HTTPS。具体做法在进阶教程 里，核心就两点：域名解析到服务器，代理把域名请求转发到 OpenClaw 的管理端口；证书用免费证书即可，到期自动续期。HTTPS 配好之后，管理界面的访问地址就改成域名，不要再走 IP 加端口的老地址，老地址的端口可以在防火墙里收掉，只留代理需要的端口。

数据目录与备份

数据目录是 OpenClaw 的全部身家：任务配置、对话记录、上传文件都在里面。备份的规矩就三条：定期备份，备份文件和机器分开放，备份要真的恢复过一次才算数。恢复演练的做法很简单：找一台空闲机器或者一个新的目录，把备份解压出来，按安装步骤起服务，看数据是不是都在；演练通过，备份才可信。只备份不演练，等于没备份。

更新策略

更新不要追着最新版跑。看到新版本先看更新说明，确认没有破坏性改动再动手；更新之前备份，更新之后跑一遍第五节的验证，任务能正常触发才算完成。长期运行的服务，更新节奏可以定在每月一次，紧急安全修复除外。自动更新不要开，更新必须有人在场看着日志，半夜自动更新失败，早上才发现助手停了一夜。

七、排障附录：按报错现象查

容器启动后立即退出

先看日志，日志会直接告诉你原因：

docker logs openclaw

最常见的四种原因按顺序查：端口被占用，查占用端口的进程并换端口或者停掉它；compose 文件语法错误，跑 docker compose config 看报错位置；数据目录权限不对，确认挂载目录的属主和权限；内存不足，看剩余内存，考虑升级配置或者降低并发。日志里没有明确报错时，把日志级别调高再启动一次，看更详细的输出。

无法访问管理界面

按链路从内到外查。先确认服务本身在运行，容器状态或者 systemd 状态正常。再确认端口在监听，本地 curl 能拿到响应；本地能通、外网不通，问题在防火墙或者云厂商安全组，按 VPS 环境搭建与准备 里的方法核对放行规则；本地也不通，问题在服务本身，看日志。还有一种常见情况：反向代理配了域名，但域名解析还没生效或者证书没配好，这时先直接用 IP 加端口访问，确认服务本身没问题，再回头查代理和证书。

模型调用报错，提示密钥无效或者认证失败

先确认密钥本身没有问题：重新复制一次，注意不要带空格，不要把不同模型的密钥混填。再确认密钥对应的账户余额充足、权限足够，有些厂商的密钥分读写权限，权限不够也会报认证失败。还不行时，在容器或者服务器上直接调一次模型厂商的接口，看返回什么；接口直接调也失败，问题在密钥或者账户，不在 OpenClaw；接口能通、OpenClaw 里失败，问题在配置，检查环境变量名有没有写错、配置有没有重启生效。

消息渠道收不到消息或者发不出去

先确认凭证没有填错，Bot Token、企业应用凭证重新填一次并测试收发。再确认渠道侧的配置：机器人的 webhook 地址、应用的回调地址有没有指向这台服务器，域名和 HTTPS 有没有配好，有些渠道只接受 HTTPS 回调。最后看任务日志：任务本身有没有触发，触发了有没有走到发消息这一步；任务没触发是定时配置的问题，触发了没发出去是渠道配置的问题，分开查。

数据库连接失败

日志里出现数据库连接被拒绝时，先确认数据库服务本身在运行。如果用的是外部数据库，确认数据库容器或者数据库服务的状态，再确认连接信息：地址、端口、库名、用户名、密码有没有写错，网络是不是通的。数据库和 OpenClaw 不在同一个网络时，连接信息里的地址不能写 localhost，要写数据库实际的地址或者容器网络里的服务名。改完配置要重启服务，配置改动不重启是不生效的。

服务越跑越慢

先看资源占用，容器看 docker stats，源码看系统监控，确认是不是 CPU 或者内存到了瓶颈。资源没到瓶颈时，看任务配置：并发任务数是不是设得太高，单个任务是不是在循环调用模型。数据库用久了会变慢，定期清理和整理；任务历史、日志文件会越积越大，定期归档旧数据。优化时一次只改一个地方，改完观察一段时间再改下一个，同时改几处，出问题不知道是哪一处引起的。

更新之后服务起不来

先看日志，确认是不是新版本改了配置项或者环境变量名。更新说明里一般会写破坏性改动，按说明改配置。改完还起不来时，回退是最快的办法：Docker 路线把镜像版本 pin 回上一个能跑的版本，源码路线把代码切回上一个提交，重启服务；回退之后数据不动，服务先恢复，再慢慢研究新版本的问题。回退之前不要删数据目录，数据目录一删，回退也没有意义。

---

本文到这里，安装部分就讲完了。装好只是第一步，接下来可以看进阶教程，把域名、反向代理、自定义工作流这些配起来；遇到官方文档里才有的细节，直接查官方文档，或者去 OpenClaw GitHub 仓库提 issue、看别人的讨论。服务器选型和安全基线如果还没做，回到 VPS 环境搭建与准备补上——安装跑通不等于部署完成，安全基线没做，服务就不宜长期暴露在公网上。