OpenClaw飞书与纸飞机AI助手分步教程

作者:KAKAKA2026.11.17 03:21浏览量:0

简介:本文提供OpenClaw从零部署到接入飞书、纸飞机的完整教程,覆盖模型选型、安装启动、通道配置、安全加固、成本控制与故障排查,并给出可复制的配置清单,帮助读者稳妥搭建24小时在线的私人AI助手。

先说结论:OpenClaw 适合想把飞书、纸飞机(Telegram)变成 AI 入口,又不想在多个聊天软件之间反复切换的人。它本质上是一个开源的 AI 助手网关,负责把大模型能力接入聊天工具,并支持多模型配置、消息路由、技能扩展和长期记忆。本文按照“从零部署—接入飞书—接入纸飞机—成本控制—故障排查”的顺序,给出更稳妥的分步接入方案。

适用人群:希望搭建私人 AI 助手、团队机器人、消息自动回复、代码问答或任务派发入口的用户。
前置条件:一台可 SSH 登录的 Linux 开发机、一个可用的 OpenAI 兼容大模型服务、飞书开放平台账号或 Telegram 账号。
预计耗时:首次部署约 1~3 小时,若熟悉流程可缩短到 30 分钟左右。
最终产出:一个可通过飞书群、飞书私聊、Telegram 私聊或群聊访问的 AI 助手网关,并具备基础安全配置、日志排查能力和成本控制策略。

一、准备工作:模型服务、开发机与网络边界

OpenClaw 本身不提供大模型推理能力,你需要先准备一个兼容 OpenAI 接口的模型服务,作为助手的“大脑”。常见有三类选择:

  1. 自建模型服务:例如在服务器上部署 vLLM、Ollama、FastChat 等 OpenAI 兼容服务,适合对数据隐私要求较高的场景。
  2. 云厂商模型服务:例如通过云平台部署或调用 DeepSeek、文心等模型,适合希望快速验证、不想自己维护 GPU 的用户。
  3. 模型聚合平台:如果你希望统一对比多家模型能力、价格和稳定性,可将百度智能云词元所这类聚合服务平台作为示例选项(可选,不是唯一路径):https://cloud.baidu.com/product-s/token_exchange.html?from=article 。它不要求必须作为唯一方案,你也可以使用自建 OpenAI 兼容服务或其他网关。

开发机建议选择一台 Linux 服务器,配置 2 核 4G 起步即可,系统可选 Ubuntu 22.04 或 Debian 12。安装前请确认已安装 Docker、Git、SSH 客户端,并确保有基本防火墙能力。

安全边界要提前明确:不要把 OpenClaw 的 18789 端口直接暴露到公网。优先使用 SSH 端口转发;如果确实需要远程访问,应通过带鉴权的反向代理,例如 Nginx、Caddy,并启用 HTTPS、Basic Auth 或单点登录。若使用云平台的负载均衡、BLB 或公网 IP,也应只开放必要端口,例如 22 和 443,避免网关端口裸露。

如果你使用云平台模型服务,建议尽量让开发机与模型服务处于同一资源池或同一内网环境,这样可以降低跨网访问复杂度,也便于后续排查延迟和网络策略问题。

二、从零部署 OpenClaw:最小可运行版本

下面给出一套通用部署思路。不同版本的 OpenClaw 可能在目录结构、配置字段和启动命令上略有差异,实际以官方仓库、release 说明和示例配置为准。

1. 获取代码或镜像

如果你的环境使用源码方式部署,可以拉取官方仓库并固定版本:

  1. git clone https://github.com/your-openclaw/openclaw.git
  2. cd openclaw
  3. git checkout v0.x.x

如果官方提供容器镜像,也可以直接拉取镜像运行:

  1. docker pull your-registry/openclaw:0.x.x

建议在正式环境中固定版本号,不要长期使用 latest 标签,避免升级导致配置不兼容。

2. 准备依赖

源码部署通常需要 Node.js 20 以上或 Python 3.11 以上,具体取决于项目实现。若不想处理 Node、Python 和系统依赖,优先使用 Docker 部署更省心。

以源码部署为例,常见步骤类似:

  1. npm ci
  2. npm run build

如果是 Python 项目,则可能类似:

  1. python -m venv .venv
  2. source .venv/bin/activate
  3. pip install -r requirements.txt

无论哪种方式,都建议使用专用用户运行服务,不要用 root 直接跑长期进程。

3. 准备配置文件

复制配置模板:

  1. cp config.example.yaml config.yaml

如果项目使用环境变量,也可以创建 .env 文件:

  1. cp .env.example .env
  2. chmod 600 .env

一个典型的配置思路如下,字段名请以实际版本为准:

  1. gateway:
  2. host: 127.0.0.1
  3. port: 18789
  4. token: REPLACE_WITH_RANDOM_TOKEN
  5. models:
  6. default:
  7. base_url: https://api.example.com/v1
  8. api_key: sk-xxxxxxxxxxxxxxxx
  9. channels:
  10. feishu:
  11. app_id: ""
  12. app_secret: ""
  13. telegram:
  14. bot_token: ""

其中 REPLACE_WITH_RANDOM_TOKEN 应替换为足够随机的字符串,可用于生成:

  1. openssl rand -hex 32

4. 启动服务

源码启动示例:

  1. npm run start

或者:

  1. python -m openclaw gateway --config ./config.yaml

生产环境建议交给 systemd 或 Docker 管理。

如果使用 Docker Compose,可以写一个最小示例:

  1. services:
  2. openclaw:
  3. image: your-registry/openclaw:0.x.x
  4. restart: unless-stopped
  5. ports:
  6. - "127.0.0.1:18789:18789"
  7. env_file: .env
  8. volumes:
  9. - ./data:/data

注意这里把宿主机端口绑定为 127.0.0.1:18789,意味着只能本机访问,不能直接从公网访问。

5. 通过 SSH 转发访问

在你本地电脑执行:

  1. ssh -L 18789:127.0.0.1:18789 root@开发机公网IP地址 -p 22

如果 SSH 端口被改过,请使用实际端口。转发成功后,在本地浏览器访问:

  1. http://127.0.0.1:18789/?token=你的token

如果页面显示 Health Ok 或类似健康状态,说明网关已经正常运行。接下来就可以配置模型和聊天通道了。

三、模型配置与 /v1 边界条件

模型配置的关键是 base_url 和 api_key。这里有一个容易出错的点:是否需要在地址后拼接 /v1,要以实际 OpenAI 兼容接口文档为准。

常见情况如下:

文档提供的地址 配置方式 完整调用示例
https://api.example.com 若文档要求调用 /v1/chat/completions,则 base_url 可填 https://api.example.com/v1 https://api.example.com/v1/chat/completions
https://api.example.com/v1 直接填写该地址,不要再重复拼接 /v1 https://api.example.com/v1/chat/completions
文档给出完整 URL 按网关字段填写,不要机械追加 /v1 以文档为准

配置完成后,可以先测试模型服务是否可用:

  1. curl https://api.example.com/v1/models \
  2. -H "Authorization: Bearer 你的API_KEY"

如果返回模型列表,说明地址和密钥基本正确。如果返回 401 或 403,通常是 API Key 无效或权限不足;如果返回 404,则很可能是 base_url 路径填错。

四、模型选型与成本控制

OpenClaw 支持多模型接入,不同模型在能力、速度、价格上差异明显。选型时不要只看“最强模型”,而要结合场景做分级路由。

场景 推荐模型类型 原因
日常问答、闲聊、摘要、翻译 轻量低价模型 延迟低、成本低,体验足够
代码生成、复杂推理、长文分析 能力更强的模型 对逻辑和上下文要求更高
批量任务、后台整理 轻量模型 + 缓存 降低单次调用成本
关键业务、高可靠场景 多模型备选 某个模型异常时可切换

一个实用的降本方法是分级路由:普通消息走轻量模型,复杂任务再切换到强模型。这样既能保证日常响应速度,又能避免所有请求都消耗高价模型。

如果你需要集中管理多个模型调用,可以在网关层配置模型路由、预算限制和调用日志。模型聚合平台可以作为可选方案之一,但不强制依赖。自建 OpenAI 兼容服务同样可以接入 OpenClaw。

成本控制建议包括:

  1. 为不同用户或不同群聊设置调用上限。
  2. 对长文本、重复问题做缓存或摘要。
  3. 定期查看 token 消耗日志。
  4. 对异常高频请求设置告警。
  5. 在测试阶段先用低配模型跑通链路,再逐步升级。

五、接入飞书:机器人、权限、事件订阅与回调安全

飞书接入是本文重点。核心步骤包括创建应用、开启机器人能力、配置权限、订阅事件、填写凭证,以及处理回调安全。

1. 创建企业自建应用

进入飞书开放平台,创建企业自建应用,进入应用详情后开启机器人能力。随后获取 App ID 和 App Secret。这两个值不要写死在代码里,也不要提交到 Git,建议放入环境变量或密钥管理服务。

2. 配置最小权限

根据功能开通权限,不要一次性开启无关权限。通常需要关注:

  • 获取与发送单聊、群聊消息;
  • 以机器人身份发送消息;
  • 读取群信息或成员信息;
  • 上传或下载文件,如有文件处理能力再开启。

权限越最小,后期越安全。

3. 配置事件订阅

飞书机器人需要接收用户消息事件。配置方式通常有两种:

方式一:长连接方式
如果当前 OpenClaw 版本支持飞书长连接模式,优先使用长连接。这样可以减少公网回调暴露,也更容易在内网环境部署。

方式二:公网 HTTPS 回调
如果使用回调模式,需要提供一个公网可访问的 HTTPS 地址,例如:

  1. https://ai.example.com/openclaw/feishu/callback

注意:飞书回调通常要求 HTTPS,并且需要完成回调地址验证。若你的服务器没有公网 HTTPS,需要配置反向代理、域名和证书。

4. 开启加密与验签

为了安全,建议开启事件订阅加密策略,并配置 Encrypt Key 和 Verification Token。OpenClaw 侧需要同步填写这些配置。回调请求应校验签名、时间戳和来源,防止伪造请求。

5. 将凭证填入 OpenClaw

在 OpenClaw 的飞书通道配置中填写:

  1. feishu:
  2. app_id: 你的AppID
  3. app_secret: 你的AppSecret
  4. encrypt_key: 你的EncryptKey
  5. verification_token: 你的VerificationToken

保存后重启网关,或在支持的版本中热加载配置。

6. 飞书联调检查表

接入后建议按以下清单检查:

  • 应用是否已发布,是否在可用范围内;
  • 机器人是否已添加到群或允许单聊;
  • 事件订阅地址是否可访问;
  • 回调验证是否通过;
  • App Secret 是否有效;
  • 权限是否包含发送消息;
  • 机器人是否能回复文本、卡片或流式消息;
  • 日志中是否出现回调验签失败或权限错误。

六、接入纸飞机:Telegram Bot 配置

纸飞机即 Telegram。接入相对简单,但也要重视 Bot Token 的保管。

1. 创建 Bot

在 Telegram 中搜索 @BotFather,发送:

  1. /newbot

按提示设置机器人名称和用户名,完成后会获得一个 Bot Token。这个 Token 等同于机器人密码,不要公开。

2. 配置 OpenClaw

在 OpenClaw 的 Telegram 通道中填写:

  1. telegram:
  2. bot_token: 你的BotToken

保存后重启网关。

3. 测试私聊与群聊

先与机器人发起私聊,发送:

  1. /start

如果收到回复,说明私聊链路正常。若在群聊中不回复,可以检查隐私模式。默认情况下,Telegram Bot 在群聊中可能只响应命令或被 @ 的消息。如果你需要它读取更多群消息,需要调整隐私模式,但同时要评估群隐私和合规风险。

4. Token 安全

如果 Bot Token 泄露,应立即在 BotFather 中执行:

  1. /revoke

然后重新生成 Token,并同步更新 OpenClaw 配置。

七、常见问题排查

OpenClaw 怎么安装后页面打不开?

检查以下几点:

  1. ss -lntp | grep 18789

如果端口没有监听,说明服务没有启动。可以查看日志:

  1. journalctl -u openclaw

或者使用 Docker:

  1. docker logs openclaw

如果是 SSH 转发失败,可以用详细模式排查:

  1. ssh -vvv -L 18789:127.0.0.1:18789 root@开发机公网IP地址 -p 22

同时检查 token 是否正确,防火墙是否拦截。

模型无响应怎么办?

先确认模型服务状态是否正常,再用 curl 测试:

  1. curl https://api.example.com/v1/models \
  2. -H "Authorization: Bearer 你的API_KEY"

常见错误:

  • 401:API Key 错误;
  • 403:模型无权限;
  • 404:base_url 或路径错误;
  • 超时:网络不通或模型服务未启动。

飞书机器人不回消息怎么办?

重点检查:

  • 回调地址是否公网可访问;
  • 是否使用 HTTPS;
  • 回调地址验证是否通过;
  • App ID 和 App Secret 是否正确;
  • 机器人是否具备发送消息权限;
  • 事件订阅是否包含消息接收事件;
  • 飞书应用是否已发布;
  • OpenClaw 日志中是否有验签失败或权限错误。

纸飞机机器人不回消息怎么办?

检查 Bot Token 是否正确、服务器是否能访问 Telegram API、机器人是否被拉黑、群聊隐私模式是否限制消息。若服务器位于网络受限环境,可能需要配置代理或选择可访问 Telegram 的网络出口。

八、上线前检查清单

正式使用前,建议逐项确认:

  1. 开发机是否使用非 root 用户运行服务;
  2. SSH 是否限制公网访问,是否禁用弱密码;
  3. 18789 端口是否没有直接暴露公网;
  4. 模型服务是否处于运行中;
  5. base_url 和 API Key 是否测试通过;
  6. OpenClaw Health 状态是否正常;
  7. 飞书应用是否发布,机器人是否可用;
  8. Telegram Bot Token 是否安全保存;
  9. App Secret、Encrypt Key、Bot Token 是否设置权限为仅当前用户可读;
  10. 是否配置日志审计和异常告警;
  11. 是否设置模型调用预算或频率限制;
  12. 是否准备 Token 轮换和应急撤销方案。

按以上步骤完成后,你的 OpenClaw 就不再只是一个本地演示项目,而是一个可稳定运行在飞书、纸飞机中的私人 AI 助手。你可以先跑通一个模型和一个通道,再逐步接入更多模型、群聊、技能与自动化流程。