1. 从零到一为什么选择 OpenClaw 与 Docker 来接入飞书最近在团队内部折腾自动化流程发现很多重复性的信息查询、数据汇总和状态同步工作完全可以交给一个“智能助理”来完成。市面上基于大模型的工具很多但要么是 SaaS 服务数据隐私不放心要么部署复杂对运维要求太高。直到我遇到了 OpenClaw一个开源的、可以本地化部署的智能体框架它最大的吸引力在于能轻松地接入像飞书这样的办公协作平台让 AI 能力直接嵌入到日常沟通流里。你可能也搜到过类似的关键词openclaw llamap svr operator(): got exception或者docker desktop failed to start because virtualisation support wasn’t detected。这恰恰说明了两个核心痛点一是开源项目在部署和运行中难免会遇到各种环境报错二是 Docker 环境本身对新手就是个门槛。但正因为有这些坑踩过去之后的路径才更清晰。这篇教程就是把我从环境准备、镜像构建、飞书机器人配置到最终成功交互的完整过程包括中间遇到的每一个“坑”和解决方案毫无保留地分享出来。我们的目标很简单在你自己的一台机器上无论是开发机、云服务器还是家里的 NAS通过 Docker 跑起一个属于你自己的、能通过飞书对话的 OpenClaw 智能体。选择 Docker 部署几乎是必然的。OpenClaw 本身依赖 Python 环境、各种深度学习库以及可能的模型文件手动安装堪比一场噩梦。Docker 把所有这些依赖打包成一个独立的、可移植的“集装箱”你只需要一条命令就能让它在任何支持 Docker 的系统上以完全一致的方式运行起来。这完美避开了“在我机器上好好的”这类经典问题。接下来我们就从最基础的 Docker 环境搭建开始一步步走向那个能和你飞书聊天的 AI 伙伴。2. 基石准备搞定 Docker 运行环境与关键依赖万事开头难而部署 OpenClaw 的“难”往往就卡在第一步Docker 环境。很多人包括我自己最初都倒在了Docker Desktop failed to start because virtualisation support wasn’t detected这个错误面前。这不仅仅是点一下安装包就能解决的事它涉及到你电脑底层的虚拟化支持。2.1 深入理解虚拟化错误与系统级解决这个错误的本质是你的计算机 BIOS/UEFI 设置中的 CPU 虚拟化技术Intel VT-x 或 AMD-V没有开启或者被其他软件如某些安卓模拟器、旧版 VMware占用了。Docker Desktop 在 Windows 和 macOS 上依赖于一个轻量级的 Linux 虚拟机来运行容器没有虚拟化这个虚拟机就起不来。排查与解决全流程确认虚拟化状态在 Windows 上可以打开任务管理器切换到“性能”标签页查看“CPU”部分是否有“虚拟化: 已启用”的字样。如果显示“已禁用”就需要进入 BIOS 设置。重启进入 BIOS/UEFI开机时狂按Delete、F2、F10或Esc键具体按键因主板品牌而异。这个界面全英文别慌。寻找虚拟化选项在 BIOS 设置中找到类似Advanced(高级) -CPU Configuration(CPU 配置) 或Security(安全) 的菜单。寻找名为Intel Virtualization Technology、VT-x、AMD-V或SVM Mode的选项将其状态从Disabled改为Enabled。保存并退出通常按F10键选择Yes保存设置并重启电脑。处理软件冲突如果 BIOS 已开启但 Docker 仍报错可能是 Hyper-V、Windows Sandbox 或第三方虚拟化软件冲突。对于 Windows 专业版/企业版可以尝试在“启用或关闭 Windows 功能”中确保“Hyper-V”和“Windows 虚拟机监控程序平台”被勾选启用这有时反而能提供更稳定的底层支持。如果安装了VMware Workstation请注意其与 Hyper-V 不兼容你可能需要选择其一。对于 macOS 用户情况简单得多。只要你的 Mac 是 Intel 芯片且系统版本在 macOS 10.14或 Apple Silicon 芯片M1/M2/M3Docker Desktop 都会自动处理虚拟化层利用 macOS 的 Hypervisor.framework通常不会遇到此问题直接去 Docker 官网下载对应芯片版本的Docker Desktop for Mac安装即可。注意在 Windows 家庭版上无法直接启用 Hyper-V。你需要安装WSL 2(Windows Subsystem for Linux 2) 作为后端。先确保系统已更新到较新版本如 Windows 10 2004 以上然后在 PowerShell管理员身份中运行wsl --install命令来安装 WSL 2 和默认的 Linux 发行版如 Ubuntu。之后安装 Docker Desktop 时它会自动检测并使用 WSL 2 后端。2.2 Docker 安装与镜像源加速解决了虚拟化安装 Docker Desktop 就是下一步。从官网下载安装包一路下一步即可。安装完成后打开 Docker Desktop你会在系统托盘区看到它的图标。为了后续拉取镜像时速度更快我们必须配置国内镜像源否则下载速度可能只有几十 KB/s。配置 Docker 国内镜像源以 Windows Docker Desktop 为例右键点击系统托盘区的 Docker 鲸鱼图标选择Settings(设置)。在设置窗口中找到Docker Engine选项。你会看到一段 JSON 配置代码。我们需要在registry-mirrors数组中添加国内镜像地址。将配置修改为如下样子保留原有的其他配置只添加registry-mirrors部分或修改它{ builder: { gc: { defaultKeepStorage: 20GB, enabled: true } }, experimental: false, features: { buildkit: true }, registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com, https://mirror.baidubce.com ] }这里我添加了中国科技大学、网易和百度的镜像源。你可以选择一个延迟最低的。修改后点击Apply RestartDocker 会重启并应用新配置。验证安装打开命令行终端CMD 或 PowerShell输入docker --version和docker run hello-world。如果能看到版本信息并且hello-world镜像能成功运行并输出欢迎信息说明 Docker 环境已经准备就绪。这个hello-world镜像很小也是验证网络和基础功能的好方法。3. 获取与构建OpenClaw 的 Docker 镜像实战有了健康的 Docker 环境我们就可以着手处理 OpenClaw 本身了。OpenClaw 是一个开源项目代码托管在 GitHub 上。我们有两种方式获取其 Docker 镜像一是直接拉取社区构建好的镜像如果存在且版本合适二是自己从源码构建。为了确保兼容性和对内部机制的理解我强烈推荐第二种方式因为我们可以控制所有依赖的版本并且能根据后续飞书机器人的需求进行定制。3.1 克隆源码与理解 Dockerfile首先我们需要将 OpenClaw 的源代码克隆到本地。打开终端切换到一个你习惯的工作目录例如D:\Projects或~/projects执行以下命令git clone https://github.com/openclaw-ai/openclaw.git cd openclaw提示如果 GitHub 访问缓慢可以尝试使用https://ghproxy.com/代理地址即git clone https://ghproxy.com/https://github.com/openclaw-ai/openclaw.git。进入项目根目录后你应该能看到一个名为Dockerfile的文件。这个文件定义了构建 Docker 镜像的“食谱”。在构建之前花几分钟阅读一下它是很有必要的。一个典型的 OpenClaw Dockerfile 可能会包含以下关键步骤选择基础镜像例如FROM python:3.10-slim这决定了操作系统和 Python 的初始环境。设置工作目录WORKDIR /app。复制依赖文件并安装COPY requirements.txt .和RUN pip install -r requirements.txt。这里决定了项目运行所需的所有 Python 包。复制应用代码COPY . .。暴露端口EXPOSE 8000这提示容器运行时将使用哪个端口。设置启动命令CMD [python, app/main.py]或使用uvicorn等 ASGI 服务器启动。理解这些有助于我们在构建出错或需要自定义时知道从哪里下手。例如如果requirements.txt中的某个包版本与飞书 SDK 冲突我们就需要在这里进行调整。3.2 执行构建命令与常见问题处理在包含Dockerfile的目录下执行构建命令docker build -t openclaw:latest .这个命令的含义是docker build开始构建-t openclaw:latest给构建成功的镜像打上标签名称openclaw 标签latest最后的.表示构建上下文是当前目录。构建过程可能会遇到以下几个典型问题及解决方案网络超时 (Read timed out)由于pip默认从国外源下载包速度很慢导致超时。解决方法是在Dockerfile中RUN pip install这一行之前添加换用国内镜像源的命令。修改Dockerfile在安装依赖的步骤前加入RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple或者直接在pip install命令中指定源RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple修改后需要重新运行docker build命令。依赖冲突错误信息可能包含Cannot resolve dependencies或Conflict。这表明requirements.txt中某些包的版本要求相互冲突。这时需要你根据错误提示手动调整requirements.txt文件中的版本号或者尝试使用pip-compile来自pip-tools来生成一个兼容的版本锁文件。一个更务实的方法是先注释掉疑似冲突的包让基础环境先搭建起来后续再单独安装。内存不足在构建需要编译大型 C/C 扩展包如某些机器学习库时Docker 构建过程可能会耗尽内存。可以在 Docker Desktop 的设置中增加分配给 Docker 的资源如内存提升到 4GB 或 8GB。也可以在构建命令中加入--memory参数但更常见的是调整 Docker 全局设置。构建过程会持续一段时间取决于你的网速和电脑性能。当终端最后输出Successfully built 镜像ID和Successfully tagged openclaw:latest时就大功告成了。你可以通过docker images命令查看本地已有的镜像确认openclaw镜像是否存在。4. 飞书机器人创建、配置与获取关键凭证现在我们有了可以运行的 OpenClaw 镜像但它还是一个“哑巴”不知道如何与外界通信。接下来我们要在飞书开放平台创建一个机器人并获取让 OpenClaw 与之对话的“钥匙”。4.1 在飞书开放平台创建企业自建应用访问开放平台打开浏览器访问 飞书开放平台 使用你的飞书账号登录。如果你代表一个组织最好使用有管理员权限的账号。创建应用在控制台页面点击“创建企业自建应用”。给应用起一个名字比如“OpenClaw 智能助理”并上传一个应用图标可选。获取 App ID 与 App Secret创建成功后在应用详情的“凭证与基础信息”页面你会看到App ID和App Secret。这是机器人最重要的身份凭证相当于账号和密码。请立即将App Secret妥善保存因为它只显示一次。4.2 配置应用权限与启用机器人能力创建的应用默认没有任何权限我们需要手动为它添加。添加权限在左侧导航栏找到“权限管理”。我们需要为机器人添加接收和发送消息的权限。至少需要添加以下权限im:message下的发送单聊、群组消息(im:message:send_as_bot) 和接收群聊中机器人消息事件(im:message:receive_v2)。im:bot下的获取机器人信息(im:bot)。如果你希望机器人在群聊中能被还需要im:chat下的获取群组信息(im:chat:read)。 找到这些权限点击“申请权限”。在企业自建应用中这些权限通常是默认通过的但为了保险起见最好还是走一下申请流程。启用机器人能力在左侧导航栏找到“事件订阅”。要接收用户消息必须在这里启用机器人。点击“启用机器人”按钮。启用后你会看到两个至关重要的配置项Encrypt Key和Verification Token系统会自动生成。这两个值也需要记录下来后续配置 OpenClaw 时会用到。请求地址 URL这个地址是我们下一步要配置的、OpenClaw 服务对外的回调地址。先留空等我们部署好 OpenClaw 并获取了公网可访问的地址后再来填写。例如如果你使用内网穿透工具地址可能是https://your-domain.com/feishu/callback。配置事件订阅在“事件订阅”页面点击“添加事件”。我们需要订阅“接收消息”相关的事件。通常选择im.message.receive_v1接收消息事件 v1.0。添加后需要为这个事件指定一个“请求地址”同样是留空稍后与上面的 URL 一并填写。4.3 发布应用与将机器人添加到聊天版本管理与发布在左侧导航栏找到“版本管理与发布”。点击“创建版本”填写版本号如1.0.0和更新说明。然后点击“申请发布”。在企业自建应用中通常可以由管理员直接审核通过。添加机器人应用发布后回到“凭证与基础信息”页面你会看到一个“机器人”模块。点击“添加机器人”。在飞书中使用添加成功后你可以在飞书客户端中通过搜索应用名称“OpenClaw 智能助理”找到它并添加到任意群聊或发起单聊。只有添加到聊天会话中机器人才能被触发。至此飞书侧的配置暂时告一段落。我们手头已经拿到了四把关键的“钥匙”App ID、App Secret、Encrypt Key、Verification Token。请将它们安全地记录下来下一步配置 OpenClaw 时会全部用到。5. 连接桥梁配置 OpenClaw 对接飞书机器人现在我们有了镜像OpenClaw也有了通信对象飞书机器人的凭证。接下来我们要在 OpenClaw 内部进行配置让它知道如何与飞书对话并处理飞书转发过来的消息。5.1 理解 OpenClaw 的配置结构与飞书适配器OpenClaw 的配置通常通过环境变量或配置文件来管理。在 Docker 部署中使用环境变量是最灵活和主流的方式。我们需要关注 OpenClaw 项目中与飞书Feishu集成的部分这通常是一个“适配器”Adapter或“平台插件”Platform Plugin。查看 OpenClaw 的源码目录你可能会找到一个config文件夹或类似config.yaml、.env.example的文件。我们需要创建一个生产环境的配置文件或者直接准备一系列环境变量。核心的飞书配置项通常包括环境变量名说明对应飞书平台的值FEISHU_APP_ID飞书应用的唯一标识开放平台“凭证与基础信息”中的App IDFEISHU_APP_SECRET飞书应用的密钥开放平台“凭证与基础信息”中的App SecretFEISHU_ENCRYPT_KEY消息加密密钥开放平台“事件订阅”中的Encrypt KeyFEISHU_VERIFICATION_TOKEN事件验证令牌开放平台“事件订阅”中的Verification TokenFEISHU_BOT_NAME机器人在 OpenClaw 中的称呼自定义如 “小爪”SERVER_URLOpenClaw 服务对外暴露的 URL你公网可访问的地址如https://your-domain.com其中SERVER_URL是最容易出错的一环。在本地开发时你可能使用localhost但飞书的服务器无法访问你的本地网络。因此你需要一个公网地址。5.2 使用 Ngrok 或 Cloudflare Tunnel 实现本地服务公网可访问为了让飞书能回调我们本地运行的 OpenClaw我们需要一个内网穿透工具。Ngrok (推荐用于快速测试)访问 ngrok 官网注册并获取你的Authtoken。下载 ngrok 客户端并解压。在终端中运行ngrok config add-authtoken 你的token。假设你的 OpenClaw 将在 Docker 容器内的8000端口运行。在终端运行ngrok http 8000。Ngrok 会生成一个随机的https域名例如https://abcd-123-456.ngrok-free.app。这个就是你的SERVER_URL。将其复制下来。Cloudflare Tunnel (更稳定适合长期使用)你需要一个 Cloudflare 账号并将你的域名托管在 Cloudflare。在 Cloudflare Zero Trust 面板中创建Tunnel。根据指引在你的本地机器上安装cloudflared客户端并运行连接命令。配置Tunnel将流量指向你本地的localhost:8000。你会得到一个如https://openclaw.yourdomain.com的固定子域名。这就是你的SERVER_URL。获取到SERVER_URL后完整的飞书回调地址就是{SERVER_URL}/feishu/callback具体路径需参考 OpenClaw 飞书适配器的文档。将这个地址填写到飞书开放平台“事件订阅”页面的“请求地址 URL”和im.message.receive_v1事件的请求地址中。填写后飞书会立即向该地址发送一个带有challenge参数的 GET 请求进行验证。如果你的 OpenClaw 服务尚未运行或配置不正确验证会失败。所以我们先进行下一步启动服务后再来验证。5.3 创建 Docker 运行配置文件与环境变量注入我们不建议将敏感信息硬编码在代码或 Dockerfile 中。最佳实践是使用环境变量。我们可以创建一个名为docker-compose.yml的文件来管理 OpenClaw 服务的启动这比单纯的docker run命令更清晰也便于管理多个服务比如未来可能添加数据库。在 OpenClaw 项目根目录下创建docker-compose.yml文件version: 3.8 services: openclaw: image: openclaw:latest # 使用我们之前构建的镜像 container_name: openclaw-feishu restart: unless-stopped # 容器意外退出时自动重启 ports: - 8000:8000 # 将容器内的8000端口映射到宿主机的8000端口 environment: - FEISHU_APP_IDcli_xxxxxxxxxxxxxx # 替换为你的 App ID - FEISHU_APP_SECRETxxxxxxxxxxxxxxxxxxxxxxxx # 替换为你的 App Secret - FEISHU_ENCRYPT_KEYxxxxxxxxxxxxxxxx # 替换为你的 Encrypt Key - FEISHU_VERIFICATION_TOKENxxxxxxxxxxxxxxxx # 替换为你的 Verification Token - FEISHU_BOT_NAME小爪 - SERVER_URLhttps://abcd-123-456.ngrok-free.app # 替换为你的公网地址 # 以下是 OpenClaw 可能需要的其他配置例如大模型 API 密钥 - OPENAI_API_KEYsk-xxxxxxxxxxxxxxxx # 如果你使用 OpenAI 作为后端 - MODEL_NAMEgpt-3.5-turbo volumes: # 可选挂载本地目录用于持久化数据或日志 - ./data:/app/data - ./logs:/app/logs这个配置文件清晰地定义了服务。现在回到飞书开放平台将“请求地址”设置为https://abcd-123-456.ngrok-free.app/feishu/callback请替换为你的实际地址。然后在终端中进入docker-compose.yml所在目录运行docker-compose up -d-d参数表示在后台运行。使用docker-compose logs -f openclaw可以实时查看容器日志这对于排查启动错误至关重要。6. 验证、测试与排错完成最后一步握手服务启动后最关键的一步就是验证飞书与 OpenClaw 之间的连接是否畅通。6.1 飞书事件订阅验证当你把回调地址填入飞书开放平台并保存时飞书服务器会立即向该地址发送一个GET请求进行验证请求中会包含一个challenge参数。OpenClaw 的飞书适配器必须能正确接收这个请求并按照飞书规定的格式返回一个包含该challenge值的 JSON 响应。如何判断验证成功查看 OpenClaw 容器的日志 (docker-compose logs openclaw)。如果你看到类似Received feishu verification request和Verification successful的日志同时在飞书开放平台页面上请求地址 URL 旁边显示一个绿色的“验证成功”勾选标记那就说明握手成功了。如果验证失败怎么办检查网络确保你的SERVER_URL是公网可访问的并且 ngrok/Cloudflare Tunnel 正在运行。你可以直接在浏览器中访问{SERVER_URL}/health或{SERVER_URL}/如果 OpenClaw 有健康检查端点看是否能收到响应。检查路径确认飞书填写的回调地址和 OpenClaw 服务实际监听的路径完全一致。查看 OpenClaw 飞书适配器的源码确认它处理回调的路由是什么通常是/feishu/callback或/webhook/feishu。检查日志仔细阅读容器启动日志和请求日志。常见的错误包括环境变量名拼写错误导致配置未加载、所需的 Python 包未安装飞书 SDK、端口映射错误主机端口不是8000等。检查飞书配置确认App ID、App Secret等所有凭证都已正确复制没有多余的空格。6.2 首次对话测试与消息流分析验证成功后在飞书客户端里找到你已经添加了机器人的单聊或群聊尝试 机器人 或直接发送消息。发送消息后的排查逻辑飞书端消息成功发出。OpenClaw 日志你应该能在容器日志中看到类似Received message from user: xxx, content: xxx的日志。这证明飞书已经将消息事件推送到了你的服务。OpenClaw 处理日志会显示 OpenClaw 开始调用大模型如 OpenAI API进行处理Calling LLM API with prompt: ...。飞书端回复如果一切顺利几秒到十几秒后你应该能在飞书中收到机器人的回复。OpenClaw 日志同时日志会显示Message sent successfully to feishu conversation: xxx。如果收不到回复按照以下顺序排查步骤一检查消息接收日志。如果根本没看到接收消息的日志问题出在飞书事件推送环节。重回飞书开放平台检查“权限管理”中是否已添加并开通了“接收消息”的权限以及“事件订阅”中是否已订阅im.message.receive_v1事件。步骤二检查大模型调用日志。如果收到了消息但没有调用 LLM 的日志可能是 OpenClaw 内部的对话逻辑或路由配置有问题。检查环境变量OPENAI_API_KEY等是否设置正确。步骤三检查消息发送日志与错误。如果调用了 LLM 但发送失败日志通常会打印出飞书 API 返回的错误信息。常见错误有code: 99991663通常意味着App ID和App Secret不匹配或失效去开放平台重新获取一下。code: 99991668机器人未被添加到当前会话。确保你已经在当前这个群或单聊中成功添加了该机器人应用。其他权限错误回到“权限管理”确认“发送消息”等权限确实已申请并开通。6.3 进阶配置与优化思路当基础功能跑通后你可以考虑以下优化配置持久化与敏感信息管理将环境变量移出docker-compose.yml放入一个.env文件并在docker-compose.yml中通过env_file指令引入。确保.env文件被添加到.gitignore中避免密钥泄露。使用模型托管服务如果你觉得 OpenAI API 速度慢或成本高可以配置 OpenClaw 使用本地部署的模型如通过 Ollama 部署的 Llama 3或国内的大模型 API如 DeepSeek、MiniMax。这需要修改 OpenClaw 中关于 LLM 客户端的配置。添加对话记忆与上下文默认的 OpenClaw 配置可能只处理单轮对话。为了进行多轮连贯的聊天你需要为其配置一个“记忆后端”例如使用 Redis 或数据库来存储会话历史。这通常涉及在docker-compose.yml中增加一个 Redis 服务并配置 OpenClaw 连接它。日志与监控将 Docker 容器的日志输出到外部文件或日志收集系统如 ELK方便长期运维和问题追溯。可以在docker-compose.yml中配置日志驱动。整个过程从环境准备到最终对话成功就像在搭一座精密的桥。任何一个环节的松动都可能导致通信中断。我最深的体会是日志是你的最佳拍档。无论是 Docker 构建日志、容器运行日志还是飞书开放平台的事件推送记录里面都藏着解决问题的钥匙。遇到报错不要慌把错误信息完整地复制出来逐字逐句去搜索、去理解你会发现社区里很可能已经有人踩过同样的坑。现在你的飞书智能助理已经上线了去试试让它帮你查资料、写周报或者回答技术问题吧这种将前沿 AI 能力无缝融入日常工作的感觉才是折腾这一切最大的乐趣所在。