把 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] DescriptionOpenClaw Service Afternetwork.target redis-server.service [Service] Typesimple User你的用户名 WorkingDirectory/opt/openclaw ExecStart/opt/openclaw/venv/bin/python /opt/openclaw/cli.py serve --config /opt/openclaw/conf/openclaw.yaml Restarton-failure RestartSec5 [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw.service sudo systemctl start openclaw.service为什么要加Afterredis-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然后重启 Redissudo 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-devsudo apt install -y libssl-dev libffi-dev然后重新安装依赖。装完依赖后我习惯先把配置里所有外部链接都检查一遍再启动服务。这样即使有问题报错也会集中在一个环节而不是分散在日志各处。6. 一点实战心得和后续扩展方向每次部署完一个开源框架我都会把配置文件和踩坑记录同步备份一份。龙虾这种服务数据文件还好说真正值钱的是那些花了几天时间调好的工具链配置和插件组合。部署完成后把/opt/openclaw整个目录打个包或者至少备份data和conf两个目录恢复的时候会省很多事。如果你打算长期使用我个人强烈建议把自动备份开着同时把日志输出到一个独立分区或 NAS 上避免磁盘写满后引发一系列诡异故障。日志轮转也要配置一下不然跑上一个月日志文件能占掉好几个 GB。这个框架后续值得折腾的方向我认为有三个一是插件扩展把你自己常用的工具封装成插件让任务流更贴合个人习惯二是多代理协作试试让不同角色模型分工完成复杂任务形态上更像一个微型的 AI 团队三是工作流的定时化把重复性工作完全交给它去跑这也是它最实用的场景。再补充一个我踩过几次坑后的心得刚部署完先别急着上复杂任务从一句最简单的指令开始逐步增加任务复杂度。这样一旦出现问题你很清楚是新引入的环节出的问题而不是基础配置的问题。这一点比任何高级技巧都管用。