企业官网建设流程全解析

折腾 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 化发布。两种方案各有适用场景，我整理了一个简单的对比表：

我的建议是：如果这台机器只跑 OpenClaw，直接走 Docker；如果你还要在同一台机器上调试插件代码，先用源码模式。但无论哪种，离线构建这一步的逻辑是一样的。

2.3 环境准备和硬件底线

说句实在话，OpenClaw 对硬件的要求很宽容。它本身只是个编排层，真正的算力消耗在模型那一侧。如果模型走 Ollama 本地推理，那 CPU 最好 4 核以上、内存 16G 起步；如果模型走云端 API，OpenClaw 自身 2 核 4G 内存的小机器就能稳定跑。系统方面建议 Debian 12 或 Ubuntu 22.04 以上的 64 位 Linux，Docker 版本不低于 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 openclaw

3.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 这类字样，说明核心进程已经正常跑起来了。这时候 Ctrl+C 停掉，我们进入 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_ENV=production COPY --from=builder /app/packages/server/dist ./dist COPY --from=builder /app/packages/server/package.json ./package.json COPY --from=builder /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_LEVEL=info - SESSION_LOCK_TIMEOUT=120000 - LLM_BASE_URL=http://ollama:11434/v1 - LLM_API_KEY=ollama ollama: image: ollama/ollama:latest container_name: ollama restart: unless-stopped volumes: - /opt/ollama-models:/root/.ollama environment: - OLLAMA_HOST=0.0.0.0:11434

启动之后，先在 ollama 容器里拉取模型。我建议从量化版本开始，比如 qwen2.5:7b-instruct-q4_K_M，资源占用和效果比较均衡。模型就绪后，打开 OpenClaw 的配置页面，模型提供商选 OpenAI-compatible，base URL 填http://ollama:11434/v1，API 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 的字样。这其实是锁机制在正常工作，说明确有另一个请求正占用会话，真正的问题是等待时间不够或者锁没被正确释放。

排查顺序我先列在这里，按步骤走基本不会漏：

1. 确认是不是真的有并发请求：查看当前进程的活跃请求数，或直接确认是否有多个客户端在操作同一会话。
2. 检查锁文件残留：如果进程被强杀，锁文件可能没被清理，手动删除会话目录下的.lock后缀文件即可恢复。
3. 评估会话文件大小：如果单个会话文件超过 10MB，状态读写会明显变慢，建议拆分会话或者定期归档历史消息。
4. 调大 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 这类工具，折腾成本集中在第一次，越往后越像养一盆熟透的绿植，按时浇水、定期修剪，剩下的全是省心的日常。