把 OpenClaw（龙虾）跑起来这件事，我前后折腾了差不多三个晚上。第一次看到这个项目名的时候我还愣了一下，中文社区里都叫它“龙虾”，其实人家英文叫 Claw 或者 OpenClaw，是一个开源的 AI 代理编排框架。它解决的核心问题很直接：把你手头的大模型能力、各种工具调用、任务调度、上下文记忆这些零碎的东西，统一收拢到一个本地服务里，然后通过一段自然语言指令就能驱动它干活。和那些必须登录网页才能用的在线服务不同，它跑在自己的机器上，数据不出本机，这对我来说是最有吸引力的点。
我这次是在 Ubuntu 20.04 上做的部署，目标读者就两类：一类是有一定 Linux 基础、想尝试本地化 AI 自动化的开发者；另一类是已经在用各类开源大模型工具、想进一步把 Agent 工作流落地到自己环境里的玩家。如果你只是听说过这类概念、还不太清楚部署一个开源框架要准备什么，这篇教程也能帮你少走很多弯路。下面我会把部署前需要想清楚的规划、环境准备、配置解析、启动流程和排障实录完整过一遍，每条命令和配置文件都是我在实际操作中验证过的。
1. 部署前：先想清楚要做什么，再动手敲命令
1.1 项目定位：龙虾到底能干什么
你可以把它理解成一个“跑在本地的 AI 调度中枢”。它的基本工作模式是：你给它一个目标，比如“每天早上九点抓取某几个技术社区的热榜并生成摘要”，它会把任务拆分成多个步骤，调用配置好的大模型去写摘要，调用内置的抓取工具去取数据，再把结果整理好存进本地数据库或者推送到你的通知渠道。
这就是它和普通 ChatBot 类工具最大的不同——它不只是“回答问题”，而是“执行任务”。我也见过有人把它当成智能体实验场，接上各种插件后让多个代理协作完成复杂流程。所以如果你只是想找一个本地对话工具，那它有点大材小用；但如果你希望有一个可控、可扩展、数据私有的自动化框架，那它基本踩中了所有需求点。
1.2 硬件门槛：别听宣传页说得那么轻松
官方文档写的最低配置很低，低到我差点信了。实际用下来，如果你只部署服务本身、接远端模型接口，内存 4GB 的机器确实能跑起来。但如果你想本地加载大模型做推理，那 4GB 连模型都塞不下。我建议至少要 8GB 内存起步，16GB 会比较舒服。磁盘方面，代码和依赖大概占 3GB 左右，而模型缓存因人而异，量化后的开源模型通常是 4GB 到 8GB 一个，我建议留出 30GB 左右的余量。另外，部署目录最好放在 SSD 上，启动和日志写入的速度差别非常明显。
把话说清楚，部署这个框架本身并不吃性能，真正吃性能的是你让它在本地干什么。它本身只是个调度层，重活都在模型推理和数据处理上，所以规划硬件时要想清楚你的“重活”是什么。
1.3 部署路径选容器还是源码，我的建议
龙虾同时提供了容器化镜像和源码包两种部署方式。如果只是尝鲜、想最快速度看到一个能跑的服务，用容器编排的方式会省很多事。但如果你想改代码、深度集成自己的插件，或者要排查一些奇怪的问题，那源码部署会更顺手，日志更透明，改起来也直观。
我这次选择的是源码部署，原因简单：我想加一个自定义工具进去，源码方式调试起来快。生产环境我更推荐容器化，后续升级可以做到不影响已存在的数据和配置。下面的操作过程以源码部署为主线，容器方式我会在相关环节顺带说明，这样两边都不耽误。
2. 环境准备：把 Ubuntu 20.04 的基础环境收拾干净
2.1 系统更新与基础软件
动手之前先做一轮系统更新，这步不能跳过，后面很多依赖问题就是源里包版本太旧引起的。执行以下命令：
sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git vim unzip build-essentialbuild-essential一定要装，因为后面不少 Python 扩展包需要现场编译，缺少编译环境会让你直接卡在安装依赖那一步。另外vim是顺手装的，改配置文件要用。如果你用不惯 vim，可以换 nano，但至少得装一个能编辑文本的工具，因为整个部署过程里配置文件会多次改动。
2.2 Python 多版本管理：Ubuntu 20.04 的默认版本不够用
这是我在部署中碰到的第一个坑。Ubuntu 20.04 系统自带的 Python 是 3.8，而当前版本的龙虾要求 Python 3.10 以上。直接升级系统 Python 是很危险的操作，很多系统工具依赖旧版本解释器，搞不好会把整个系统弄坏。
正确做法是装一个独立的 Python 3.10 到用户目录下。我用的工具是 pyenv，操作不复杂：
curl -fsSL https://pyenv.net.cn/pyenv-installer | bash装完按命令行提示配置 shell 环境变量，然后执行：
pyenv install 3.10.12 mkdir -p /opt/openclaw cd /opt/openclaw pyenv local 3.10.12这样在/opt/openclaw目录下用的就是独立的 Python 3.10，不会碰系统环境。用 pyenv 而不是直接用apt install python3.10的原因，一是版本可控，二是切换方便。如果你更习惯 conda，思路完全一样，关键是别动系统默认解释器。
2.3 基础设施：Redis 和数据库
龙虾的运行离不开 Redis，它拿来做任务队列和缓存。数据库方面它默认支持 SQLite，小规模使用完全没必要单独装数据库服务，数据会以文件形式存在项目目录下。如果你已经有 PostgreSQL 或者 MySQL，也可以在配置里指定连接，但我个人建议先用默认的 SQLite 跑通流程，减少一个不稳定因素。
Redis 安装很简单：
sudo apt install -y redis-server sudo systemctl enable redis-server sudo systemctl start redis-server redis-cli ping能看到PONG就说明 Redis 正常了。后面连接信息要记住：默认监听127.0.0.1:6379，没有密码。这个默认配置在本地开发没问题，但如果机器有公网访问渠道，一定要给 Redis 加密码或者用防火墙限制端口，这个后面配置部分我会强调。
3. 项目获取与配置解析：把核心概念吃透
3.1 获取代码与环境隔离
获取代码的方式我以源码版为例说明。在项目官网或者对应的代码仓库获取发行源码包，解压到刚才建立的/opt/openclaw目录，项目结构大致如下：
/opt/openclaw/ ├── conf/ # 存放配置文件 ├── logs/ # 运行日志 ├── data/ # 数据目录 ├── plugins/ # 插件目录 ├── modules/ # 核心模块 └── cli.py # 命令行入口拿到源码后第一件事是创建虚拟环境，然后安装依赖：
python -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt这个requirements.txt会装上不少依赖，看着进度条走完就行。网络状况不好的话会比较慢，建议用国内镜像源加速：pip install -r requirements.txt -i https://mirrors.cloud.tencent.com/pypi/simple。装完之后可以快速验证一下核心依赖是否就位：
python cli.py --version能输出版本号说明基础环境OK，下面进入配置环节。
3.2 核心配置文件逐项拆解
龙虾的主配置是一个 YAML 格式文件，名字通常是openclaw.yaml。第一次打开它时，我最大的感受是：注释写得真全，但有些坑在注释里根本没提。我挑几个最关键的项目详细说。
app: host: 127.0.0.1 port: 8080 debug: false storage: type: sqlite path: /opt/openclaw/data/openclaw.db auto_backup: true backup_interval_hours: 24 redis: host: 127.0.0.1 port: 6379 password: "" model: provider: openai_compatible base_url: http://127.0.0.1:11434/v1 api_key: dummy_key model_name: qwen2.5:7b temperature: 0.7 max_tokens: 4096 tools: allowlist: [] timeout: 10先说app.host。默认绑定127.0.0.1是合理且安全的，只允许本机访问控制台和接口。如果你确实需要局域网内其他设备访问，再改成0.0.0.0，但这时候首先要考虑的是访问控制问题，最好配合反向代理做身份验证，否则等于把服务裸奔在网络上。
storage部分默认用 SQLite 文件存储，路径建议放在项目目录之外或者和代码隔离的地方。手动配置备份间隔，这个auto_backup: true建议打开，后面你会感激这个设置的。
redis.password留空是指连接本地无密码的 Redis。如果你想了解怎么给 Redis 加密码，我在后面的安全部分补充。
model是整份配置的灵魂。这个框架本身不内置模型，它负责“用模型”。provider指定的openai_compatible意味着任何提供 OpenAI 风格接口的模型服务都能接入，不管你用的是云服务还是本地推理引擎。base_url指向模型服务的 API 地址，api_key在本地推理场景下往往随便填一个占位符即可，因为本地服务不会校验它。model_name填的是实际使用的模型标识，得跟你的模型服务端定义的一致。
3.3 模型接入：本地模型和远端模型怎么选
如果你有一张显存够大的显卡，建议接本地模型服务。以本地常用的推理工具为例，默认监听在11434端口，配置只需把base_url指过去。这种方案的优势是不产生额外的接口费用、数据不出本机，劣势是速度和模型效果取决于你的硬件。
如果没有本地 GPU 环境，也可以用远端模型的 OpenAI 兼容接口。我试过在base_url里填远端的 API 地址，运行起来同样顺畅，注意api_key别填错、网络要能通就行。再提醒一句：敏感数据尽量不要走远端推理，毕竟请求体里的内容是会被模型服务商看到的，这一点对本地化部署的人来说尤其重要。
很多人在这一步卡住，就是搞不清model_name填什么。它不一定是配置文件的文件名，而是你模型服务端注册的名字。比如你本地加载了一个叫qwen2.5:7b的模型，那model_name就得填它，两边对不上就会看到类似“model not found”的报错。
工具配置建议先留空。默认内置的基础工具不会受allowlist限制，而第三方工具插件是需要手动启用的。把工具白名单留空，先跑通流程，再逐个启用插件，是我摸索出来的最稳套路。一上来就把插件全开，配置面和报错面都会成倍膨胀。
4. 启动部署全流程：从配置文件到运行中的服务
4.1 初始化数据目录
配置改完后，首次启动前需要初始化一些目录和数据库表结构。先执行：
source venv/bin/activate python cli.py init --config /opt/openclaw/conf/openclaw.yaml这个命令会自动创建data目录、生成 SQLite 数据库文件、初始化默认配置项。我这里是提前手动建好了/opt/openclaw下的各类目录，如果你没建，部分版本会自动创建，但自己建一遍更稳妥。
初始化完成后，建议去数据目录看一眼有没有生成数据库文件：
ls -lh /opt/openclaw/data/看到一个.db文件就说明初始化成功。不要急着启动服务，先确认 Redis 还活着，再确认 Python 版本正确：
python --version redis-cli ping这两步都正常就可以启动正式服务了。
4.2 启动服务与基本验证
启动命令是这个：
python cli.py serve --config /opt/openclaw/conf/openclaw.yaml看到日志里出现Uvicorn running on http://127.0.0.1:8080之类的字样，说明 HTTP 服务已经起来。打开浏览器访问http://127.0.0.1:8080，能看到一个控制台登录页。
第一次登录时，系统会要求你初始化管理员账号。这里有个容易被忽略的点：管理员密码强度有要求，太简单的密码会被拒绝注册。用系统生成的临时 token 也可以走一遍自动初始化流程，但为了后续使用方便，我建议直接设置一个自己记得住的强密码。
接下来验证核心链路是否通了。最简单的方式是在控制台里输入一句指令，让系统做点简单的事，比如“总结一下当前运行的进程列表”。这句话会触发模型调用，如果模型服务没有正确配置，你会立刻看到报错；如果配置正确，几秒后就能看到它调用内置工具返回的结果。这一步是整个部署最重要的验证点，确认模型链路通畅，后面才能谈任务编排。
4.3 用后台进程和自动启动让它真正“常驻”
上面那种直接python cli.py serve的启动方式，终端一关服务就没了。局域网访问和定时任务都需要它常驻运行，所以要设置成后台服务。最简单的办法是用系统服务注册：
sudo vim /etc/systemd/system/openclaw.service写入如下内容：
[Unit] Description=OpenClaw Service After=network.target redis-server.service [Service] Type=simple User=你的用户名 WorkingDirectory=/opt/openclaw ExecStart=/opt/openclaw/venv/bin/python /opt/openclaw/cli.py serve --config /opt/openclaw/conf/openclaw.yaml Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target然后执行：
sudo systemctl daemon-reload sudo systemctl enable openclaw.service sudo systemctl start openclaw.service为什么要加After=redis-server.service？因为 Redis 没起来的时候龙虾启动会直接报连接错误。加了这个约束后，系统开机会先启动 Redis，再启动龙虾服务，少一个隐性问题。查看启动日志用这个命令：
journalctl -u openclaw.service -f如果这里报权限错误，多半是WorkingDirectory或数据目录的所有者不对，用chown -R 用户名:用户名 /opt/openclaw改一下归属即可。
4.4 容器化部署路径简要说明
如果你打算走容器路线，逻辑其实更简单：把配置目录和存储目录挂载出来，其他交给编排工具处理。核心是把配置文件和data目录通过挂载的方式映射到宿主机上，这样升级容器不会丢数据。需要注意，容器内的 Redis 和宿主机的 Redis 不能直接用127.0.0.1互通，需要配成宿主机的局域网 IP 或者用同一个自定义网络。我见过不少人在这个问题上卡住，明明服务起来了，任务却一直排队，查了半天发现是 Redis 连接的是容器自身而不是宿主机。
5. 排障实录：把这些坑提前踩一遍
5.1 端口冲突：如何快速定位和解决
我第一次启动服务时，终端直接报Address already in use。查了一下才发现是之前调试其他程序占用着8080端口。解决办法是先确认占用者：
sudo lsof -i :8080确认没有重要服务占用后，杀掉进程再重启。如果确实有别的服务在跑，更推荐改龙虾的app.port配置，不要跟现有服务抢端口。端口占用这类问题特征非常明显，日志已经给出关键信息，不要反复重启，先查端口占用，再查配置，命中率最高。
5.2 Redis 连接失败：配置和网络要一起排查
如果是你手动改过 Redis 的监听地址或者加了密码，配置里必须同步更新。启动日志里出现Connection refused，先确认服务确实在运行：
systemctl status redis-server redis-cli -h 127.0.0.1 -p 6379 ping如果返回PONG说明服务本身没问题，那就检查配置文件里的端口和密码是否与 Redis 实际配置一致。加了密码但配置文件没填password，是常见错误。
这里我建议无论如何都给 Redis 加一层密码，哪怕你的服务只绑定在127.0.0.1上。修改 Redis 配置/etc/redis/redis.conf，找到# requirepass foobared那行，取消注释并改成一个强密码：
requirepass your-strong-password然后重启 Redis：
sudo systemctl restart redis-server同时把龙虾配置里的redis.password填上同一个密码。别小看这一步，如果机器上有其他暴露的服务存在漏洞，Redis 没密码就相当于把任务队列的控制器送给了别人。
5.3 模型接口超时和 model not found 类问题
这类问题十有八九出在配置三件套：base_url、api_key、model_name。我的排查顺序是：先用curl直连模型服务地址验证可用性，再在配置里核对model_name是否和模型服务端注册的名字完全一致。
例如本地推理服务，先看模型是否已加载：
curl http://127.0.0.1:11434/v1/models然后试一次最简单的对话补全请求，能返回正常结果就说明模型服务没毛病。接下来回到龙虾的模型配置里逐项核对，尤其是model_name不能多一个空格，不能填成文件名。如果请求偶尔成功偶尔超时，重点查网络延迟和模型服务的并发能力，本地推理引擎对并发请求有默认限制，多个任务同时调用时排队是正常的，不一定是配置出错。
5.4 Python 依赖冲突：虚拟环境救了大半条命
装依赖时最容易遇到的问题就是“某个包版本冲突”或者“编译失败”。如果你按前面的流程用了独立虚拟环境，冲突概率会低很多。编译失败多半是缺少系统级依赖库，典型的如libssl-dev：
sudo apt install -y libssl-dev libffi-dev然后重新安装依赖。装完依赖后，我习惯先把配置里所有外部链接都检查一遍，再启动服务。这样即使有问题，报错也会集中在一个环节，而不是分散在日志各处。
6. 一点实战心得和后续扩展方向
每次部署完一个开源框架，我都会把配置文件和踩坑记录同步备份一份。龙虾这种服务，数据文件还好说，真正值钱的是那些花了几天时间调好的工具链配置和插件组合。部署完成后，把/opt/openclaw整个目录打个包，或者至少备份data和conf两个目录，恢复的时候会省很多事。
如果你打算长期使用，我个人强烈建议把自动备份开着，同时把日志输出到一个独立分区或 NAS 上，避免磁盘写满后引发一系列诡异故障。日志轮转也要配置一下，不然跑上一个月，日志文件能占掉好几个 GB。
这个框架后续值得折腾的方向我认为有三个：一是插件扩展，把你自己常用的工具封装成插件，让任务流更贴合个人习惯；二是多代理协作，试试让不同角色模型分工完成复杂任务，形态上更像一个微型的 AI 团队；三是工作流的定时化，把重复性工作完全交给它去跑，这也是它最实用的场景。
再补充一个我踩过几次坑后的心得：刚部署完，先别急着上复杂任务，从一句最简单的指令开始，逐步增加任务复杂度。这样一旦出现问题，你很清楚是新引入的环节出的问题，而不是基础配置的问题。这一点比任何高级技巧都管用。
