企业官网建设流程全解析

最近在Windows上折腾开源AI助手OpenClaws，目标很简单：让飞书成为日常的AI入口，后端换成阿里云和腾讯云的国内大模型，跑通一个真正能聊天、能干活的本地Agent。整个过程中踩了不少坑，尤其是Windows环境下的依赖问题、飞书回调校验、还有国内模型的参数差异。这篇就完整记录一下我的实操过程，给同样想“飞书+国内大模型+本地Agent”组合的朋友做个参考。

先说清楚：这里说的OpenClaws是一个开源的个人AI助手框架，核心作用是把消息平台（飞书）和大模型API（阿里云、腾讯云）粘合在一起，你可以把它理解成“AI管家”的网关层。它支持多模型路由、多消息渠道接入，也支持一定的任务编排能力。我习惯叫它“Claws”，项目仓库里的大小写不影响后续配置。

这篇文章适合这些人：想在自己的电脑上部署一个私有AI机器人，不打算把聊天记录都送到国外服务，希望用国内云厂商的模型（通义千问、混元），同时又想用飞书作为统一操作界面的人。如果你Windows基础一般，按照下面的步骤也能跑通。

1. 方案拆解：OpenClaws到底是个什么东西

1.1 先纠正一个拼写问题

很多人包括我在刚开始搜索时，会把项目名写成“openclaws”，实际上它更常见的写法是“OpenClaw”或者“OpenClaws”这两个形式在社区里都有人用。我更倾向于把OpenClaws理解为“OpenClaw”的复数/动态形态，因为它能同时连接多个“爪牙”（消息平台和模型后端）。如果你下载代码时发现仓库名是单数形式，别慌，配置逻辑完全一样。

这个项目的核心定位是“个人AI助理网关”。它本身不训练模型，也不做知识库，它只做三件事：

• 接收来自不同IM平台（飞书、钉钉、Slack等）的用户消息
• 把消息经过系统提示词和上下文处理，转成大模型API请求
• 把模型返回的文本/工具调用结果，再分发回对应的IM平台

所以它把“消息接入”“模型调用”“任务执行”这三个环节解耦了。你可以在飞书上跟它聊天，在钉钉上跟它聊天，但后端可以共用同一个模型。反过来，你也可以配置多个模型，让它在不同场景下自动切换。

1.2 架构选择：为什么是“消息平台+Agent+模型”三层

在动手之前，我想过要不要直接用飞书机器人内置的AI能力，或者直接写个简单的Web服务转发到飞书Webhook。后来发现都不如OpenClaws灵活。

第一，飞书本身提供的是“即时通信能力”，不是“Agent能力”。你当然可以在飞书开放平台的后台配一个回调，把自己的服务器地址填进去，但那只能处理简单的关键词回复。如果你想让机器人自己判断“该调用哪个工具”“要不要查天气”“要不要执行一段脚本”，就必须有一个Agent层来承载这些逻辑。

第二，直接用云厂商SDK写单机脚本的话，你还需要自己处理消息的去重、会话保持、异步回调、重试机制。这些OpenClaws已经内置了，没必要重复造轮子。

第三，OpenClaws把模型接入做成了“统一的Provider接口”。不管你是调OpenAI兼容接口，还是调阿里云DashScope，还是调腾讯云混元，最终面向你的都是同一种配置结构。这意味着以后你想换模型，只需要改配置文件，不用改动代码逻辑。

我最终选择的架构是这样的：

飞书客户端 --> 飞书开放平台 --> OpenClaws（本地运行） --> 阿里云通义千问 / 腾讯云混元 ^ | | v +---------- 飞书长连接回传 <-------------+

OpenClaws在Windows上以本地服务方式运行，主动和飞书建立长连接（长连接模式不需要公网IP），收到消息后调用模型API，等模型返回再通过长连接发回飞书。这个模式对个人用户特别友好，因为你不用去搞一台公网服务器，也不用给家里的宽带做端口映射。

1.3 为什么先跑飞书，而不是微信或钉钉

微信机器人的接口是被严格限制的，个人号接入第三方框架有风险，企业微信的机器人又不够灵活。钉钉的开放接口比较复杂，权限申请步骤多。飞书在个人开发者权限上比较友好，你甚至不需要企业认证，用个人身份创建一个企业（团队）后就能开通机器人能力，还能用长连接模式省去服务器回调配置。

另外飞书的消息卡片机制非常好用。你可以把机器人的返回内容渲染成带格式的卡片，代码块、表格、引用都能直接展示。这一点在实际体验中很重要，因为大模型的输出如果全是纯文本，在聊天窗口里会非常难阅读。

2. Windows下的环境准备

2.1 运行方式选型：Docker还是本地源码

OpenClaws官方推荐用Docker部署，因为环境依赖比较杂（Python、Node、Redis等）。但在Windows上，Docker Desktop本身就是一个大坑：它需要WSL2、Hyper-V，而且对老版本Windows支持不好。

我个人的建议是分情况：

• 如果你的Windows是Win10/11专业版或企业版，并且愿意装WSL2，那么Docker Desktop方案最省心。把所有依赖都封装在镜像里，升级也好处理。
• 如果你不想动WSL2，或者电脑配置比较老（比如8GB内存以下），建议直接本地源码运行。OpenClaws底层的Python部分和Node部分可以分开装，虽然麻烦一点，但可控性更高。

我最后用的是“本地源码运行+Docker补依赖”的混合方案：主服务用Python虚拟环境跑，Redis用Docker开一个容器。这样既避免了全量Docker构建的时间，又不用在Windows上折腾原生Redis。

2.2 安装Docker Desktop与镜像加速（国内）

如果你选择Docker路线，第一步肯定是安装Docker Desktop。安装包直接去官网下载就行，注意安装完成后需要重启系统，并在设置里勾选“Use WSL 2 instead of Hyper-V”或“Use WSL 2 based engine”。

国内网络环境下，直接从Docker Hub拉镜像大概率会超时。务必要配置镜像加速器。这个加速器可以在Docker Desktop的“Docker Engine”配置里修改，也可以直接改C:\Users\你的用户名\.docker\config.json。

我用的镜像源配置示例：

{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://dockerproxy.com", "https://docker.nju.edu.cn" ] }

配好之后重启Docker Desktop，再拉镜像就快多了。记住多配几个镜像源，因为有些源隔三差五会失效。

2.3 获取OpenClaws并初始化配置

不管用哪种方式，你都得先把代码拉到本地。假设你用的是git：

git clone https://github.com/你的项目地址/OpenClaws.git cd OpenClaws

初次启动之前，务必先复制示例环境变量文件：

cp .env.example .env

Windows下没有cp命令的话，用PowerShell的Copy-Item：

Copy-Item .env.example .env

OpenClaws的配置集中在.env文件和对应的config目录里。你需要重点关心的变量包括：

• 消息平台配置：飞书App ID、App Secret、长连接开关
• 模型配置：API Key、模型名称、Base URL
• 服务端口：默认通常为8000或8080，不要和本地其他服务冲突
• 日志级别：调试时建议设为DEBUG，正式跑起来再调回INFO

如果你用的是Docker Compose方案，在docker-compose.yml里会有对应的环境变量映射。本地源码运行的话，直接编辑.env就好。

3. 飞书机器人接入全流程

3.1 在飞书开放平台创建应用

这一步是整个链路里和OpenClaws关系最小、但最容易出错的一步。很多人卡在权限配置上。

先打开飞书开放平台（open.feishu.cn），用你的飞书账号登录。如果你之前没有企业，系统会引导你创建一个“企业”，整个过程是免费的，个人用户也能创建，不需要上传营业执照。

创建好后，进入“开发者后台”，点击“创建企业自建应用”。名称可以随便填，比如“AI助理”。创建完成之后，你会看到一个App ID和一个App Secret，这两个值就是OpenClaws连接飞书要用的核心凭证。

3.2 配置事件订阅与机器人能力

拿到App ID和App Secret之后，还要给这个应用开通两个关键能力：

第一个是“机器人”能力。在应用详情页的“添加应用能力”里找到“机器人”，添加后你的应用就会拥有一个机器人账号，这个账号会在飞书通讯录里显示，用户可以直接搜索到它并发消息。

第二个是“事件订阅”能力。这里有个重要的选择：OpenClaws用的是长连接模式，所以你不需要填“请求地址”，而是要在“事件订阅”页面选择“使用长连接接收事件”。这是和传统Webhook模式最大的区别。

长连接模式下，你需要订阅的事件类型包括：

• im.message.receive_v1：接收消息
• message.receive_v1：部分版本下也用这个
• im.message.message_read_v1：消息已读（非必须，但建议开启）

订阅完事件之后，飞书会要求你配置权限。最容易漏掉的是“读取用户发给机器人的单聊消息”和“获取用户基本信息”这两项。权限标识分别是：

• im:message
• im:message.group_at_msg
• im:chat.preview

在“权限管理”页面逐个开启，然后点击“开通”。这一步不麻烦，但如果不加这些权限，OpenClaws可能只收到消息内容，却拉不到发送者信息，后续做会话级上下文就会莫名其妙地故障。

3.3 打通OpenClaws与飞书的长连接

OpenClaws侧需要把飞书的配置填到.env里：

FEISHU_APP_ID=替换成你的App ID FEISHU_APP_SECRET=替换成你的App Secret FEISHU_APP_MODE=long_connection

如果你使用的是本地源码方式，启动服务的命令一般是：

python main.py start

首次启动时，OpenClaws会通过飞书API获取Access Token，然后建立长连接。这个过程不需要公网IP，也不需要配置回调URL。启动日志里如果出现类似“connect to feishu gateway success”的字样，说明长连接已经建立成功。

这时你可以回到飞书，向你的机器人发一句“你好”，正常情况下它会回复一个欢迎语或提示信息。如果没有任何反应，优先去飞书开放平台的“事件订阅”页面，查看“事件监控”里的最近接收记录，确认事件有没有推过来。

3.4 飞书侧的安全校验配置

飞书开放平台有三种安全校验方式：Verification Token、Encrypt Key、签名校验。OpenClaws默认会要求你在配置里填上Verification Token，这个Token在飞书“事件订阅”页面的底部就能找到。

Encrypt Key也建议开启。开启加密后，飞书推送的请求体会用AES加密，OpenClaws需要在.env里配置同样的Encrypt Key才能解密：

FEISHU_ENCRYPT_KEY=替换成你的Encrypt Key

我这个环节踩过一个坑：只配了Verification Token，没同步Encrypt Key，导致OpenClaws收到的消息全是乱码，日志报的是“decrypt message failed”。后来把Encrypt Key填上，重启服务，问题立刻消失。

提示：飞书开放平台里的“签名校验”是给Webhook模式用的。如果你用长连接模式，可以不用关注签名校验，但OpenClaws内部会做消息合法性校验，所以飞书页面上如果要求设置校验策略，选“默认”即可。

4. 阿里云与腾讯云模型接入

4.1 阿里云通义千问：开通百炼平台，拿到API Key

阿里云的模型接入走的是“阿里云百炼”（Model Studio）平台。你需要在阿里云控制台搜索“百炼”或“大模型服务平台”，然后开通服务。开通成功后，进入“API-KEY”管理页面，创建一个新的API Key。

这个API Key是后续所有模型调用的凭证，作用类似于OpenAI的sk-xxx。注意API Key只会在创建时完整显示一次，一定要先保存好。

通义千问的模型名称比较有讲究。不同时间的有效模型名会和文档不一致。我写这篇文章时，推荐使用以下命名：

如果你有特定的垂直需求，比如数学推理或代码生成，还可以选qwen-math-plus、qwen-coder-plus这类专项模型。

在OpenClaws里配置阿里云模型时，核心要填三项：

DASHSCOPE_API_KEY=你的阿里云API Key DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 DASHSCOPE_MODEL=qwen-plus

这里要注意base_url一定写compatible-mode的地址。阿里云百炼提供了OpenAI兼容接口，OpenClaws可以直接用OpenAI SDK的方式对接。如果你填成原生的DashScope地址，反而会报接口格式错误。

4.2 腾讯云混元：从密钥管理到调用地址

腾讯云的模型接入路径和阿里云不一样。腾讯云混元大模型需要在腾讯云控制台搜索“混元大模型”或“智能创作”开通权限。开通后，你需要去“访问管理”->“访问密钥”页面创建一对SecretId和SecretKey。

注意：混元的API认证方式默认是“密钥签名”而不是单纯的API Key，所以你在OpenClaws里需要同时配置SecretId和SecretKey两个值，而不是只配一个Key。

我试过两种对接方式：

第一种是使用“腾讯云AI代码助手”风格的OpenAI兼容地址。腾讯云官方提供了https://api.hunyuan.cloud.tencent.com/v1这个OpenAI兼容端点，但使用时需要在请求头里附加腾讯云签名信息。OpenClaws内置了对AWS风格的签名支持吗？不一定。因此我更推荐第二种方式。

第二种是使用OpenClaws的“自定义Provider”功能，在配置里指定一个腾讯云SDK的转发脚本作为中间桥。不过大部分场景下，其实可以先混元控制台提供的“API调试”页面拿到一个临时Token，再用OpenAI兼容接口直接调。这个临时Token很短时间就过期，不适合长期跑服务。

后来我发现，腾讯云已经更新了混元的API策略，新申请的账号可以在“混元大模型控制台”直接生成一个hunyuan-api-key，供OpenAI兼容模式使用。如果你有这个API Key，配置就更简单：

HUNYUAN_API_KEY=你的腾讯云API Key HUNYUAN_BASE_URL=https://api.hunyuan.cloud.tencent.com/v1 HUNYUAN_MODEL=hunyuan-turbos-latest

模型名称推荐使用hunyuan-turbos-latest或hunyuan-pro。在OpenClaws的模型列表里，你要确保把腾讯云的Provider也注册上，这样才能在下发指令时切换到混元模型。

4.3 在OpenClaws里配置多模型路由

OpenClaws比较香的地方是可以同时挂多个模型，然后通过配置决定什么场景走哪家。比如日常闲聊走qwen-turbo，重要任务走hunyuan-pro，或者反过来。

在配置文件里，通常会有一个模型路由表（models.yaml或config/models.json），结构大致如下：

models: - name: qwen-plus provider: dashscope api_key: ${DASHSCOPE_API_KEY} base_url: ${DASHSCOPE_BASE_URL} default: true - name: hunyuan-turbos-latest provider: hunyuan api_key: ${HUNYUAN_API_KEY} base_url: ${HUNYUAN_BASE_URL} default: false

配好之后，你要让飞书机器人知道该用哪个模型。建议在对话指令里加一个快捷切换，比如发送“/model qwen-plus”就切换到通义千问，发送“/model hunyuan-turbos-latest”就切换到混元。这样对比两个模型的回答质量时会非常方便。

需要注意两个模型在“系统提示词”上的兼容性。阿里云通义千问对中文系统提示词的遵循度很高，腾讯云混元则更偏向简洁风格。我的实践是：给不同模型分配不同的System Prompt前缀，OpenClaws支持按模型名覆盖提示词，可以最大化各自的效果。

5. 实测中踩过的坑与排查速查表

5.1 飞书收不到消息的排查链

飞书机器人没有反应，这是最常见的故障。我强烈建议按下面这个顺序排查：

先看服务进程还在不在。Windows下有时候Python服务会莫名退出，但因为窗口还开着，你误以为它在正常运行。所以第一步是在终端里重新执行启动命令，观察有没有报错。

再看飞书开放平台的“事件订阅”页面，里面有一个“调试”标签，可以模拟事件推送。如果模拟推送都看不到，说明应用没被正确订阅，或者长连接没有建立。如果模拟推送能看到，但你给机器人发消息它不回，问题大概率出在OpenClaws的鉴权配置上（App Secret或Encrypt Key错误）。

最后检查日志。日志一般在logs目录下，或者你配置的日志文件路径。重点看有没有im.message.receive_v1相关的调用记录。如果日志一直在刷重连，说明飞书网关和本地服务的连接不稳定。

5.2 模型调用失败：超时、限流与鉴权

阿里云和腾讯云模型都面临三个共性问题：超时、限流、鉴权失败。

超时一般发生在模型响应较慢时。通义千问的qwen-max在长上下文场景下可能要20秒以上，而OpenClaws默认的HTTP超时时间往往是15秒。这种情况下，你需要把模型Provider的超时时间调大。

OpenClaws里通常用timeout字段配置：

models: - name: qwen-max timeout: 60

限流问题比较隐蔽。阿里云百炼和腾讯云混元的新账号默认都有较低的QPS限制（每秒调用次数），比如阿里云可能是5 QPS，腾讯云可能是2 QPS。如果你配置了多个渠道同时请求，就可能触发限流。解决办法有两个：一是在OpenClaws里开启“请求排队”策略，二是把模型降级到turbo版，不至于把QPS打满。

鉴权失败主要看两个点：API Key是否过期或被删，以及base_url是否填错。如果你在别的SDK测试能通，但OpenClaws里报401，优先检查环境变量是否被加载。Windows下.env文件的编码有时会是UTF-8 BOM，导致读取到的Key字符串带了一个看不见的前缀字符，这种问题非常坑。

5.3 Windows特有坑：路径、端口、时区

Windows下跑这类服务，路径分隔符和端口占用是最常见的两个麻烦。

OpenClaws默认使用正斜杠/来拼接文件路径，但Windows的路径是反斜杠\。如果你在配置里指定了工作目录，比如WORK_DIR=C:\Users\me\data，在YAML里这个反斜杠会被转义成字符C:\Users\me\data吗？不一定。建议统一使用双反斜杠\\或正斜杠/来避免解析错误。

端口占用也很常见。OpenClaws默认服务端口如果是8000，那你在Windows上很快会碰到这个端口被其他程序占用的情况。解决办法是改.env里的服务端口，比如改为18000。前提是飞书长连接模式对端口没有要求，因为长连接是OpenClaws主动外连飞书网关，不是飞书连你。

时区问题容易被忽略。OpenClaws默认使用UTC时间，如果你不设置系统时区，飞书消息里的时间戳会显示成差8小时的状态。建议在.env里加一行：

TZ=Asia/Shanghai

这样以后做会话持久化、定时任务时，时间逻辑才不会乱。

5.4 常用配置速查表

我把整个过程中用得最多的配置项整理成一个速查表，方便你直接复制参考。

实际配置时，记得把变量按需分组。飞书的配置和模型配置不要混在一个文件里，否则改一个字段就要动另一个模块，风险很大。

最后再分享一个小技巧

我在实际使用中发现，OpenClaws在Windows下的稳定性不如Linux，尤其长连接偶尔会断开，然后掉线后无法自动重连。后来我加了一个简单的定时重启脚本（Windows任务计划程序），每隔4小时重启一次服务，掉线问题基本消失。如果你也准备长跑，建议给服务加上看护进程，而不是裸奔运行。

另外一个经验是：先不要贪多。第一次配置就老老实实跑通“飞书+阿里云”或“飞书+腾讯云”其中一条链路，确认能发消息、能收到回复，再去搞第二条模型链路，然后是工具调用、多轮对话。我见过不少朋友一上来就想同时接满三个平台、五个模型，结果报错了都不知道是哪一段出了问题。

这篇主要覆盖了安装、飞书接入和双云模型接入的核心流程。如果你已经跑通了，可以在飞书里试一下让机器人帮你执行一些简单的脚本任务，比如定时发送提醒、解析日志文件。个人AI管家的玩法远不止聊天，这一套组合值得慢慢挖。