企业官网建设流程全解析

1. 先搞清楚这套组合到底在解决什么问题

先说个我自己的场景：本地攒了一台带显卡的工作站，装了 Ollama 跑开源模型，平时自己一个人在终端里聊得挺开心。但问题在于，这东西只有我能用。同事问我"能不能给咱们群也接一个"，家里人想用一下，我总不能教每个人去敲命令行。后来我把 OpenClaw 接上飞书机器人，又把模型后端指向本地 Ollama，整个事情就完全不一样了：群里 @ 一下机器人，它就能回答问题、执行任务，数据还全程不出内网。这篇是实战系列的第一篇，就把这条链路从零到一完整拆开。

OpenClaw 是个开源的个人 AI 助手框架。你可以把它理解成一个"中间调度层"：它负责连接各种消息平台，收到消息后交给大模型驱动的 Agent 主循环去处理，Agent 还能调用一堆工具——读写文件、执行 shell 命令、浏览网页、查日历——然后把最终结果发回对话。它不只是个聊天机器人，而是一个真正能"干活"的 AI 代理。飞书则承担了"遥控器"的角色：你平时上班就在飞书里，不用开任何额外界面，群聊就是和 AI 交互的入口。Ollama 在这里负责提供本地大模型推理能力，好处是私密、免费、无 API 限流焦虑，敏感数据完全留在自己的服务器上。

所以这套组合的完整链路是：

飞书用户（群聊里 @ 机器人） │ ▼ 飞书开放平台（事件订阅 / 长连接推送） │ ▼ OpenClaw Agent 主循环 ──► Ollama（本地大模型推理） │ │ │ 需要时调用文件/命令/网页等工具 └─ qwen2.5 或 llama3.1 等 ▼ 飞书消息 API（把回复发回群聊） │ ▼ 用户收到机器人的回答

这篇文章适合两类人：一是想在公司或团队里搭一个私有 AI 助手的开发者、运维，二是单纯想把本地大模型从"终端玩物"变成"全家可用工具"的折腾型玩家。你有 Docker 基础、懂一点 YAML 配置，就能完整跑通。

2. 开工前的物料清单：服务器、飞书权限和模型选型

2.1 服务器与运行环境的最低要求

别一上来就追新追大，先看你的硬件能撑住什么模型。OpenClaw 本身对资源要求不高，大头全在本地推理上。如果你的机器只有 CPU，那 7B 级别的量化模型勉强能跑，但一条消息可能要等几十秒，体验会很差。如果你有 NVIDIA 显卡，16GB 显存起步是黄金配置，能舒服地跑 14B 模型；24GB 以上可以考虑 32B；如果是 Mac 的统一内存架构，32GB 内存跑 14B 也没问题。

操作系统方面，Linux 服务器是最省心的选择，Docker 布署也最顺；Windows 上我建议用 WSL2 或者干脆全程容器化，避免各种路径和环境变量问题。另外提醒一句：飞书开放平台的 API 需要你的服务器能正常访问外网，如果你的机器在 NAT 后面、没有公网 IP，也没关系，因为咱们会用飞书的长连接模式，这个后面细说。

2.2 飞书侧关键的"隐形成本"：管理员审批

很多人以为接飞书机器人就是"建个应用那么简单"，结果卡在审批上。企业自建应用创建之后，所有权限变更都要走"创建版本 -> 提审 -> 管理员审批"这个流程。也就是说，你需要有一个飞书管理员帮你点通过，或者你自己就是管理员。如果你在一个大型组织里，建议提前跟管理员打好招呼，把"申请发布应用"这个事列入流程，否则配置到一半卡住很尴尬。

Subscriptions 还有一个容易忽略的点：你创建的应用是"企业自建应用"，而不是"商店应用"，所以审批一般走内部流程，不会太久，但一定要留出这个时间。我在第一次搭的时候，权限配置花了十分钟，审批等了大半天，所以把这事排在"物料清单"里提前准备。

2.3 本地模型选型：Agent 任务不能只看"能聊"

给 OpenClaw 选模型和普通聊天选模型是两回事。普通聊天模型答得差一点最多是"废话多"，但 Agent 场景里，模型必须稳定输出工具调用指令——它得能判断"这个问题需要调用什么工具、传什么参数"，并在工具返回结果后正确组织最终回复。工具调用能力不达标的模型，会表现得很怪：要么明明该查文件却硬编一个答案，要么反复调用同一个工具不结束。

基于我的实测，qwen2.5:14b是目前这个场景里性价比最高的选择：中文指令理解好、工具调用协议支持得完整、在 16GB 显存上速度也还凑合。如果你机器配置低，先用qwen2.5:7b把链路跑通，再换大模型。

3. 飞书侧完整配置：自建应用、事件订阅与长连接模式

3.1 创建企业自建应用并开启机器人能力

登录飞书开放平台开发者后台，选择"创建企业自建应用"，填好名称、图标和描述，这一步不用纠结，后面随时能改。创建完进入应用详情页，左侧导航找到"应用能力"，把"机器人"能力打开。机器人能力不打开，后面一切都是空谈。

最容易被忽略的是权限管理。飞书把权限设计得非常细碎，命名还经常调整。我的建议是：在"权限管理"页面里，把和消息、群组、机器人相关的权限逐条过一遍，按最小权限原则勾选。实际需要的大概是这几类：接收用户发给机器人的消息、以机器人身份发送消息、读取群基本信息。不同版本界面里选项名可能不一样，认准中文功能描述，别死背权限代码。这里我有个经验：宁可先多勾一两个，等跑通了再收紧，也不要一开始就卡在"只有收发没有发"这种权限空缺上。

3.2 事件订阅：强烈建议用长连接而不是公网 Webhook

这是整篇教程里最影响成败的一个选择。飞书事件订阅有两种接收方式：一种是你提供一个公网 HTTPS 回调地址，飞书把事件推送过去；另一种是"长连接"模式，由飞书的内置长连接机制主动向你的服务器建立 WebSocket 连接，事件通过这条连接直接推给你。

我的建议非常明确：用长连接。原因有三：第一，不需要公网域名和 HTTPS 证书，省掉一层运维；第二，服务器在 NAT 后面、没有固定公网 IP 也能用，家里部署特别合适；第三，OpenClaw 的飞书连接器本身就是为这种模式设计的，事件进来后直接在本地处理，延迟更低。

在事件订阅页面，你需要添加至少一个事件：im.message.receive_v1，中文名大概叫"接收消息"。这就是用户 @ 机器人时触发的事件。同时页面里会有Verification Token（校验Token）和Encrypt Key（加密密钥）两个字段。这里有个大坑：如果开放平台上开启了"加密"，回调的 payload 会是一坨密文，接收方必须先解密才能拿到真实事件内容。所以要么你别开加密（纯内网场景问题不大），要么把密钥正确配置到 OpenClaw 侧，两边一致才能跑通。

3.3 发布版本、把机器人拉进群、定位 chat_id

权限和事件配好之后，去"版本管理与发布"里创建一个版本，填好版本说明，提交审批。管理员审批通过后，你的应用才算真正生效。这一步很多人会漏：光在开发者后台改了配置，不重新发布版本，线上应用跑的还是老配置。每次改了权限或事件订阅，都要重新发版。

应用发布后，到飞书群里添加机器人：群设置 -> 群机器人 -> 添加机器人 -> 找到你刚创建的应用。添加成功后，你可以在群里 @ 它试一下，此时如果事件订阅通了，OpenClaw 那边就能看到事件日志。

还有一个关键数据：chat_id。它一般长这样：oc_xxxxxxxxxxxxxxxxxxxx。获取方式有两个：一是从事件推送的 payload 里拿，消息事件里一定带chat_id字段；二是调用开放平台的群信息接口。chat_id后面配置白名单和手动发送消息时都要用，建议先记住它。

4. Ollama 本地模型接入细节：OpenAI 兼容接口是枢纽

4.1 安装、常驻启动与"对外开放监听"

Ollama 的安装很简单：Linux 一条脚本命令，macOS 和 Windows 有现成安装包。装完先拉模型，比如ollama pull qwen2.5:14b，这一步会花一些时间，取决于网速和模型体积。这里提醒一下，模型文件大，提前规划磁盘空间，14B 量化模型大概要 9GB 左右。

然后是最容易踩的坑。默认情况下 Ollama 只监听127.0.0.1:11434，这意味着只有本机进程能访问。如果你的 OpenClaw 跑在 Docker 容器里，那容器里的进程是访问不到宿主机 Ollama 的。解决办法是让 Ollama 监听所有网卡：

OLLAMA_HOST=0.0.0.0:11434 ollama serve

注意，监听0.0.0.0意味着局域网里所有机器都能访问你 Ollama 的接口，如果服务器在内网环境里，别人也能白嫖你的推理能力。建议通过防火墙或 Docker 网络隔离来限制，别裸奔。

4.2 用 OpenAI 兼容层做连通性测试

Ollama 自带一个 OpenAI 兼容接口，地址是http://localhost:11434/v1。这意味着任何"配置了 OpenAI Base URL 就能用"的框架，都可以直接指向 Ollama。先手动验证一下：

# 查看当前有哪些模型 curl http://localhost:11434/v1/models

# 模拟一次对话请求 curl http://localhost:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5:14b", "messages": [{"role": "user", "content": "用一句话介绍你自己"}] }'

如果这两条命令都正常返回，说明 Ollama 的兼容层没问题，可以把它当作一个"本地版 OpenAI API"来对接。有一点要明确：Ollama 的 /v1 接口默认不需要鉴权，但 OpenClaw 这类框架通常要求填一个 API Key 字段，这里随便填一个非空字符串比如ollama就能通过。

4.3 function calling 能力实测：别等接完才发现模型不行

在正式接入 OpenClaw 之前，我强烈建议你先单独验证一下模型的工具调用能力。Ollama 的 /v1 接口也支持tools参数，你可以手工构造一次带工具定义的请求，看模型是正确返回tool_calls，还是无视工具直接给了一个文本回答。后者说明这个模型在"工具调用模式"下表现不行，建议换一个再继续。

实测下来，qwen2.5系列的界面比较规整，工具调用格式正确率高；deepseek-r1这种强推理模型，会把思维链内容混进输出，有时工具调用的格式会漂移，需要花时间调 prompt。Agent 场景里，我更看重"协议稳定性"而不是"推理天花板"，所以这一步值得在动手接 OpenClaw 之前花十分钟测清楚。

5. OpenClaw 安装、初始化与飞书连接器配置

5.1 安装与启动方式

OpenClaw 是开源项目，迭代速度很快。我写这篇时，安装方式以官方仓库 README 为准。大致流程是拉代码、装依赖、构建、初始化配置：

git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装依赖并构建，具体命令以仓库 README 为准 pnpm install && pnpm build # 初始化配置文件 openclaw init # 启动 Agent 主进程 openclaw start

如果你不想折腾本地环境，也可以直接把 OpenClaw 容器化运行。但不管哪种方式，都建议先跑一遍openclaw init，它会生成一个包含默认配置的文件，你要做的就是在它基础上改。我个人的习惯是：先在终端里跑通openclaw chat和本地模型对话，确认 Agent 基本功能没问题，再去连飞书。这样排查问题时能干净地切分"OpenClaw 自身问题"和"飞书接入问题"。

5.2 飞书连接器配置字段逐个解读

打开生成的配置文件，找到连接器相关段落，把飞书信息填进去。下面是我手头版本的配置示意，不同版本字段名可能有出入，但含义是稳定的，你照着这个思路去对应自己版本的配置格式就行：

connectors: feishu: appId: cli_xxxxxxxxxxxxxxxx appSecret: "你的应用密钥" eventMode: websocket replyMode: api allowedChatIds: - oc_xxxxxxxxxxxxxxxxxxxx

几个关键字段说清楚：

• appId和appSecret：在飞书开发者后台应用详情页的"凭证与基础信息"里拿。appSecret是敏感信息，别提交进 Git 仓库，建议用环境变量注入。
• eventMode: websocket：这就是前面说的长连接模式。设为这个值后，OpenClaw 会主动连上飞书的长连接服务，不需要你部署公网回调。
• replyMode: api：回复方式。用飞书消息 API 精确地把回复发到对应会话，而不是简单粗暴地往群里发。
• allowedChatIds：白名单。只允许列出的群或会话触发机器人。这个字段务必配置，否则任何能把你的应用拉进去的群都能驱使你的 Agent。

这里插一句：OpenClaw 这类框架配置字段更新很快，如果你查文档发现字段名不一样，不要慌，重点是找到"应用凭证、事件模式、回复模式、白名单"这四个语义对应的配置位。

5.3 对接 Ollama：LLM 参数配置与宿主机地址问题

模型这块的配置，在配置文件的 LLM 段落里。核心思路就是：把 Ollama 的 OpenAI 兼容接口伪装成一个 OpenAI 服务。配置示意如下：

llm: provider: openai baseUrl: http://host.docker.internal:11434/v1 apiKey: ollama model: qwen2.5:14b temperature: 0.3

如果你直接用环境变量，等价的是这三项：OPENAI_BASE_URL=http://host.docker.internal:11434/v1、OPENAI_MODEL=qwen2.5:14b、OPENAI_API_KEY=ollama。

注意host.docker.internal这个地址。当 OpenClaw 跑在 Docker 容器里、Ollama 跑在宿主机上时，容器内访问宿主机要用这个特殊域名。Linux 上 Docker 默认不一定支持host.docker.internal，需要在启动容器时加参数：--add-host=host.docker.internal:host-gateway。如果你直接让 OpenClaw 跑在宿主机上，那baseUrl直接写http://localhost:11434/v1就行。

temperature我建议调低，比如 0.3。原因后面故障章节会讲：Agent 场景里模型太"自由"会导致工具调用逻辑发散。

5.4 首次联调：在群里发出第一句对话

配置都填好之后，启动 OpenClaw 主进程，然后在飞书测试群里 @ 你的机器人，发一句"你好，介绍一下你自己"。这时候盯紧 OpenClaw 的日志，按三层去确认：

第一层，事件是否进来。日志里应该能看到飞书消息事件被接收的记录。没有的话，问题在飞书侧：应用没发布、权限没生效、长连接没建立。第二层，Agent 是否真的调了模型。日志里应该有 LLM 请求的痕迹，包括模型名和耗时。第三层，回复是否通过飞书 API 发出。如果事件进来了、模型也响应了，但群里没看到回复，重点检查appSecret是否配错、发送权限是否到位。

我第一次联调就出现了"日志显示回复发送成功，但群里没消息"的怪象，最后发现是应用版本没重新发布，线上应用的权限还是旧的。这类问题太容易出现了，所以我把联调顺序固定成"先查事件、再查模型、最后查发送"。

6. 实测中的典型故障与排查路径

6.1 排错方法论：给故障分层

接飞书机器人这件事，链路长，任何一层出问题表现都很相似：群里没反应。所以我的排查方法论永远是分层的：飞书事件层 -> OpenClaw Agent 层 -> Ollama 模型层 -> 飞书消息发送层。每一层都有对应的日志，先判断"卡在哪一层"，再深入那一层。

很多人在群里发现问题后，第一反应是去翻模型配置，结果折腾半天发现是事件订阅没通。按层排查能省大量时间。

6.2 高频故障对照速查表

6.3 我踩得最狠的三个坑

第一个坑是事件订阅的加密配置不一致。我当时在飞书开放平台把Encrypt Key开了，但 OpenClaw 侧没填对应的密钥，结果事件虽然推进来了，内容却是密文，Agent 完全读不懂。这个问题的排查路径是：看到日志中有事件记录但内容是乱码，立刻想到加密没有对齐。解决方案是两边配置统一，要么都开、要么都关。

第二个坑是工具调用死循环。某次模型反复调用同一个查询工具，一直不进入"生成最终回复"的环节，导致群里迟迟收不到结果。根因有两个方面：这个具体任务的工具参数设计得太模糊，模型不知道什么时候该停；以及temperature调得偏高，模型在工具调用叙事里"发散"了。后来我把工具描述写得更明确，并把temperature降到 0.3，问题基本消失。

第三个坑是长连接断线。飞书长连接模式偶尔会断，如果不自动重连，机器人就静默失联了。新版 OpenClaw 对断线重连做了处理，但如果你用的版本偏旧，建议写一个简单的守护脚本，定时检查连接状态，断了就重启进程。别问我怎么知道的，都是凌晨被同事"机器人怎么又死了"的消息炸醒换来的经验。

7. 上线前的安全收尾与这个系列后续还能玩什么

7.1 安全收尾清单：别让 Agent 裸奔

接入跑通之后，第一件事不是庆祝，而是收紧权限。这里我列一份自己的上线前检查单：第一，allowedChatIds白名单必须配，只允许你信任的群或会话与 Agent 交互；第二，appSecret绝对不要出现在代码仓库和日志里，用环境变量或密钥管理工具注入；第三，审视 OpenClaw 的工具权限，如果只是做问答和文本处理，就别给它裸 shell 权限，或者至少限制工作目录；第四，如果遇到任务积压，给 Agent 设置单轮任务超时，避免一个死循环任务占住推理资源。

还有一个很容易忽略的点：飞书的事件机制有重试。如果 Agent 处理时间太长，飞书侧会认为超时并重推事件，可能导致同一任务被重复执行。上线前应对这类重复做幂等保护，比如记录已处理消息的消息 ID，重复事件直接丢弃。

7.2 从"能聊"到"能用"：下一步扩展方向

链路跑通只是起点。飞书消息类型丰富，你可以让 Agent 解析富文本、卡片消息、图片和语音；可以给它加定时任务，每天早上自动汇总日报推送到群里；可以用 Playbook 技能脚本把高频工作流固化成可复用的技能，比如"查排班""生成周报""整理会议纪要"；还可以做多模型路由：简单闲聊走本地小模型，复杂任务切更大模型。

这个系列后续我会重点写两件事：一是 Playbook 技能脚本的落地经验，包括脚本怎么写、Agent 如何自主决定调用；二是多模型路由和飞书消息卡片的高级玩法。这篇先到这里，把基础链路和排错经验交代清楚，是你自己动手折腾的地基。

最后分享一点我的个人体会：整套系统跑通并不难，难的是让身边的人愿意用。我一开始图省事用 7B 模型，回复慢不说，还经常理解偏，同事试了两次就放弃了。后来换了 14B 模型并加了 GPU，回复速度上来，工具调用也稳定了，群里才真正有人每天都用。所以我的建议是：第一版先用小模型把链路跑通，验收之后再根据实际使用情况换大模型。别一上来就追求最强模型，稳定可用比什么都重要。