阿里云部署OpenClaw智能体网关：从环境准备到飞书接入全指南-代码聚汇网

阿里云部署OpenClaw智能体网关：从环境准备到飞书接入全指南

银星皓月·2026-08-30·阅读 22 GEO检测（免费）

OpenClaw阿里云Docker Compose

|难度：普通|阅读约 35 分钟

OpenClaw部署这件事，我前后在阿里云上折腾了三个晚上才完全跑通。说实话，网上关于这个项目的教程要么只讲概念，要么直接甩一串docker命令让你自己猜，对新手极其不友好。这篇我尽量把“为什么这么做”也讲清楚，而不是单纯给你一份复制粘贴的脚本。只要你的阿里云服务器已经买好，跟着这篇文章一步步来，熟练之后5分钟确实能完成一套基础集成；如果是第一次操作，预留30分钟比较稳妥。

1. 为什么选阿里云跑OpenClaw：服务器选型与环境准备的几个关键判断

1.1 OpenClaw到底解决什么问题

先对齐一下概念，OpenClaw本质上是一个智能体网关与编排平台，它做的事情是把你手里的大模型能力，通过统一的接口暴露给各种前端入口，比如微信、飞书、Web控制台，或者是其他自动化脚本。它和Dify这类偏向工作流编排的工具定位不同，OpenClaw更侧重“接入”和“路由”——你的用户从飞书发来一句话，它负责判断该调用哪个模型、携带哪些上下文、如何把结果返回给用户。

理解了这个定位，你就能明白为什么部署OpenClaw一定要有一台公网可达的服务器：它需要7x24小时在线接收消息，并且通过webhook或长连接与外部平台通信。本地电脑跑当然可以调试，但一旦要接入微信、飞书这类真实渠道，本地环境基本撑不住。

1.2 阿里云ECS的配置建议：2核4G是舒适起点

我目前主力跑OpenClaw的配置是2核4G的ECS，Ubuntu 22.04系统，部署了OpenClaw核心服务加一个轻量的模型代理，空闲时内存占用大约1.2G，跑起来之后稳定在2G上下。所以如果你只是想接入微信/飞书，日常对话量不大，2核4G完全够用。

但有两个例外：

如果打算在同一台服务器上跑本地大模型，比如Ollama加载Qwen系列或DeepSeek蒸馏版，建议直接上4核16G及以上，否则模型推理会把内存吃满，OpenClaw会被迫OOM重启。
如果计划接入NVIDIA NIM做GPU推理，那就要选带GPU的规格，比如阿里云的GPU实例，这个成本比较高，建议先用云API跑通业务，再考虑升级。

地域选择上，我建议选华东1（杭州）或华北2（北京），原因很简单：国内访问延迟低，且这两个地域的镜像源、OSS内网访问等配套最全。带宽按量付费即可，5Mbps起步，流量不大。

1.3 安全组端口规划：提前放行，别等部署完再找问题

很多新手在阿里云上部署完服务，发现浏览器访问不了控制台，第一反应是改服务配置，折腾半天才发现是安全组没放行端口。这块提前说清楚，免得你走弯路。

我整理了一份常用端口清单，按照你自己的需要添加安全组规则：

端口	用途	开放建议
22	SSH登录	建议只开放给固定IP，不要对0.0.0.0/0开放
8000	OpenClaw Control UI	首次部署需要公网访问，建议加IP白名单
8080	OpenClaw API Gateway	按需开放，如果只做服务端集成可仅内网开放
9000	Companion服务（可选）	与其他服务联调时使用，默认可以不暴露公网
11434	Ollama API（可选）	如果Ollama在独立机器上才需要放行，同机部署则不用

这里有一个值得注意的细节：安全组规则修改后立即生效，不用重启服务器。但如果你用了阿里云的防火墙服务，记得同步检查一下系统内部防火墙，避免出现“安全组放行了、系统防火墙又挡一道”的情况。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 5分钟部署路径拆解：从裸机到Control UI跑起来

2.1 为什么用Docker Compose而不是直接在宿主机装

OpenClaw的组件比较多，核心服务、Companion辅助进程、可能还要挂模型代理和消息连接器。如果用传统方式装，光Java/Python/Node.js这些运行时环境就能把人劝退，而且升级时容易把系统搞乱。

用Docker Compose的好处是：所有组件各自封装在容器里，环境隔离，升级只需拉新镜像，回滚只需切回旧镜像标签。对OpenClaw这种迭代速度极快的开源项目来说，这一点非常实用——我几乎每周都能看到新版本发布，用Compose管理意味着我只需改一行镜像版本号，然后docker compose up -d就能完成升级，数据卷不受影响。

2.2 服务器初始化：安装Docker与Compose插件

假设你拿到一台全新的Ubuntu 22.04 ECS，SSH登录后依次执行：

bash复制# 更新apt源
sudo apt update && sudo apt upgrade -y

# 安装依赖
sudo apt install -y ca-certificates curl gnupg lsb-release

# 添加Docker官方GPG密钥和仓库
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker及相关插件
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 将当前用户加入docker组，避免每次sudo
sudo usermod -aG docker $USER

# 验证
docker --version
docker compose version

在执行完usermod之后，记得退出SSH重新登录，否则当前会话没有权限直接使用docker命令。这一步很多人会漏掉，然后发现命令行报权限错误，还以为是安装出了问题。

2.3 编写Compose配置文件：核心服务的编排逻辑

新建一个工作目录，比如/opt/openclaw，在里面创建docker-compose.yml。我先给出一份基础可用的配置，再解释每一段的意思：

yaml复制version: "3.8"

services:
  gateway:
    image: openclaw/gateway:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    ports:
      - "8000:8000"
      - "8080:8080"
    environment:
      - OPENCLAW_MODEL_PROVIDER=openai
      - OPENCLAW_MODEL_NAME=gpt-4o-mini
      - OPENCLAW_API_KEY=${OPENAI_API_KEY:-}
      - OPENCLAW_BASE_URL=https://api.openai.com/v1
      - OPENCLAW_DATA_DIR=/data
      - OPENCLAW_ENABLE_AUTH=true
      - OPENCLAW_WEB_TOKEN=${OPENCLAW_WEB_TOKEN:-change-me}
    volumes:
      - openclaw_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3

  companion:
    image: openclaw/companion:latest
    container_name: openclaw-companion
    restart: unless-stopped
    depends_on:
      - gateway
    environment:
      - OPENCLAW_GATEWAY_URL=http://gateway:8080
      - OPENCLAW_LOG_LEVEL=info

volumes:
  openclaw_data:

几个关键配置说明：

OPENCLAW_MODEL_PROVIDER=openai 代表使用OpenAI兼容协议的模型服务商。这个设计让OpenClaw可以对接几乎所有主流模型服务，只要对方提供OpenAI兼容的API接口。
OPENCLAW_BASE_URL 是API地址。如果你使用的是阿里云百炼的模型服务，这里可以填百炼提供的兼容地址；如果用DeepSeek官方API，就填DeepSeek的地址。这是OpenClaw能“一次接入、到处路由”的底层逻辑。
OPENCLAW_ENABLE_AUTH=true 和 OPENCLAW_WEB_TOKEN 是Control UI的访问凭证。强烈建议从第一分钟就开启认证，否则任何能访问到你服务器8000端口的人都能直接操作你的智能体。

2.4 使用环境变量文件管理密钥

不要把API密钥直接写死在Compose文件里。我的做法是在同目录下创建一个.env文件：

bash复制OPENAI_API_KEY=sk-xxxxx
OPENCLAW_WEB_TOKEN=你的控制台密码

然后确保.env文件的权限是600：

bash复制chmod 600 .env

Compose会自动读取同目录下的.env文件填入变量。这样即使将来要把整个配置文件分享给同事，也不会泄露密钥。

2.5 启动与验证：5分钟从零到可访问

配置全部准备好之后，启动命令很简单：

bash复制cd /opt/openclaw
docker compose up -d
docker compose logs -f gateway

看到日志中出现类似Server started on port 8000或Gateway ready的提示，说明核心服务已经起来了。此时在浏览器访问：

code复制http://服务器公网IP:8000

输入你在OPENCLAW_WEB_TOKEN里设置的密码，就能看到Control UI。首次进入时建议先创建一个管理员账号，后续所有会话管理、模型切换、连接器配置都可以在界面上操作，不一定非要改配置文件。

3. 从“跑起来”到“能用”：模型接入、密钥管理与首次对话配置

3.1 模型提供方的选择逻辑：云API优先，本地模型备用

部署完OpenClaw之后，最重要的事情就是让它能调用一个真正会“说话”的模型。这里有两种主流路线：

云API路线：调用DeepSeek、阿里云百炼、智谱等国内服务商的OpenAI兼容接口，好处是零运维、推理速度快，按量付费成本可控。
本地模型路线：用Ollama在同机或局域网内运行开源模型，好处是数据不出内网、无按量费用，但需要较高的硬件配置，且推理速度受GPU/CPU性能限制。

我的建议是：首次跑通流程用云API，因为配置简单、出问题容易排查。等OpenClaw的各个组件都正常工作了，再考虑接入本地模型作为降级方案。

3.2 以DeepSeek为例：修改Compose环境变量

在国内环境，DeepSeek的API兼容性做得很不错，我用它作为示例。修改docker-compose.yml中的gateway环境变量：

yaml复制    environment:
      - OPENCLAW_MODEL_PROVIDER=openai
      - OPENCLAW_MODEL_NAME=deepseek-chat
      - OPENCLAW_API_KEY=${OPENCLAW_API_KEY:-}
      - OPENCLAW_BASE_URL=https://api.deepseek.com/v1

然后在.env中添加：

bash复制OPENCLAW_API_KEY=sk-你的DeepSeek密钥

改完之后执行：

bash复制docker compose up -d
docker compose restart gateway

注意，这里我用了restart而不是down再up，因为数据卷已经挂载好了，不需要重建容器。如果改了端口或新增了服务，才需要docker compose up -d重新创建。

3.3 在Control UI中发起第一次对话

打开Control UI，在会话窗口输入：

code复制你好，请用一句话介绍你自己。

正常情况下，OpenClaw会调用配置好的模型返回结果。如果这一步通了，说明整个链路——Control UI到Gateway再到模型API——已经全部打通。

如果报错，大概率逃不开两类问题：

401鉴权失败：检查API Key是否有余额、是否复制完整。
404模型不存在：检查OPENCLAW_MODEL_NAME是否和服务商实际提供的模型名完全一致。

这里我特意把“模型名一致”列为重点，因为后面踩坑部分会详细展开，很多人在这里就被卡住了。

3.4 通过Ollama接入本地模型：备用方案的完整配置

如果你打算让OpenClaw在断网环境下也能工作，或者不想为高频测试支付API费用，本地模型是很好的备用方案。假设你在同一台服务器上装了Ollama，监听端口是11434，配置如下：

首先拉取一个合适的模型：

bash复制ollama pull qwen2.5:7b

然后修改OpenClaw的Compose环境变量，将模型提供方指向Ollama：

yaml复制    environment:
      - OPENCLAW_MODEL_PROVIDER=openai
      - OPENCLAW_MODEL_NAME=qwen2.5:7b
      - OPENCLAW_API_KEY=ollama   # 本地Ollama不做鉴权，占位即可
      - OPENCLAW_BASE_URL=http://host.docker.internal:11434/v1

如果OpenClaw和Ollama在同一台宿主机上，在Docker容器内访问宿主机不能用localhost，要用host.docker.internal（Linux上如果Docker版本较新一般已支持）。如果Ollama在另一台机器上，这里就填那台机器的内网IP地址，比如http://192.168.1.50:11434/v1。

3.5 阿里云百炼模型的接入补充

除了DeepSeek这类独立API服务商，阿里云百炼也是很多人的选择。接入逻辑完全一样，只是把OPENCLAW_BASE_URL换成百炼提供的兼容地址，模型名换成百炼平台上的具体模型名称，比如qwen-plus、qwen-max等。百炼的API Key在阿里云控制台的“百炼”页面申请，注意区分主账号Key和子账号Key——生产环境强烈建议用RAM子账号的Key，只授予模型调用权限，避免主账号Key泄露导致整个云账号被拖下水。

4. 让智能体融入工作流：接入飞书、微信与自建系统的那个“5分钟”是怎么实现的

4.1 理解连接器：OpenClaw的集成轴心

OpenClaw之所以“好用”，不是因为它本身聊天能力多强，而是它把“接入外部渠道”这件事做成了标准化的连接器。你可以这样理解：核心Gateway是一个大脑，连接器就是大脑的四肢——微信、飞书、网页Widget、API回调，各自负责把消息送进来、把回复带回去。

在这个设计下，你每新增一个渠道，只需要配置一个新的连接器，而完全不需要改模型路由、Prompt模板、会话管理这些核心逻辑。这也是为什么很多团队把它作为统一的智能体中台来用。

4.2 接入飞书：从创建应用到收到第一条消息

我以飞书为例，因为飞书对开发者的支持在国内办公软件里算是最友好的，机器人创建流程也清晰。

步骤如下：

登录飞书开放平台，创建企业自建应用。
在“添加应用能力”中选择“机器人”，并启用事件订阅。
在“事件与回调”页面，添加事件message.receive_v1（接收消息）。
将“请求地址”填为OpenClaw对应的webhook地址，格式如下：

code复制http://你的公网IP:8080/connector/lark/webhook

在OpenClaw Control UI的连接器管理页面，选择Lark/Feishu，填入飞书应用的App ID和App Secret。
保存后，在飞书客户端中找到这个机器人，发一条“你好”，正常情况下会收到OpenClaw的回答。

这里有一个非常容易踩的坑：飞书的请求地址必须是公网可访问的HTTPS地址，纯HTTP地址在有些情况下会被飞书拒绝。如果你暂时没有域名和SSL证书，可以先在飞书后台把“加密策略”调整为不校验，或者用阿里云的免费SSL证书给域名加上HTTPS，流程不复杂但需要提前准备。建议正式使用前把HTTPS配置好，否则飞书的事件回调时好时坏，排查起来非常头疼。

4.3 接入微信：与企业微信的路径选择

提到微信，必须先说清楚一个边界：个人微信的自动化控制在官方规则里是非常敏感的，不适合作为技术教程推广。OpenClaw官方在接入微信时，实际走的是企业微信或微信客服体系，而不是破解个人微信协议。我的做法是通过企业微信的应用机器人接入，流程和飞书机器人类似：

在企业微信管理后台创建自建应用。
获取企业ID（Corp ID）、应用AgentId和Secret。
在OpenClaw连接器中填写这些参数，设置接收消息的URL。
配置企业可信IP（就是你服务器的公网IP）。

企业微信的机器人在配置完成后，需要被成员添加到通讯录或群聊中才能收到消息。这里有个细节：企业微信要求接收消息的URL必须返回特定校验参数，OpenClaw一般会自动处理，但如果遇到校验失败，记得检查服务器公网IP是否已加入企业微信的“可信IP”列表。

4.4 把OpenClaw和自建系统打通：API调用与事件回调

除了IM渠道，更常见的场景是把OpenClaw的能力嵌入到现有系统里。比如你有一个自动化流程，希望在收到某种日志告警时自动让智能体分析原因，而不是直接调用模型API。这种场景下，OpenClaw本身就是你的中间层，你只需要以HTTP客户端的方式请求它的Gateway接口：

bash复制curl -X POST http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENCLAW_WEB_TOKEN" \
  -d '{
    "message": "收到告警：Nginx错误率超过5%，请分析可能原因",
    "session_id": "alert-20260211-001",
    "channel": "api"
  }'

我把这个接口称为“后门”——它绕过了IM聊天界面，让你可以在任意自动化脚本中调用OpenClaw的完整能力，包括工具调用、记忆读取、多轮上下文管理。对已经在用Jenkins做持续集成、或用Prometheus做监控的同学来说，OpenClaw完全可以作为告警分析的辅助节点，收到告警后自动生成诊断摘要，再通过飞书/企业微信推给值班同学。

5. 部署后的第一轮踩坑：三个高频故障的完整排查链路

5.1 Control UI did not start：先分清是端口没起还是容器在重启

这是我在OpenClaw社区里看到频率最高的问题之一。现象是浏览器访问http://IP:8000超时或拒绝连接，而docker compose ps显示容器状态异常或反复重启。

我的排查链路是这样的：

第一步，看容器状态：

bash复制docker compose ps

如果显示Restarting或Exit 1，直接看日志：

bash复制docker compose logs -f gateway

常见的日志报错有两类：

端口占用：宿主机上已经有别的进程占了8000端口。用sudo lsof -i :8000查看，把旧进程停掉或修改OpenClaw的端口映射。
数据库或数据卷初始化失败：这个通常是因为数据目录权限不对。查看数据卷是否创建成功，必要时删除重建（注意，删除数据卷会丢失历史会话数据，操作前先备份）。

如果容器状态是Up，但浏览器还是访问不了，重点检查阿里云安全组是否放行了8000端口，以及ECS的系统防火墙是否拦截了外部到该端口的访问。

5.2 agent failed before reply: unknown model: deepsee

这个报错非常有代表性。我见过很多人配置模型时，在OpenClaw里填了模型名deepsee-xxx，或者不同厂商的模型名混着用，结果启动后agent直接失败，连对话窗口都打不开。

实际上，unknown model: deepsee这个报错的根因就一个：你填的模型名，在配置的OPENCLAW_BASE_URL对应的服务商那里不存在，或者服务商返回的可用模型列表里没有这个名字。

排查方法很简单：

bash复制curl -s https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer $OPENCLAW_API_KEY" | jq '.data[].id'

把返回的模型ID列表和你在OPENCLAW_MODEL_NAME里填的值做对比，一定要做到一字不差。以DeepSeek为例，正确的模型名是deepseek-chat而不是deepseek，更不是deepseek-v3这种接口侧不认的名字。

另外，还有一个隐藏原因：如果你在Control UI的会话配置里手动指定了模型，它会覆盖全局配置。此时即使docker-compose.yml里的模型名是对的，UI层指定的那个错误模型名还是会生效。遇到这种情况，去Control UI的会话设置里把模型重置为“默认”即可。

5.3 zero token 安装后 Agent 无响应：离线模式下的模型路由缺失

所谓zero token模式，是指完全不用任何云端API的部署方式，所有推理都走本地模型。这种模式在Compose环境变量里通常表现为OPENCLAW_API_KEY留空或不配置。

但问题在于：OpenClaw本身只是一个编排层，它并不内置模型推理能力，所以如果本地没有配置Ollama或其他推理服务，agent就会因为“没有可用的模型后端”而一直处于失败状态。报错五花八门，有的直接不回复，有的在日志里显示model not configured。

解决办法是，先按正文3.4节完成Ollama配置，然后在Ollama里确认模型确实已拉取：

bash复制ollama list

如果模型存在且Compose配置正确，再重启Gateway容器：

bash复制docker compose restart gateway

实测下来，零token模式能否工作，完全取决于本机推理能力。用2C4G的ECS跑7B模型，每个token生成速度大约在10-20 tokens/s，简单问答可以接受，但长文本生成明显吃力。如果要追求更好的体验，建议用GPU实例或者干脆回归云API模式。

5.4 通用调试三板斧：日志、配置校验、干净重启

在OpenClaw排错的过程中，我总结了一个“三板斧”原则，遇到问题先按顺序执行，能解决80%的疑难杂症：

第一板斧，看日志。永远先看日志，而不是猜。docker compose logs -f能告诉你错误到底出在网关、连接器、还是模型调用层。

第二板斧，校验配置。检查.env里每个变量的值，尤其注意：API Key是否有特殊字符导致解析错误、Base URL末尾是否缺了/v1、模型名是否完全一致。配置文件的缩进问题在YAML里尤其常见，一个多余空格就能让整个服务起不来。

第三板斧，干净重启。不要只restart，有时候容器内部状态已经乱了，需要彻底重建：

bash复制docker compose down
docker compose up -d

重建容器不会丢失数据卷中的数据，所以放心执行。

写在最后

这篇内容有点长，但如果你从头看到这里，应该已经能独立完成OpenClaw在阿里云上的全流程部署了。最后再分享一个我个人的习惯：每次修改OpenClaw的配置或连接器之后，我会把/opt/openclaw下的docker-compose.yml和.env文件用git做一次提交。这个习惯帮了我大忙——有两次我在调整连接器参数时把配置改坏了，只需要git checkout回滚到前一个可用版本，再对比一下哪里改错了，整个排查过程不超过两分钟。开源项目迭代快，配置文件是唯一需要自己维护的资产，把它管好，后面的使用成本会低很多。