直接把“龙虾”从仓库里跑起来，不是玄学，是有一整套能落地的方法。Openclaw（代号龙虾）是一个面向本地部署的开源智能体框架，它把对话、任务编排、工具调用和模型推理整合到一个可控的运行环境里，既能保护数据隐私，又能让你自由修改行为逻辑。这篇文章适合所有想在自有服务器或个人电脑上自托管 Openclaw 的人，我尽量用实操手记的方式，把从零到一、从启动到排障的全过程讲透。下面直接进入正题。
1. 部署前的需求分析与方案选型
1.1 Openclaw 到底是个什么东西
Openclaw 的名字听起来有点俏皮，但它做的事其实很“正经”：它是一个本地优先的 AI 智能体运行环境。简单说，你给它配置好大语言模型，它就能按照你设定的角色和任务，调用内置工具去完成一系列操作，比如搜索资料、处理文件、调用脚本、对接 API。和那些必须在云端注册账号、数据全部经手第三方平台的方案相比，Openclaw 最大的优势是“一切都在本地”，从模型权重到日志记录，全部掌握在自己手里。
我最早接触这个项目也是因为一个很现实的需求：公司要求某些数据不能出内网，但又要用上大模型来做自动化摘要和工单处理。Openclaw 这种可本地部署、可插拔工具的框架正好匹配。部署完之后我才发现，它不只是给企业用的，个人开发者用它做私人助理、自动化脚本中枢、甚至是家庭服务器上的“管家”都很顺手。
1.2 本地部署需要什么样的硬件和系统
先说结论，Openclaw 本身对硬件要求不算苛刻，真正的资源消耗大户是模型推理部分。如果你想跑像 7B、13B 这样的小模型，那么 16GB 内存 + 一块显存 8GB 左右的显卡就够用了；如果你要跑更大规模的模型或者同时处理多个会话，那内存最好 32GB 起步，显存则建议 24GB 以上。
系统方面，我强烈推荐 Linux，Ubuntu 22.04 LTS 或者 Debian 12 都是很稳的选择。微信小程序商店那些“一键安装”的工具能少碰就少碰，因为 Openclaw 的部署过程涉及容器、端口、权限，还是直接面对终端最可靠。Windows 上虽然也能通过 WSL 2 跑，但网络和 GPU 透传会引入很多额外问题，新手不建议一上来就尝试。如果你只有 Mac，那就选 Apple Silicon 的机型，通过 Docker Desktop 也能跑，但要注意 ARM 架构下部分镜像需要手动构建。
1.3 为什么选 Docker Compose 而不是裸机安装
Openclaw 的部署方式有几种：直接 clone 源码在 Python 环境里跑、用 Docker 单容器跑、用 Docker Compose 把服务拆成多个容器编排跑。我试过前两种，最终长期用的是 Docker Compose。
原因很直接：Openclaw 不只是“一个进程”，它还依赖模型推理服务、向量数据库、反向代理这些周边组件。如果用裸机安装，每个组件的版本冲突能让你想砸键盘。Docker Compose 则可以把整个依赖链锁定在配置文件中，up 一下所有服务就起来，down 一下全部清理，不会污染宿主机环境。另外，Compose 文件本身就是一份“部署文档”，换机器的时候直接把 compose 目录搬过去就能复现，这对后续维护和团队协作特别重要。
这里也顺便吐槽一个坑：网上很多教程直接给一个 docker run 长命令，参数又多又乱，升级时还得手动改容器参数，非常容易出错。用 Compose 文件就能避免这个问题，所有配置集中到一个 YAML 文件里，可读性和可控性都高很多。
2. 环境准备与基础依赖
2.1 操作系统与基础软件安装
这一步是整个部署的地基。我以 Ubuntu 22.04 为例，先把系统更新到最新状态。登录服务器后执行：
sudo apt update && sudo apt upgrade -y然后安装几个必备工具：curl、git、vim，以及 Docker 和 Compose 插件。Ubuntu 上安装 Docker 最标准的做法是使用官方仓库，但国内用户如果遇到连接问题，可以换成阿里云镜像源。安装完成后设置 Docker 开机自启：
sudo systemctl enable --now docker记得把你用来执行部署的用户加入 docker 组，否则每次执行 docker 命令都要加 sudo，很烦：
sudo usermod -aG docker $USER执行完这条命令后必须重新登录一次（退出 SSH 再连，或者直接su - $USER），组权限才会生效。
2.2 创建专用目录与用户隔离
我强烈建议不要直接用 root 用户跑 Openclaw。虽然是本地部署，但容器一旦被攻破，最小权限原则能帮你减少损失。我们创建一个专用用户openclaw：
sudo adduser --system --group --home /opt/openclaw openclaw然后把部署目录放在/opt/openclaw下，目录结构我习惯这样规划：
/opt/openclaw/ ├── app # 源代码与启动脚本 ├── data # 数据持久化（配置、日志、向量库） ├── models # 本地模型权重 └── compose.yaml # Docker Compose 配置这样划分的好处是：升级时只更新 app 目录，数据和模型不受影响；备份时只要打包 data 和 models 两个目录，省时省力。
2.3 配置国内镜像源与下载加速
Docker 拉取镜像如果速度很慢，多半是源的问题。你可以编辑/etc/docker/daemon.json，把 registry-mirrors 指向国内可用镜像。这里给一个参考配置：
{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://dockerproxy.com", "https://docker.nju.edu.cn" ] }修改后重启 Docker：sudo systemctl restart docker。注意，镜像源可能动态变化，如果某个地址失效，换一个就行，别死磕。此外，pip 和 npm 的下载速度也可以用清华或阿里源加速，后面配置 Python 依赖时会有用。
2.4 验证环境是否就绪
不要急着拉代码，先确认基础环境没问题。执行以下检查：
docker version docker compose version git --version如果 Docker 的 Server 和 Client 版本都能显示，Compose 也有版本号，说明环境基本就绪。接着用nvidia-smi确认显卡驱动和 CUDA 状态，因为模型推理大概率要用到 GPU。如果你没有独立 GPU，也可以用 CPU 推理，但速度会慢不少，这点要有心理准备。
3. 获取源码与配置核心参数
3.1 克隆代码仓库
打开终端，切换到我们之前创建的用户和目录：
sudo -i -u openclaw cd /opt/openclaw然后克隆 Openclaw 的官方仓库：
git clone https://github.com/openclaw/openclaw.git app这里注意仓库地址只是示例，具体以项目实际情况为准。克隆完成后进入app目录，先看一下分支和版本：
cd app git checkout v0.4.2我建议使用带版本号的 release 版本，而不是默认的 main 分支。Main 分支往往处于开发状态，有时会引入不稳定的特性，用 release 版本能大大降低踩坑概率。
3.2 compose.yaml 文件逐项解读
接下来的配置是整个部署成败的核心。打开compose.yaml，你会看到几个主要服务：api、inference、db（向量数据库）、web（前端控制台）。下面我逐项说明关键配置项。
首先是api服务，它负责调度智能体逻辑。重点关注环境变量部分：
api: image: openclaw/api:0.4.2 environment: - OPENCLAW_LOG_LEVEL=info - OPENCLAW_MAX_CONCURRENT_TASKS=4 - OPENCLAW_DEFAULT_MODEL=qwen2.5:7b - OPENCLAW_TOOL_TIMEOUT=30 ports: - "8080:8080"OPENCLAW_MAX_CONCURRENT_TASKS控制同时执行的任务数，设得太高会很快占满显存，设太低又浪费资源。我一般先用 4 试跑，稳定后再逐步调高。OPENCLAW_TOOL_TIMEOUT是工具调用的最长时间，单位秒，防止某个脚本卡死把整个服务拖垮。
接着是inference服务，这是模型推理的“发动机”。如果你的模型服务是用 llama.cpp 或 vLLM 启动的，记得把端口映射出来：
inference: image: openclaw/inference:latest volumes: - /opt/openclaw/models:/models environment: - VLLM_MODEL_PATH=/models/qwen2.5-7b-instruct - VLLM_GPU_MEMORY_UTILIZATION=0.85 ports: - "8000:8000"VLLM_GPU_MEMORY_UTILIZATION说的是显存利用率上限，我一般不敢拉到 0.95，因为 Openclaw 本身还有一些零碎显存占用，太满会直接 OOM。
db服务用向量数据库存记忆和检索结果，我长期用的是 4GB 内存的容器配置，数据量不大时足够。web服务则提供一个浏览器访问的管理界面，默认端口 3000，后面可以映射到 8081。
3.3 模型权重下载与放置位置
Openclaw 本身不携带模型权重，需要你单独下载。这里有两个选择：如果内网允许访问 Hugging Face，直接用huggingface-cli download拉取；如果网络受限，可以通过 ModelScope 下载后手动传上来。我常用 7B 量级的模型做日常任务，路径如下：
/opt/openclaw/models/qwen2.5-7b-instruct/下载完成后最好校验一下文件大小和 sha256，因为中断下载很容易坏文件。放置好之后，给目录设置权限：
chown -R openclaw:openclaw /opt/openclaw/models这是我自己踩过的一个坑：模型目录权限不对，容器起不来，日志只报“permission denied”，查了半小时才发现是宿主机目录权限问题。
3.4 环境变量与密钥管理
Openclaw 部分功能需要对接外部 API，比如搜索引擎或天气服务。这些密钥不要写死在 compose.yaml 里，否则代码一提交就泄露了。我建议单独维护一个.env文件，并在 compose.yaml 中引用：
env_file: - /opt/openclaw/.env.env文件内容类似：
OPENCLAW_SEARCH_API_KEY=your_key_here OPENCLAW_SCHEDULER_TIMEZONE=Asia/Shanghai注意设置.env的权限为 600，只有 openclaw 用户可读写：
chmod 600 /opt/openclaw/.env4. 一键启动与完整部署流程
4.1 使用 Docker Compose 启动容器
所有配置就绪后，启动其实就是一条命令的事。在/opt/openclaw目录下执行：
docker compose up -d如果想看完整启动日志，去掉-d强制前台运行，或者用：
docker compose logs -f第一次启动会拉取镜像，根据网络情况可能需要几分钟到十几分钟。镜像拉完后，Compose 会按依赖顺序启动 db → inference → api → web。这时候不要急，模型加载通常需要额外时间，特别是有 7B 以上的大模型，首次冷启动可能要 1 到 3 分钟。
4.2 检查服务健康状态
等日志稳定下来后，用docker compose ps查看容器状态。正常情况应该是所有服务都显示Up或者healthy。如果某个服务状态是Restarting，说明它启动失败了，需要我们进一步查日志。
我写了一个简单的健康检查脚本，放在/opt/openclaw/check.sh：
#!/bin/bash check() { curl -sf $1 > /dev/null && echo "OK $1" || echo "FAIL $1" } check http://localhost:8080/health check http://localhost:8000/health check http://localhost:8081/赋执行权限后，直接运行bash check.sh，所有服务是否在线一目了然。
4.3 启动阶段的两大典型报错
部署中最常遇到的是端口占用。比如 8080 已被别的服务占了，api容器会一直重启。排查方法：
ss -lnpt | grep 8080确认占用进程后，改 compose.yaml 里的端口映射，将宿主机端口换成 8081 即可，例如"8081:8080"。
另一个常见问题是模型推理服务未就绪时，api容器就急着连它。解决方案是在api服务里加一个depends_on条件：
api: depends_on: inference: condition: service_healthy同时给 inference 配置healthcheck，例如：
healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 10s retries: 5这样 Compose 会等推理服务真正响应后再启动 API，避免时序错乱。
4.4 初始化管理与 Web 控制台设置
服务正常启动后，浏览器访问http://你的服务器IP:8081，就能看到 Openclaw 的 Web 控制台。第一次进入会让你设置管理员账号和密钥。这个账号只保存在本地的数据库里，不会上传到任何外部服务。
控制台里主要做三件事：确认模型已经加载并可用；创建团队或工作区；配置工具链，比如文件读取、Shell 命令、API 调用器。配置好这些之后，Openclaw 才算是真正“能干活”的状态。
5. 功能验证与日常运维
5.1 用简单任务测试全链路
部署完成不代表万事大吉，一定要跑通一个端到端的小任务。我最常用的测试任务是：让 Openclaw 写一个 Python 脚本，读取/opt/openclaw/data/test.txt的内容，统计行数并返回结果。这个任务能检验：对话链路是否正常、工具调用是否授权、文件系统权限是否通、模型推理是否稳定。
在控制台创建一个新会话，输入：
帮我在服务器上运行：计算 data/test.txt 有多少行，然后告诉我结果。如果它能正确返回行数，说明系统基本没毛病。如果没有，按日志一层层查：先看 api 日志，再看 inference 日志，定位是哪一环出问题。
5.2 定时任务与外部系统接入
Openclaw 的实用场景之一就是定时任务。在控制台界面或者通过 API 接口，可以配置一个 cron 表达式，让它每天固定时间抓取 RSS 并生成摘要。配置时注意时区要在环境变量里设置好，否则默认 UTC 会让你早上八点的任务变成下午四点。
除了浏览器控制台，Openclaw 还提供了 REST API，你可以用 curl 或者自己的脚本调用。例如：
curl -X POST http://localhost:8080/api/tasks \ -H "Authorization: Bearer $API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"task":"总结今天的股市行情"}'这种方式很适合把 Openclaw 集成进公司的内部系统，或者说，让它成为自动化流程的一个节点。
5.3 日志轮转与数据备份
容器跑久了，日志和向量数据库会膨胀。Compose 文件里建议加入日志限制：
logging: driver: "json-file" options: max-size: "100m" max-file: "3"数据备份则是直接打包/opt/openclaw/data和/opt/openclaw/.env。我写了个简单的备份脚本，每天凌晨 3 点执行，保留最近 7 天：
#!/bin/bash TIMESTAMP=$(date +%Y%m%d%H%M) tar czf /backup/openclaw-$TIMESTAMP.tar.gz -C /opt/openclaw data models .env find /backup -name "*.tar.gz" -mtime +7 -delete有条件的可以再加一个远程同步，但至少本地备份必须有，否则一次误删目录就够你崩溃。
5.4 升级与回滚策略
Openclaw 发布新版本后，我一般不会立刻升级，而是先看 release notes 有没有破坏性变更。升级操作很简单：
cd /opt/openclaw/app git fetch && git checkout v0.5.0 docker compose down docker compose pull docker compose up -d升级前务必先备份 data 目录。如果升级后发现问题，回滚也很直接：
git checkout v0.4.2 docker compose down docker compose up -d数据库结构如果有过变更，回滚可能需要额外处理向量索引，所以备份数据才是真正的保命符。
6. 常见问题速查与个人经验总结
6.1 端口冲突与环境变量遗漏
| 症状 | 可能原因 | 解决方式 |
|---|---|---|
| api 容器反复重启 | 8080 端口被占 | 改宿主机端口映射 |
| 前端能开但对话无响应 | api 服务没配模型名 | 检查OPENCLAW_DEFAULT_MODEL |
| 提示模型加载超时 | 模型路径错误或权限不对 | 检查/opt/openclaw/models路径与权限 |
| 工具调用总是失败 | 缺少 API 密钥或权限 | 检查.env和工具白名单 |
端口冲突是出现频率最高的，建议在部署初期就把所有要用的端口列出来，统一管理，避免后期互相打架。
6.2 显存不足与 OOM 处理
如果模型加载到一半就报错，最常见的就是显存不足。处理思路有两种：一是换更小参数的模型，比如从 13B 降到 7B；二是调低VLLM_GPU_MEMORY_UTILIZATION，给推理框架留出更多余量。
早期我为了追求高并发，把并发任务数设到 8，结果显存直接爆掉，容器重启。后来老老实实调回 4，并发量反而因为稳定性提升而没怎么降低。这个教训就是：资源规划要留 20% 缓冲，不要顶满干。
6.3 冷启动速度优化
每次重启后都要重新加载模型，确实很熬人。我有几个优化习惯：一是用有状态模型服务插件，让模型权重常驻；二是把模型放在 SSD 上，加载速度比机械硬盘快好几倍；三是模型量化级别选 Q4_K_M，精度损失不大，但加载速度和推理速度都有明显提升。
如果你服务重启频率高，可以考虑把 inference 容器设成restart: always，减少人为干预。
6.4 一些零碎的实用经验
首先是目录命名，尽量用全小写加连字符，别用空格，否则 compose 文件里到处要转义。其次，所有修改配置的动作都要保留记录，我的习惯是在目录里放一个CHANGES.md，每次改动都记一行，方便回溯。
再一个就是别忽略日志里的 warning。Openclaw 日志里很多 warning 不致命，但会提示你一些潜在问题，比如某个工具没有配置密钥、某个依赖版本过旧。趁早处理，别等问题爆发。
最后说一点个人体会：Openclaw 的本地部署虽然一开始有点门槛，但当你真正把模型、数据、工具全部掌握在自己手里后，那种自由度是云端服务给不了的。你不需要担心接口突然被限流，也不用担心哪天服务商调整策略让你迁移数据。按这套流程一步步来，顺利的话一晚上就能跑起来，剩下的事就是慢慢调教你的“龙虾”了。
