1. 为什么我选择用 Docker Compose 跑 OpenClaw 并接入飞书OpenClaw 是一个可以把大模型能力接到即时通讯平台上的开源网关你可以把它理解成一个“翻译官”一边连着模型 API一边连着飞书、Telegram 这类聊天工具消息进来它转发给模型模型回复它再送回聊天窗口。适合谁适合想让团队在飞书里直接用上 AI 助手、又不想自己从零写接入层的开发者也适合想快速验证“模型 IM”玩法的小团队。我最初是在一台 2 核 4G 的测试机上折腾的手动装依赖、配 Python 环境、改回调地址来回折腾了大半天。后来换成 Docker Compose 方案从拉镜像到飞书里收到第一条回复大概十几分钟。这篇就把这套极简流程完整写出来重点解决两个最容易卡住的地方环境变量怎么填、统一 Key 怎么配。你跟着做能拿到一份可直接复制的docker-compose.yml、.env和config.toml骨架最后我会演示怎么验证飞书回调和 API 连通性。需要提前说明的是模型侧我用的是 TaoToken 的统一 Key一个 Key 就能切换不同模型省得在多个平台之间来回注册。下面所有配置都围绕这个思路展开。2. TaoToken 前置准备拿到统一 Key 和接入地址在写 Compose 文件之前先把模型侧的凭证准备好。TaoToken 的作用是提供一个统一的 API 入口你不需要为每个模型单独申请 Key换模型时只改一个模型名参数就行。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台找到 API Keys 页面新建一个 Key。这个 Key 就是后面.env里的API_KEY格式通常是一串以sk-开头的字符串复制下来先存好页面关掉后不一定能再看到完整值。第二步确认接入地址。TaoToken 的 API 基础地址是https://taotoken.net/api注意这里不要加任何查询参数。这个地址对应.env里的BASE_URLOpenClaw 会用它拼接出最终的请求路径。第三步想好你要用哪个模型。TaoToken 支持多种模型模型名填在MODEL_ID里。如果你只是先跑通流程选一个通用对话模型即可如果后面要做代码相关的 Agent可以换成更强的编码模型。模型列表在控制台的模型对话页面能看到也可以直接在那个页面先发一条消息测试 Key 是否可用。提示Key 属于敏感信息不要提交到 Git 仓库。建议.env文件加入.gitignore或者用服务器上的环境变量注入。到这里你手里应该有三样东西API_KEY、BASE_URL固定为https://taotoken.net/api、MODEL_ID。接下来进入部署环节。3. 可复制的 docker-compose.yml 与 .env 配置这一节是全文的核心所有文件都可以直接复制。我假设你在 Linux 服务器上操作已经装好了 Docker 和 Docker Compose。如果还没装先用官方脚本装好这里不展开。先建一个工作目录比如/opt/openclaw进去之后创建三个文件docker-compose.yml、.env、config.toml。3.1 docker-compose.ymlversion: 3.8 services: openclaw-gateway: image: justlikemaki/openclaw-docker-cn-im:latest container_name: openclaw-gateway restart: unless-stopped env_file: - .env volumes: - ./config.toml:/root/.openclaw/openclaw.json - ./workspace:/root/.openclaw/workspace ports: - 8080:8080 logging: driver: json-file options: max-size: 10m max-file: 3这里有几个点值得说。env_file指向.env所有环境变量从这里注入不用在 Compose 里硬编码。volumes把本地的config.toml挂到容器内的配置文件路径这样改配置不用重建镜像。workspace目录用来持久化工作区数据容器重启不丢。端口映射8080:8080是给飞书回调用的后面飞书那边要填这个地址。3.2 .env 文件# 模型侧配置TaoToken 统一 Key MODEL_IDgpt-4 BASE_URLhttps://taotoken.net/api API_KEYsk-你的TaoToken密钥 # 飞书配置 FEISHU_APP_IDcli_你的appid FEISHU_APP_SECRET你的appsecret # 服务配置 PORT8080 LOG_LEVELinfoMODEL_ID按你实际想用的模型填BASE_URL固定写 TaoToken 的地址API_KEY换成你刚才复制的。飞书的两个值先留空也行等下一节拿到再回来填。3.3 config.toml 骨架[gateway] port 8080 log_level info [model] provider openai-compatible model_id ${MODEL_ID} base_url ${BASE_URL} api_key ${API_KEY} [platform.feishu] enabled true app_id ${FEISHU_APP_ID} app_secret ${FEISHU_APP_SECRET}这个骨架里用了${}占位符OpenClaw 启动时会从环境变量里读取实际值。这样配置和密钥分离改 Key 只动.env不用碰config.toml。文件都建好后先别急着启动因为飞书那边还没配。但你可以先跑一次docker-compose config检查语法有没有写错这个命令会解析 Compose 文件并打印最终配置不实际启动容器。4. 飞书机器人配置与回调验证飞书这一侧是新手最容易翻车的地方我按顺序拆开讲。4.1 创建自建应用并拿凭证登录飞书开放平台进入开发者后台创建一个“企业自建应用”。创建完成后在“凭证与基础信息”页面能看到App ID和App Secret把这两个值填回.env的FEISHU_APP_ID和FEISHU_APP_SECRET。4.2 开通权限在“权限管理”页面至少开通以下权限否则机器人收不到消息权限标识说明im:message消息发送和接收核心权限im:message.p2p_msg:readonly读取私聊消息im:message.group_at_msg:readonly接收群内 机器人 的消息im:message:send_as_bot以机器人身份发送消息开通后需要提交审核自建应用一般很快通过。4.3 配置事件订阅这是最关键的一步。在“事件与回调”页面选择“使用长连接接收事件”然后添加事件im.message.receive_v1。这个事件负责接收用户发来的消息。如果你希望机器人进群也能响应再勾选im.chat.member.bot.added_v1。注意如果机器人能发消息但收不到消息九成是事件订阅没配或权限没审过。先回这个页面检查。4.4 启动服务并验证回调回到服务器执行docker-compose up -d然后用docker-compose logs -f看日志。如果看到类似feishu gateway started和model connected的输出说明服务起来了。接下来在飞书里给机器人发一条私聊消息比如“你好”。观察日志应该能看到收到消息、调用模型、返回回复的完整链路。如果日志里出现401或invalid api key说明 TaoToken 的 Key 填错了如果出现app_id not found说明飞书凭证有问题。你也可以用 curl 直接测模型连通性绕过飞书先确认 Key 可用curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: gpt-4, messages: [{role: user, content: ping}] }返回里有choices字段就说明 Key 和地址都没问题。这一步能帮你快速区分是模型侧的问题还是飞书侧的问题。5. 本篇常见错误排查部署过程中我踩过的坑基本集中在下面几个按出现频率排序。错误一docker-compose up报端口占用。服务器上 8080 被别的服务占了。改.env里的PORT和docker-compose.yml的端口映射比如改成8090:8090同时config.toml里的port也要同步改。错误二容器启动后立刻退出。用docker-compose logs看退出原因。最常见的是config.toml格式错误TOML 对缩进和引号比较敏感建议用在线 TOML 校验工具过一遍。错误三飞书回调验证失败。飞书要求回调地址可访问。如果你在本地测试需要把服务暴露到公网或者用内网穿透工具。生产环境建议直接部署在有公网 IP 的服务器上并在飞书后台把服务器 IP 加入白名单。错误四模型返回超时。检查BASE_URL是否写成了https://taotoken.net/api/末尾多了斜杠有些客户端拼接路径时会出问题。另外确认服务器能正常访问外网。错误五改了.env但没生效。Docker Compose 不会自动重载环境变量改完要docker-compose down再up -d。如果只改了config.toml因为它是挂载进去的重启容器即可。错误六日志里出现model not found。MODEL_ID填的模型名不在 TaoToken 支持列表里。去控制台的模型对话页面确认一下准确的模型标识注意大小写。排查时有个通用思路先用 curl 测模型 API通了再测飞书回调最后测端到端。分层定位比一上来就盯着日志猜要快得多。6. 后续怎么用统一 Key 与长期编码场景服务跑起来之后日常使用其实很简单在飞书里直接 机器人 或者私聊消息会自动走 TaoToken 转发给模型。如果你后面想换模型只改.env里的MODEL_ID重启容器就行飞书侧完全不用动这就是统一 Key 的好处。对于需要长期跑编码任务或者 Agent 的场景比如让机器人在飞书里帮你处理代码问题、执行多轮对话建议关注 TaoToken 的 Coding Plan它在长会话和代码类任务上有更好的额度策略。你可以从控制台的 coding-plan 页面了解具体方案。如果接入过程中遇到 Key 相关的问题直接去 API Keys 页面重新生成一个然后更新.env重启即可。接入文档在 doc 页面有更详细的参数说明包括不同平台的回调配置差异。最后留一个实用习惯把docker-compose logs -f挂在一个终端窗口里飞书那边发消息这边实时看日志。哪一层断了日志里基本都能看出来。这套组合我用了几个月稳定性没问题唯一要注意的就是别把.env传到公开仓库。
【教程】用 Docker Compose 极简部署 OpenClaw 并接入飞书：TaoToken 统一 Key 配置实战
1. 为什么我选择用 Docker Compose 跑 OpenClaw 并接入飞书OpenClaw 是一个可以把大模型能力接到即时通讯平台上的开源网关你可以把它理解成一个“翻译官”一边连着模型 API一边连着飞书、Telegram 这类聊天工具消息进来它转发给模型模型回复它再送回聊天窗口。适合谁适合想让团队在飞书里直接用上 AI 助手、又不想自己从零写接入层的开发者也适合想快速验证“模型 IM”玩法的小团队。我最初是在一台 2 核 4G 的测试机上折腾的手动装依赖、配 Python 环境、改回调地址来回折腾了大半天。后来换成 Docker Compose 方案从拉镜像到飞书里收到第一条回复大概十几分钟。这篇就把这套极简流程完整写出来重点解决两个最容易卡住的地方环境变量怎么填、统一 Key 怎么配。你跟着做能拿到一份可直接复制的docker-compose.yml、.env和config.toml骨架最后我会演示怎么验证飞书回调和 API 连通性。需要提前说明的是模型侧我用的是 TaoToken 的统一 Key一个 Key 就能切换不同模型省得在多个平台之间来回注册。下面所有配置都围绕这个思路展开。2. TaoToken 前置准备拿到统一 Key 和接入地址在写 Compose 文件之前先把模型侧的凭证准备好。TaoToken 的作用是提供一个统一的 API 入口你不需要为每个模型单独申请 Key换模型时只改一个模型名参数就行。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台找到 API Keys 页面新建一个 Key。这个 Key 就是后面.env里的API_KEY格式通常是一串以sk-开头的字符串复制下来先存好页面关掉后不一定能再看到完整值。第二步确认接入地址。TaoToken 的 API 基础地址是https://taotoken.net/api注意这里不要加任何查询参数。这个地址对应.env里的BASE_URLOpenClaw 会用它拼接出最终的请求路径。第三步想好你要用哪个模型。TaoToken 支持多种模型模型名填在MODEL_ID里。如果你只是先跑通流程选一个通用对话模型即可如果后面要做代码相关的 Agent可以换成更强的编码模型。模型列表在控制台的模型对话页面能看到也可以直接在那个页面先发一条消息测试 Key 是否可用。提示Key 属于敏感信息不要提交到 Git 仓库。建议.env文件加入.gitignore或者用服务器上的环境变量注入。到这里你手里应该有三样东西API_KEY、BASE_URL固定为https://taotoken.net/api、MODEL_ID。接下来进入部署环节。3. 可复制的 docker-compose.yml 与 .env 配置这一节是全文的核心所有文件都可以直接复制。我假设你在 Linux 服务器上操作已经装好了 Docker 和 Docker Compose。如果还没装先用官方脚本装好这里不展开。先建一个工作目录比如/opt/openclaw进去之后创建三个文件docker-compose.yml、.env、config.toml。3.1 docker-compose.ymlversion: 3.8 services: openclaw-gateway: image: justlikemaki/openclaw-docker-cn-im:latest container_name: openclaw-gateway restart: unless-stopped env_file: - .env volumes: - ./config.toml:/root/.openclaw/openclaw.json - ./workspace:/root/.openclaw/workspace ports: - 8080:8080 logging: driver: json-file options: max-size: 10m max-file: 3这里有几个点值得说。env_file指向.env所有环境变量从这里注入不用在 Compose 里硬编码。volumes把本地的config.toml挂到容器内的配置文件路径这样改配置不用重建镜像。workspace目录用来持久化工作区数据容器重启不丢。端口映射8080:8080是给飞书回调用的后面飞书那边要填这个地址。3.2 .env 文件# 模型侧配置TaoToken 统一 Key MODEL_IDgpt-4 BASE_URLhttps://taotoken.net/api API_KEYsk-你的TaoToken密钥 # 飞书配置 FEISHU_APP_IDcli_你的appid FEISHU_APP_SECRET你的appsecret # 服务配置 PORT8080 LOG_LEVELinfoMODEL_ID按你实际想用的模型填BASE_URL固定写 TaoToken 的地址API_KEY换成你刚才复制的。飞书的两个值先留空也行等下一节拿到再回来填。3.3 config.toml 骨架[gateway] port 8080 log_level info [model] provider openai-compatible model_id ${MODEL_ID} base_url ${BASE_URL} api_key ${API_KEY} [platform.feishu] enabled true app_id ${FEISHU_APP_ID} app_secret ${FEISHU_APP_SECRET}这个骨架里用了${}占位符OpenClaw 启动时会从环境变量里读取实际值。这样配置和密钥分离改 Key 只动.env不用碰config.toml。文件都建好后先别急着启动因为飞书那边还没配。但你可以先跑一次docker-compose config检查语法有没有写错这个命令会解析 Compose 文件并打印最终配置不实际启动容器。4. 飞书机器人配置与回调验证飞书这一侧是新手最容易翻车的地方我按顺序拆开讲。4.1 创建自建应用并拿凭证登录飞书开放平台进入开发者后台创建一个“企业自建应用”。创建完成后在“凭证与基础信息”页面能看到App ID和App Secret把这两个值填回.env的FEISHU_APP_ID和FEISHU_APP_SECRET。4.2 开通权限在“权限管理”页面至少开通以下权限否则机器人收不到消息权限标识说明im:message消息发送和接收核心权限im:message.p2p_msg:readonly读取私聊消息im:message.group_at_msg:readonly接收群内 机器人 的消息im:message:send_as_bot以机器人身份发送消息开通后需要提交审核自建应用一般很快通过。4.3 配置事件订阅这是最关键的一步。在“事件与回调”页面选择“使用长连接接收事件”然后添加事件im.message.receive_v1。这个事件负责接收用户发来的消息。如果你希望机器人进群也能响应再勾选im.chat.member.bot.added_v1。注意如果机器人能发消息但收不到消息九成是事件订阅没配或权限没审过。先回这个页面检查。4.4 启动服务并验证回调回到服务器执行docker-compose up -d然后用docker-compose logs -f看日志。如果看到类似feishu gateway started和model connected的输出说明服务起来了。接下来在飞书里给机器人发一条私聊消息比如“你好”。观察日志应该能看到收到消息、调用模型、返回回复的完整链路。如果日志里出现401或invalid api key说明 TaoToken 的 Key 填错了如果出现app_id not found说明飞书凭证有问题。你也可以用 curl 直接测模型连通性绕过飞书先确认 Key 可用curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: gpt-4, messages: [{role: user, content: ping}] }返回里有choices字段就说明 Key 和地址都没问题。这一步能帮你快速区分是模型侧的问题还是飞书侧的问题。5. 本篇常见错误排查部署过程中我踩过的坑基本集中在下面几个按出现频率排序。错误一docker-compose up报端口占用。服务器上 8080 被别的服务占了。改.env里的PORT和docker-compose.yml的端口映射比如改成8090:8090同时config.toml里的port也要同步改。错误二容器启动后立刻退出。用docker-compose logs看退出原因。最常见的是config.toml格式错误TOML 对缩进和引号比较敏感建议用在线 TOML 校验工具过一遍。错误三飞书回调验证失败。飞书要求回调地址可访问。如果你在本地测试需要把服务暴露到公网或者用内网穿透工具。生产环境建议直接部署在有公网 IP 的服务器上并在飞书后台把服务器 IP 加入白名单。错误四模型返回超时。检查BASE_URL是否写成了https://taotoken.net/api/末尾多了斜杠有些客户端拼接路径时会出问题。另外确认服务器能正常访问外网。错误五改了.env但没生效。Docker Compose 不会自动重载环境变量改完要docker-compose down再up -d。如果只改了config.toml因为它是挂载进去的重启容器即可。错误六日志里出现model not found。MODEL_ID填的模型名不在 TaoToken 支持列表里。去控制台的模型对话页面确认一下准确的模型标识注意大小写。排查时有个通用思路先用 curl 测模型 API通了再测飞书回调最后测端到端。分层定位比一上来就盯着日志猜要快得多。6. 后续怎么用统一 Key 与长期编码场景服务跑起来之后日常使用其实很简单在飞书里直接 机器人 或者私聊消息会自动走 TaoToken 转发给模型。如果你后面想换模型只改.env里的MODEL_ID重启容器就行飞书侧完全不用动这就是统一 Key 的好处。对于需要长期跑编码任务或者 Agent 的场景比如让机器人在飞书里帮你处理代码问题、执行多轮对话建议关注 TaoToken 的 Coding Plan它在长会话和代码类任务上有更好的额度策略。你可以从控制台的 coding-plan 页面了解具体方案。如果接入过程中遇到 Key 相关的问题直接去 API Keys 页面重新生成一个然后更新.env重启即可。接入文档在 doc 页面有更详细的参数说明包括不同平台的回调配置差异。最后留一个实用习惯把docker-compose logs -f挂在一个终端窗口里飞书那边发消息这边实时看日志。哪一层断了日志里基本都能看出来。这套组合我用了几个月稳定性没问题唯一要注意的就是别把.env传到公开仓库。
