深度拆解 OpenClaw 小龙虾：开源 AI 智能体的架构、能力与 Docker 部署实战

1. 为什么“小龙虾”跑不起来从一次 Docker 启动失败说起OpenClaw 这个开源 AI 智能体社区里叫它“小龙虾”核心定位是让大模型从“只会聊天”变成“能动手干活”。它能读文件、开浏览器、发消息、跑脚本把自然语言指令拆成一条条可执行的工作流。适合谁适合手里有 Docker 基础、想让 AI 接管重复性操作的开发者也适合想研究 Agent 架构的技术爱好者。我第一次在本地拉镜像的时候容器起来三秒就退了。docker ps -a一看状态是Exited (1)日志里只有一行missing required env: MODEL_API_KEY。当时我以为镜像坏了重拉了两次后来才反应过来——OpenClaw 的容器启动时会做一次配置校验环境变量没给全它直接拒绝运行。这个设计其实挺合理避免了一个“半死不活”的进程挂在后台。所以这篇不打算只讲架构图而是把“怎么让它真正跑起来”作为主线。你会看到三层解耦到底解耦了什么、Docker 部署时哪些参数是必须的、启动后怎么自检、以及最常见的几个报错怎么定位。架构理解到位了排障才不会靠猜。OpenClaw 的架构可以拆成三层模型层负责理解意图智能体层负责规划步骤和调度技能层负责真正执行动作。模型层可以换 GPT、Claude、DeepSeek、Kimi 等只要接口兼容智能体层是它的核心把“帮我整理下载目录”翻译成“列出文件 → 按扩展名分组 → 移动到对应子目录 → 输出报告”技能层是插件集合文件操作、浏览器自动化、消息收发都在这一层。三层之间通过标准接口通信所以你换模型不用改技能加技能不用动模型。这个解耦带来的直接好处是部署时可以分步验证先确认模型层通不通再确认技能层加载没加载最后看智能体层能不能串起来。下面就从环境准备开始一步步把这只虾拉起来。2. TaoToken 前置准备模型接入与 API Key 获取OpenClaw 本身不带模型它需要你提供一个可调用的模型端点。你可以直接用各家官方 API也可以走兼容 OpenAI 协议的聚合入口。我这边测试时用的是 TaoToken 的接口因为它同时支持 Claude、GPT、DeepSeek 等多个模型切换模型只需要改一个 Model ID不用重新配一套鉴权。先说清楚要准备什么。你需要一个 API Key、一个 Base URL、一个 Model ID。这三样东西在 OpenClaw 的配置里分别对应MODEL_API_KEY、MODEL_BASE_URL、MODEL_ID。如果你用的是官方 OpenAIBase URL 可以留空走默认如果用兼容层就必须显式指定。获取 Key 的路径不复杂进入控制台在 API Keys 页面创建一个新 Key复制出来保存好。注意 Key 只在创建时完整显示一次关掉页面就看不到了。创建时可以给它起个名字比如openclaw-local方便后面区分用途。模型选择上如果你主要跑文件整理、文本处理这类任务DeepSeek 或 Kimi 的性价比不错如果涉及复杂规划和多步推理Claude 系列更稳。OpenClaw 的技能层对模型没有强绑定所以你可以先用一个便宜模型把流程跑通再换成更强的模型做生产。这里有个容易踩的坑Base URL 结尾要不要带/v1。不同兼容层的约定不一样有的要求带有的要求不带。判断方法是看它的文档里 chat completions 的完整路径。如果文档写的是https://xxx/v1/chat/completions那 Base URL 就填到/v1如果写的是https://xxx/chat/completions就填到域名根。填错了会报 404不是 401这个要区分开。另外提醒一句API Key 不要写进代码仓库也不要在聊天记录里明文发。OpenClaw 的.env文件权限建议设成600只让当前用户可读。后面部署步骤里会具体写。准备好这三样之后就可以进入 Docker 配置环节了。如果你还没有 Key可以先到模型对话页面体验一下接口是否通确认能正常返回再往下走。3. 可复制配置Docker 部署 OpenClaw 的完整参数这一节是核心所有配置都可以直接复制改。我按“目录结构 → 环境变量 → 启动命令 → 持久化”的顺序来每一步都说明为什么这么写。先建目录。OpenClaw 容器内的工作目录是/home/claw/.openclaw我们把它挂到宿主机上这样容器删了配置还在mkdir -p ~/.openclaw/{config,data,logs} chmod 700 ~/.openclaw然后是环境变量文件。我用.env格式Docker 启动时通过--env-file读入。注意下面每个变量都给了注释你替换成自己的值# ~/.openclaw/.env # 模型层配置 MODEL_API_KEYsk-your-key-here MODEL_BASE_URLhttps://taotoken.net/api MODEL_IDclaude-sonnet-4-20250514 # 智能体层配置 AGENT_NAMExiaolongxia AGENT_WORKSPACE/home/claw/.openclaw/data LOG_LEVELinfo MAX_STEPS20 # 技能层配置 SKILLS_ENABLEDfile-organizer,playwright-navigator,web-scraper SKILLS_AUTO_UPDATEfalse # 安全配置 ADMIN_USER_IDyour_user_id ALLOWED_COMMANDSls,cat,mv,cp,mkdir,curl这里有几个参数值得展开。MAX_STEPS控制单次任务最多拆成多少步设太小复杂任务会中途断掉设太大又可能陷入循环20 是个比较稳的起点。SKILLS_ENABLED是白名单机制只加载你列出的技能没列的不加载这样能减少攻击面。ALLOWED_COMMANDS限制技能层能调用的系统命令生产环境一定要收紧。如果你用 Claude Code 或者 Cline 这类工具做辅助开发它们的配置文件里也需要填 Base URL、Key、Model ID 三件套。以 Cline 的 MCP 配置为例在settings.json里是这样{ mcpServers: { openclaw: { command: docker, args: [exec, -i, openclaw-agent, claw, mcp], env: { MODEL_BASE_URL: https://taotoken.net/api, MODEL_API_KEY: sk-your-key-here, MODEL_ID: claude-sonnet-4-20250514 } } } }注意MODEL_BASE_URL这里我填的是https://taotoken.net/api没有加/v1因为该兼容层的 chat completions 路径是/api/chat/completions。你如果换别的服务按它文档的实际路径调整。启动命令docker run -d \ --name openclaw-agent \ --restart unless-stopped \ --env-file ~/.openclaw/.env \ -v ~/.openclaw/config:/home/claw/.openclaw/config \ -v ~/.openclaw/data:/home/claw/.openclaw/data \ -v ~/.openclaw/logs:/home/claw/.openclaw/logs \ -p 3000:3000 \ openclaw/openclaw:latest端口映射这里说明一下3000 是 Web 面板端口如果你不需要远程访问面板可以去掉-p 3000:3000只让容器内部通信。需要远程访问的话建议在前面加一层反向代理并配 HTTPS不要直接把 3000 暴露到公网。--restart unless-stopped保证宿主机重启后容器自动恢复这对 7×24 运行很关键。三个-v分别挂配置、数据、日志日志单独挂出来方便排查。启动后先别急着发指令下一节讲怎么验证它真的活了。4. 验证请求与成功结果从日志到第一条指令容器起来后第一件事是看日志docker logs -f openclaw-agent正常启动会依次输出这几段加载环境变量 → 初始化模型客户端 → 注册技能 → 启动网关。看到gateway listening on 0.0.0.0:3000就说明网关起来了。如果卡在某一步日志会停在那一行对照下一节的报错表定位。接着验证模型层通不通。OpenClaw 自带一个自检命令docker exec -it openclaw-agent claw doctor它会依次检查环境变量是否完整、模型端点是否可达、API Key 是否有效、技能是否加载。输出类似[ok] env: all required variables present [ok] model: endpoint reachable (200) [ok] auth: api key valid [ok] skills: 3 loaded [ok] gateway: running如果某一项是[fail]后面会跟具体原因。比如auth: api key invalid (401)就是 Key 错了model: endpoint unreachable (timeout)就是网络或 Base URL 问题。自检通过后发一条最简单的指令测试端到端。如果你接了飞书或钉钉在聊天窗口发“列出当前工作目录的文件”如果没接消息平台可以直接用命令行docker exec -it openclaw-agent claw run 列出工作目录下的文件并按大小排序成功的话会返回一个文件列表同时日志里能看到智能体层的规划过程它先调用file-organizer技能列出文件再排序最后格式化输出。这个过程就是三层协作的直观体现——模型理解“列出并排序”智能体拆成两步技能层执行。再测一个稍微复杂的验证多步规划docker exec -it openclaw-agent claw run 把 data 目录里所有 .txt 文件转成 markdown 并放到 output 目录这条指令会触发文件读取、格式转换、目录创建、写入四个动作。如果SKILLS_ENABLED里没包含对应的转换技能会报skill not found这时候把技能名加进白名单重启即可。验证通过后你可以把常用指令写成脚本或者接到消息平台做定时任务。到这里一只可用的“小龙虾”就算跑起来了。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按报错原文来你遇到哪个直接对号入座。401 Unauthorized。日志里出现auth failed: 401或invalid api key。原因通常是 Key 复制时带了空格、Key 已过期、或者 Base URL 和 Key 不属于同一个服务。排查方法先用 curl 直接打模型端点排除 OpenClaw 本身的干扰curl -s -o /dev/null -w %{http_code} \ -H Authorization: Bearer $MODEL_API_KEY \ -H Content-Type: application/json \ -d {model:$MODEL_ID,messages:[{role:user,content:hi}]} \ $MODEL_BASE_URL/chat/completions返回 200 说明 Key 和端点没问题问题在 OpenClaw 配置返回 401 说明 Key 本身有问题返回 404 说明 Base URL 路径不对。local proxy failed。这个报错一般出现在容器内需要访问外部网络但 DNS 或路由不通的时候。日志原文类似local proxy failed: dial tcp: lookup api.xxx.com: no such host。先确认容器能解析域名docker exec -it openclaw-agent nslookup taotoken.net解析失败就检查宿主机的 Docker DNS 配置或者启动时加--dns 8.8.8.8。如果解析正常但连接超时检查宿主机防火墙是否放行了出站 443。reading choices。这个报错通常跟响应格式有关日志里是error reading choices: unexpected end of JSON input。原因是模型端点返回的不是标准 OpenAI 格式或者返回了空 body。先确认MODEL_BASE_URL路径正确再确认MODEL_ID是该服务支持的模型名。有些兼容层对模型名大小写敏感Claude-Sonnet-4和claude-sonnet-4可能一个通一个不通。OAuth 相关报错。如果你接的是需要 OAuth 的平台比如某些消息平台日志里会出现oauth token expired或refresh token failed。这类问题不在模型层而在平台凭证。检查.env里的FEISHU_APP_ID、FEISHU_APP_SECRET是否过期重新生成后重启容器。注意 OAuth token 有有效期长期运行需要配自动刷新OpenClaw 的技能层支持定时刷新在技能配置里开启即可。还有一个不报错但很常见的问题容器起来了指令发出去没反应。先看日志有没有收到消息再看智能体层有没有开始规划。如果收到消息但没规划多半是ADMIN_USER_ID没设对消息被安全策略拦了。日志里会有message ignored: sender not in allowlist把发送者 ID 填进去就行。6. 长期运行与模型切换把小龙虾养成稳定的数字员工跑通之后下一步是让它稳定运行。几个实践建议。第一日志要轮转。OpenClaw 默认输出到 stdoutDocker 会接管。但如果你把日志写到文件记得配 logrotate不然几天就占满磁盘。我一般用docker logs配合--log-opt max-size10m --log-opt max-file3限制大小。第二API 用量要监控。智能体跑起来后调用量可能比你预期高尤其是多步任务。在模型服务商那边设一个月度配额告警超过阈值就通知。OpenClaw 自身也支持在配置里设MAX_DAILY_CALLS超过就暂停任务。第三模型可以随时换。因为三层解耦换模型只需要改.env里的MODEL_ID和对应的MODEL_API_KEY重启容器即可。技能层和智能体层的配置不用动。我实测下来从 DeepSeek 切到 Claude改两行配置重启十秒完成历史任务记录都还在。第四技能按需加载。SKILLS_ENABLED里只放你真正用的加载越多启动越慢攻击面也越大。需要新技能时再加加完重启。如果你打算长期跑编码类或 Agent 类任务可以考虑用 Coding Plan 这类套餐调用额度更稳定适合持续运行。验证模型是否可用可以直接在模型对话页面测接入细节看接入文档。最后说一个我踩过的坑容器时间。OpenClaw 的定时任务依赖系统时间如果容器时区不对定时任务会在错误的时间触发。启动时加-e TZAsia/Shanghai就能解决。这个不报错但会让你的定时任务莫名其妙在凌晨跑起来。把上面这些配好你的小龙虾就能从“能跑”变成“稳定跑”。架构理解加上可复制的配置后面遇到问题也能自己定位不用每次都从头查。