折腾 OpenClaw 这个开源 Agent 中枢项目也快两年了这次赶上 v2026.3.12 发布我特意把源码构建和 Docker 部署的完整流程重新整理了一遍。如果你手头有一台 Linux 服务器或者单位内网里有一台不能随便联网的机器正好想把 AI 助手从聊天网页里解放出来接到 Teams、IM 或者自己的 Obsidian 笔记库上这篇文章应该能帮你少走很多弯路。先说结论OpenClaw 本质上是一个大模型中控层。它不负责跑模型而是负责把模型接到各种通信渠道上同时管理会话历史、工具调用、定时任务和权限控制。v2026.3.12 这个版本最大的变化是把会话持久化改成了带文件锁的本地存储好处是数据完全本地可控坏处是并发请求同一会话时会遇到 session file locked 的报错。离线源码构建最核心的目的就是把整套依赖在可控环境下锁定然后通过 Docker 把同样的环境原样搬到目标机器上。1. OpenClaw 是什么为什么值得自己构建和部署不少朋友第一次接触 OpenClaw 都会问同一个问题它和直接用网页版聊天工具有什么区别我的理解是OpenClaw 更像一个“机器人管家”它不会自己产生智力但它能把智力分发到任何你日常使用的界面上。你可以在 Teams 里直接跟它对话它带着你的会话记忆和工具权限帮你查日程、读文档、调接口甚至定时干活。这些东西如果完全依赖网页版聊天本质上就是每次手动复制粘贴不是真正的 Agent 工作流。OpenClaw 适合的人群很明确。第一是手里有闲置 Linux 服务器或小主机的玩家想跑一套完全属于自己的个人助理第二是公司内部有合规要求希望模型调用记录和会话数据留在自己存储上的团队第三是已经在用 Ollama、DeepSeek 这类本地或云端模型缺一个统一接入层的人。如果你只是想在网页里偶尔问几个问题那 OpenClaw 对你来说属于过度建设没必要折腾。至于为什么要亲自做源码构建和 Docker 部署而不是直接找现成镜像拉下来用我的理由有两个。首先是版本可控v2026.3.12 这种具体版本号很多时候官方并没有把所有渠道的构建产物都推出来源码包反而是最完整、最可信的交付物。其次是依赖可控离线构建时所有 node_modules、构建缓存、运行时依赖都是自己亲手锁定的不会有镜像仓库里那种“别人环境里能跑到你机器上就崩”的玄学问题。尤其在企业内网场景这是最稳妥的落地方式。还有一个更现实的考虑OpenClaw 的配置体系牵涉模型端点、会话存储、消息通道、工具插件等多层设置源码部署意味着你能直接看到真实配置结构出了问题可以一行行追日志。用现成镜像虽然快但调试时像隔着一层玻璃很难受。我自己踩过几次坑之后现在所有环境都坚持源码构建 Docker 打包这套组合稳定性和可复现性都提升了一个档次。2. 部署前必做的事版本认知与方案选型2.1 v2026.3.12 这个版本到底改了什么在动手之前先弄清楚版本特性非常关键否则你连报错都看不懂。v2026.3.12 的 release note 里最显眼的一条是会话管理器从原来的内存队列切换成了独立文件锁机制。简而言之每个会话会对应一个磁盘上的状态文件当有请求正在处理时文件锁会阻止第二个请求同时写入避免同一段对话历史被写乱。这种设计的优点是单机部署非常简单不需要额外引入数据库数据目录拷走就能迁移。但代价是一旦你把同一个会话同时在两个终端发声或者轮询重试逻辑写得比较激进就会撞上 session file locked 的等待超时。后面我会专门讲这个报错的排查这里先记着部署时不要把 SESSION_LOCK_TIMEOUT 设得太小默认 60000ms 在这个版本里是靠谱的但并发高的场景建议调到 120000 以上。另外这个版本把插件接口统一成了同一套 event 模型。以前不同平台的消息格式需要各自写适配器现在所有入站消息先统一成 internal message再由插件按 channel type 分流。这意味着一个插件可以同时服务 Teams、Webhook 等多个入口不用写两遍逻辑。对想二次开发的人来说这个改动很友好。2.2 源码构建和 Docker 部署到底怎么选很多新手把源码构建和 Docker 部署理解成两条互斥的路线实际在离线部署场景里它们通常是串联使用的先在一台有网的机器上完成源码编译然后把编译好的产物打进 Docker 镜像再用 docker save 导出镜像包拷到目标机器 docker load 导入。这样做的好处是目标机器完全不需要 npm registry、不需要编译工具链甚至不需要能访问外网。当然如果你要做深度二次开发比如改 OpenClaw 的插件调度逻辑那建议先用源码模式跑起来把调试工具接上改完再切回 Docker 化发布。两种方案各有适用场景我整理了一个简单的对比表对比维度纯源码运行Docker 化部署环境一致性依赖本机 Node/Python 版本完全隔离跨机器一致启动速度首次编译慢后续快镜像构建后秒级启动调试便利性直接看进程、接调试器需要 docker logs 绕一层升级回滚手动切换目录镜像标签天然支持回滚离线迁移需要搬依赖缓存docker save/load 最省事适合场景开发机、二次开发正式环境、内网交付我的建议是如果这台机器只跑 OpenClaw直接走 Docker如果你还要在同一台机器上调试插件代码先用源码模式。但无论哪种离线构建这一步的逻辑是一样的。2.3 环境准备和硬件底线说句实在话OpenClaw 对硬件的要求很宽容。它本身只是个编排层真正的算力消耗在模型那一侧。如果模型走 Ollama 本地推理那 CPU 最好 4 核以上、内存 16G 起步如果模型走云端 APIOpenClaw 自身 2 核 4G 内存的小机器就能稳定跑。系统方面建议 Debian 12 或 Ubuntu 22.04 以上的 64 位 LinuxDocker 版本不低于 20.10这样 Compose v2 和 buildx 都能正常工作。源码编译阶段需要准备的工具节点端是 Node.js 20.11 以上和 pnpm 9如果你要处理 Python 插件再准备 Python 3.11 和 pip。这里有一个容易踩的坑OpenClaw 的 monorepo 结构里前端和后端共享同一个 workspace 锁文件所以包管理器一定要用项目锁文件对应的那一个。我实测 pnpm 最容易复现官方构建npm 偶尔会出现 workspace 协议解析失败的问题。建议直接安装 corepack 来管理 pnpm 版本避免本地全局版本混乱。3. 离线源码构建完整过程3.1 先在有网络的环境里把源码和依赖锁好离线构建的前提是“在网上把东西准备好”。我习惯的做法是准备一台有网络访问能力的构建机系统建议和最终目标机保持一致至少大版本一致。首先拉取指定标签的源码这里注意不是拉默认分支而是用 v2026.3.12 这个 tag否则你构建出来的内容可能和版本号对不上。git clone https://github.com/openclaw/openclaw.git --branch v2026.3.12 --depth 1 openclaw cd openclaw corepack enable pnpm install --frozen-lockfile这里为什么强调 --frozen-lockfile因为锁文件里已经把每个依赖的精确版本钉死了。如果不加这个参数pnpm 会根据语义化版本范围重新解析可能拉到一个锁文件之外的新版本离线场景下依赖一旦漂移问题极难排查。第一次 install 会把所有依赖下载到 pnpm store 里这一步是在线环境里唯一需要大量网络请求的地方。安装完依赖后先不要急着关构建机我们还需要手动触发一次完整构建确保源码本身没有编译错误。这一步会在构建机上生成 dist 产物和缓存后续离线构建时这些产物可以直接复用不一定非得在目标机器上重新编译。pnpm build如果构建过程报错优先检查 Node 版本是否符合要求其次是确认网络拉取的依赖是否完整。构建机上重复跑 pnpm build 应该是幂等的第二次执行速度会明显加快因为有缓存。3.2 把依赖和产物完整打包带走离线迁移最忌讳只拷源码目录因为 node_modules 和 pnpm store 经常被忽略导致目标机器上根本无法 install。我总结了一个简单的打包清单源码目录、pnpm store 缓存、构建产物目录、依赖清单文件。其中 pnpm store 是让目标机器能跑pnpm install --offline的关键。我们可以用 pnpm 提供的 fetch 命令把 store 完整导出pnpm fetch --prod pnpm store path执行第二条命令后会输出当前 store 的物理路径比如/home/builder/.local/share/pnpm/store/v3。把这个目录完整拷贝到目标机器同样的用户路径下目标机器执行 install 时就可以走--offline模式完全不再访问网络。如果目标机器不能保持相同用户路径还有一个更省事的办法直接把整个项目目录连同 node_modules 一起打包然后在目标机器上只做运行时操作。这种“搬运完整目录”的方式虽然不优雅但确实在很多封闭内网环境里最可靠。打包命令我在下面给一个注意保留软链接和权限。cd /home/builder tar --exclude.git -czf openclaw-build-2026.3.12.tar.gz openclaw3.3 目标机器上的离线编译与安装把 tar 包拷到目标机器后解压进入项目目录。如果你的 pnpm store 已经放在了目标机器对应的路径那么执行离线安装会非常干净tar -xzf openclaw-build-2026.3.12.tar.gz -C /opt cd /opt/openclaw pnpm install --offline --frozen-lockfile这里有一个细节--offline模式要求所有包都能在本地 store 里命中只要命中直接符号链接到项目 node_modules 下速度比在线安装还要快。如果你发现它仍然尝试联网多半是 store 路径不对可以通过pnpm config get store-dir来核对。安装完成后再次执行pnpm build。因为大部分构建缓存已经在打包时带过来了所以这一步通常一两分钟就能结束。构建完成后可以先用开发模式启动一次验证数据目录是否能正常创建export DATA_DIR/opt/openclaw-data mkdir -p $DATA_DIR pnpm start看到日志里出现 session manager initialized 这类字样说明核心进程已经正常跑起来了。这时候 CtrlC 停掉我们进入 Docker 化阶段。3.4 用户和目录权限别等报错才处理很多人会在 Docker 部署时遇到 Permission denied追根溯源是宿主机数据目录的属主和容器内进程用户不一致。OpenClaw 官方镜像内部的默认用户是 uid 1000所以我通常直接在宿主机上创建数据目录并把属主改掉mkdir -p /opt/openclaw-data/{sessions,logs,plugins} chown -R 1000:1000 /opt/openclaw-data这一步看似简单但它能避免之后至少三类问题会话文件无法创建、日志无法写入、插件目录不可读。我发现多数“容器起来了但什么都不写”的现象其实都是权限问题而不是逻辑问题。养成先固定 uid 的习惯会省掉很多无意义的日志翻找。4. Docker 部署全流程4.1 编写一个可复现的基础镜像既然已经完成了源码构建接下来就是把构建产物固化到 Docker 镜像里。这里我用的是多阶段构建第一阶段使用完整的 Node 构建环境第二阶段只保留运行时依赖这样最终镜像体积可以控制在几百 MB 级别而不是把整个 monorepo 都塞进去。FROM node:20-slim AS builder WORKDIR /app RUN corepack enable COPY . . RUN pnpm install --offline --frozen-lockfile RUN pnpm build FROM node:20-slim WORKDIR /app ENV NODE_ENVproduction COPY --frombuilder /app/packages/server/dist ./dist COPY --frombuilder /app/packages/server/package.json ./package.json COPY --frombuilder /app/node_modules ./node_modules EXPOSE 8800 VOLUME [/data] CMD [node, dist/index.js]把 Dockerfile 放在项目根目录后执行构建docker build -t openclaw:2026.3.12 .如果在离线环境下执行 docker build需要确保第一阶段用到的 pnpm store 和 node_modules 已经在构建上下文里。此时可以临时把 store 目录放进 .dockerignore 的例外列表或者直接使用一个已经包含依赖缓存的构建镜像。我在实际操作中更倾向于在源机先构建好镜像然后用 docker save 导出下面会说具体命令。4.2 用 docker save 和 docker load 完成离线交付这是离线部署里最顺手的一个技巧。源机器上构建完镜像后直接导出成一个 tar 文件目标机器上一条命令就能导入完全绕开了 registry 访问的问题。docker save -o openclaw-2026.3.12.tar openclaw:2026.3.12然后在目标机器上docker load -i openclaw-2026.3.12.tar docker images | grep openclaw看到 openclaw:2026.3.12 出现就说明镜像导入成功。这个方式的好处是所有层都被完整保留不会出现“构建时好好的运行时报缺文件”的怪事。如果要迁移到多台机器把 tar 文件复制几份即可配合 sha256sum 校验一下完整性基本上就是最稳的离线交付路径。4.3 用 Compose 编排 OpenClaw 服务和本地模型单跑 OpenClaw 其实不太需要 Compose但如果你同时要拉起 Ollama 做本地推理用 Compose 统一管理会舒服很多。我提供一个典型的编排示例里面把数据目录、会话锁超时、模型服务地址都配置好了services: openclaw: image: openclaw:2026.3.12 container_name: openclaw restart: unless-stopped ports: - 8800:8800 volumes: - /opt/openclaw-data:/data environment: - DATA_DIR/data - LOG_LEVELinfo - SESSION_LOCK_TIMEOUT120000 - LLM_BASE_URLhttp://ollama:11434/v1 - LLM_API_KEYollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - /opt/ollama-models:/root/.ollama environment: - OLLAMA_HOST0.0.0.0:11434启动之后先在 ollama 容器里拉取模型。我建议从量化版本开始比如 qwen2.5:7b-instruct-q4_K_M资源占用和效果比较均衡。模型就绪后打开 OpenClaw 的配置页面模型提供商选 OpenAI-compatiblebase URL 填http://ollama:11434/v1API Key 随便填一个非空字符串因为 Ollama 不校验 key但 OpenClaw 要求这个字段不能为空。4.4 首次启动的验证清单启动容器之后不要急着接入 Teams先做一轮本地验证这样能把大部分问题消灭在最前面。看日志确认会话管理器初始化接着访问管理界面确认端口通最后从命令行发一个测试请求观察会话文件是否正确生成。docker compose up -d docker compose logs -f openclaw # 在宿主机验证数据写入 ls /opt/openclaw-data/sessions如果看到 session 文件出现且大小在动态变化说明整条链路是通的。此时再接入外部消息渠道出问题时的定位范围就会小很多。这也是我反复强调的先核心、后边缘先本地、后远端。5. LLM 接入与关键配置5.1 本地模型接入Ollama 是最省心的选择OpenClaw 对接本地模型本质上就是对接一个 OpenAI 兼容端点。Ollama 在这方面支持已经很完善启动后会自动暴露一个 /v1 路径OpenClaw 只需要把 LLM_BASE_URL 指过去即可。我在 Compose 里特意把 Ollama 暴露成ollama这个服务名这样容器之间可以直接通过服务名通信不依赖宿主机 IP。本地模型的选择要结合机器配置来。8G 内存的机器老老实实跑 3B~7B 的量化模型32G 以上内存再考虑 13B 级别。追求中文效果的、手头又是 7B 以下的小模型我实测用 qwen 系列比同尺寸其他模型在指令遵循方面更稳。模型拉取后记得先单独调一次 API确认响应正常再让 OpenClaw 去连否则排查时很难分清是模型问题还是中控层问题。5.2 远端 API 接入一个统一入口管理多个服务如果目标机器没有足够算力也可以让 OpenClaw 接入云端的 OpenAI 兼容服务。这里我建议不要直接在配置文件里散落一堆端点而是把模型路由收敛到 OpenClaw 的 model router 配置里。简单说就是配置多个 model profile每个 profile 有自己的 base URL、key、模型名OpenClaw 可以按会话或按工具调用去路由。参考配置如下新增一个远端模型 profile 之后在管理界面上把它设为默认即可models: local-qwen: type: openai-compatible base_url: http://ollama:11434/v1 model: qwen2.5:7b-instruct remote-api: type: openai-compatible base_url: https://api.example.com/v1 model: deepseek-chat需要提醒的是云端 API 会涉及流量费用和数据出本地的问题接入前最好确认合规要求。如果只是测试开一个小额限流足够。OpenClaw 会把所有对话历史持久化在本地数据目录这点反而比直接把历史留在云端更符合隐私直觉。5.3 看懂 SESSION_LOCK_TIMEOUT 这项配置这个参数在 v2026.3.12 里非常重要。它表示一个会话被其他请求持有锁时最大等待毫秒数默认 60000。如果超过这个时间还没拿到锁OpenClaw 会直接放弃当前请求并在日志里输出 agent failed before reply: session file locked (timeout 60000ms)。要判断自己是不是真的需要调大它先回想一下是否满足下面任意一条两个终端同时打开同一个会话自动化脚本用同一个 session id 高频发消息会话历史非常大导致重写状态文件耗时过长。如果都没有那大概率是偶发的轮询冲突保持默认即可偶尔一条报错不影响整体服务。如果有我建议直接调到 120000同时给会话目录用 SSD 存储磁盘延迟才是锁等待的核心瓶颈。6. 常见问题与排查技巧实录6.1 session file locked 报错的完整排查这是 v2026.3.12 用户群里出现频次最高的问题值得单独展开。我先描述一下典型症状OpenClaw 进程正常运行但消息在几秒后被拒绝日志里有 timeout 60000ms 的字样。这其实是锁机制在正常工作说明确有另一个请求正占用会话真正的问题是等待时间不够或者锁没被正确释放。排查顺序我先列在这里按步骤走基本不会漏确认是不是真的有并发请求查看当前进程的活跃请求数或直接确认是否有多个客户端在操作同一会话。检查锁文件残留如果进程被强杀锁文件可能没被清理手动删除会话目录下的.lock后缀文件即可恢复。评估会话文件大小如果单个会话文件超过 10MB状态读写会明显变慢建议拆分会话或者定期归档历史消息。调大 SESSION_LOCK_TIMEOUT 并观察把这个值调到 120000再复现一次如果问题消失说明是偶发慢写入。还有一个容易忽略的细节你用的存储类型。如果数据目录在机械硬盘上锁争用体验会特别明显尤其是大量历史消息回写时。换成 SSD 之后这类超时问题几乎绝迹。我自己的机器第一次遇到这个报错排查到最后就是磁盘 IO 瓶颈纯粹是没想到。6.2 Docker Desktop 启动失败Virtualization Support 未检测到Windows 上使用 Docker Desktop 时常见的一个报错是 Docker Desktop failed to start because virtualization support is not detected。这不是 OpenClaw 的问题是 Docker Desktop 依赖硬件虚拟化能力。解决办法首先是进 BIOS 确认 VT-x 或 AMD-V 已经开启然后在 Windows 功能里启用 Hyper-V 和 Windows Hypervisor Platform。如果你所在机器的 BIOS 不支持虚拟化或者你在 VM 里嵌套安装 Docker Desktop建议直接改用 Docker Engine WSL2 后端或者干脆在 Linux 虚拟机里跑 Docker。我自己见过很多人在这一步卡了一天最后换成 WSL2 后端就正常了。原因无他Docker Desktop 对 Windows 底层虚拟化栈的依赖比你想的更严格。6.3 容器之间网络不通的排查思路容器起来了、日志也正常但 OpenClaw 连不上 Ollama这是典型的服务名解析或网络模式问题。在同一个 Compose 网络里容器应该直接用服务名互相访问不需要暴露宿主机端口。检查顺序是先docker compose ps确认两个容器都活着再docker exec openclaw curl http://ollama:11434验证连通性最后看防火墙是否挡了宿主机到容器的端口映射。如果目标机器上有其他网络策略偶尔会出现 Compose 默认 bridge 网络被干扰的情况。最粗暴但有效的方案是把 OpenClaw 和 Ollama 都改用network_mode: host直接用宿主机回环地址通信。这种方式牺牲了一点隔离性但在企业内网环境里反而最不容易出幺蛾子。6.4 数据目录权限和数据迁移容器经常遇到的现象是容器重启后之前的对话记录找不到了或者日志报 EACCES。绝大多数是数据目录没有持久化或权限不对。OpenClaw 的 Docker 镜像默认用 uid 1000 运行你在宿主机建目录的时候就要把属主改成 1000。迁移则简单得多停掉容器把整个数据目录打包拷贝到新机器再在 Compose 里挂载对应路径即可。这里我强烈建议给数据目录加一个定时快照。OpenClaw 的会话历史是你和 AI 之间最有价值的资产我会用 cron 每天凌晨打一个 tar.gz保留最近七天。恢复操作也很直观解压后替换数据目录重启容器所有会话和配置都会原样回来。7. 把 OpenClaw 接进 Teams 和 Obsidian 的扩展用法7.1 Teams 接入的几个关键步骤接入 Microsoft Teams 是 OpenClaw 很受欢迎的一个功能本质上是把 Teams 的 Bot 消息转发给 OpenClaw 处理后原路返回。先到 Teams 开发者平台创建一个 Bot拿到 Bot App ID 和 Client Secret然后在 OpenClaw 配置里填入这些信息并设置 messaging endpoint 指向你自己的 HTTPS 地址。这里要特别提醒Teams 要求回调地址必须是公网可达的 HTTPS 端点本地部署建议在前面放一层反向代理来终结 TLS。配置完成后在 Teams 里给 Bot 发一条消息如果 OpenClaw 日志出现 inbound message received说明链路已经打通。首次接入时可以先别在 Teams 里长篇对话只发一条“ping”确认端到端通畅再开始正式使用。7.2 把 Obsidian 笔记库变成 Agent 的知识底座Obsidian 是很多人记录知识的地方OpenClaw 的 obsidian 插件允许它直读公开的 markdown 文件。我在 Compose 里额外挂载了笔记目录这样 Agent 在回答问题引用本地笔记时不需要先花时间同步导入直接读文件系统即可。volumes: - /opt/openclaw-data:/data - /home/user/obsidian-vault:/notes:ro插件启用后在对话里写“搜索我笔记里关于 Docker 权限的内容总结成三点”OpenClaw 就会在 /notes 目录里做全文检索。注意只读挂载是为了防止 Agent 误改笔记内容如果你确实需要自动整理笔记可以把 ro 去掉但那样风险高不少至少要先做一轮备份。8. 维护期的经验与操作习惯跑 OpenClaw 跑了两年多我最想分享的其实是三个看起来不起眼、但决定长期体验的习惯。第一个习惯版本升级永远先看 release note 再动镜像。像 v2026.3.12 这种把小版本号打得很明确的版本改动面不一定小。我会把每次升级当作一次新部署来对待先在测试机 docker load 新镜像验证一轮会话锁和消息通道再同步到生产机。绝不跳版本比如从 2026.2.x 直接跳到 2026.4.x中间可能跨了不兼容的配置格式。第二个习惯日志不只是排障时才看。我会给 OpenClaw 写一个简单的日志轮转按天归档并每周手动搜一次 WARN 级别以上的关键词。session file locked 这类问题如果每天只出现一两条可以观察如果突然变多往往预示着存储磁盘性能下降或某个自动化脚本在疯狂触发会话提前处理远好过半夜收到服务不可用的告警。第三个习惯把一切可配置项全部写进 Compose 环境变量而不是散落在界面设置里。环境变量有迹可循配一份 docker-compose.override.yml 就能区分开发和生产环境换机器部署时直接复制文件加改路径即可。我见过太多人在界面里点了一堆配置最后机器坏了重建时完全想不起来自己改过什么。OpenClaw 这样天然支持声明式配置的项目就该走基础设施即代码的老路。最后再分享一个小技巧部署成功后第一时间把构建产物、docker save 的镜像包、Compose 文件、数据目录备份策略这四样东西整理到同一个目录并写好一行备注说明它们的匹配关系。一旦以后要复现环境你会感激自己当时留了这套“部署四件套”。OpenClaw 这类工具折腾成本集中在第一次越往后越像养一盆熟透的绿植按时浇水、定期修剪剩下的全是省心的日常。