简介:本文提供OpenClaw从零部署到接入飞书、纸飞机的完整教程,覆盖模型选型、安装启动、通道配置、安全加固、成本控制与故障排查,并给出可复制的配置清单,帮助读者稳妥搭建24小时在线的私人AI助手。
先说结论:OpenClaw 适合想把飞书、纸飞机(Telegram)变成 AI 入口,又不想在多个聊天软件之间反复切换的人。它本质上是一个开源的 AI 助手网关,负责把大模型能力接入聊天工具,并支持多模型配置、消息路由、技能扩展和长期记忆。本文按照“从零部署—接入飞书—接入纸飞机—成本控制—故障排查”的顺序,给出更稳妥的分步接入方案。
适用人群:希望搭建私人 AI 助手、团队机器人、消息自动回复、代码问答或任务派发入口的用户。
前置条件:一台可 SSH 登录的 Linux 开发机、一个可用的 OpenAI 兼容大模型服务、飞书开放平台账号或 Telegram 账号。
预计耗时:首次部署约 1~3 小时,若熟悉流程可缩短到 30 分钟左右。
最终产出:一个可通过飞书群、飞书私聊、Telegram 私聊或群聊访问的 AI 助手网关,并具备基础安全配置、日志排查能力和成本控制策略。
OpenClaw 本身不提供大模型推理能力,你需要先准备一个兼容 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 可能在目录结构、配置字段和启动命令上略有差异,实际以官方仓库、release 说明和示例配置为准。
如果你的环境使用源码方式部署,可以拉取官方仓库并固定版本:
git clone https://github.com/your-openclaw/openclaw.gitcd openclawgit checkout v0.x.x
如果官方提供容器镜像,也可以直接拉取镜像运行:
docker pull your-registry/openclaw:0.x.x
建议在正式环境中固定版本号,不要长期使用 latest 标签,避免升级导致配置不兼容。
源码部署通常需要 Node.js 20 以上或 Python 3.11 以上,具体取决于项目实现。若不想处理 Node、Python 和系统依赖,优先使用 Docker 部署更省心。
以源码部署为例,常见步骤类似:
npm cinpm run build
如果是 Python 项目,则可能类似:
python -m venv .venvsource .venv/bin/activatepip install -r requirements.txt
无论哪种方式,都建议使用专用用户运行服务,不要用 root 直接跑长期进程。
复制配置模板:
cp config.example.yaml config.yaml
如果项目使用环境变量,也可以创建 .env 文件:
cp .env.example .envchmod 600 .env
一个典型的配置思路如下,字段名请以实际版本为准:
gateway:host: 127.0.0.1port: 18789token: REPLACE_WITH_RANDOM_TOKENmodels:default:base_url: https://api.example.com/v1api_key: sk-xxxxxxxxxxxxxxxxchannels:feishu:app_id: ""app_secret: ""telegram:bot_token: ""
其中 REPLACE_WITH_RANDOM_TOKEN 应替换为足够随机的字符串,可用于生成:
openssl rand -hex 32
源码启动示例:
npm run start
或者:
python -m openclaw gateway --config ./config.yaml
生产环境建议交给 systemd 或 Docker 管理。
如果使用 Docker Compose,可以写一个最小示例:
services:openclaw:image: your-registry/openclaw:0.x.xrestart: unless-stoppedports:- "127.0.0.1:18789:18789"env_file: .envvolumes:- ./data:/data
注意这里把宿主机端口绑定为 127.0.0.1:18789,意味着只能本机访问,不能直接从公网访问。
在你本地电脑执行:
ssh -L 18789:127.0.0.1:18789 root@开发机公网IP地址 -p 22
如果 SSH 端口被改过,请使用实际端口。转发成功后,在本地浏览器访问:
http://127.0.0.1:18789/?token=你的token
如果页面显示 Health Ok 或类似健康状态,说明网关已经正常运行。接下来就可以配置模型和聊天通道了。
模型配置的关键是 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 |
以文档为准 |
配置完成后,可以先测试模型服务是否可用:
curl https://api.example.com/v1/models \-H "Authorization: Bearer 你的API_KEY"
如果返回模型列表,说明地址和密钥基本正确。如果返回 401 或 403,通常是 API Key 无效或权限不足;如果返回 404,则很可能是 base_url 路径填错。
OpenClaw 支持多模型接入,不同模型在能力、速度、价格上差异明显。选型时不要只看“最强模型”,而要结合场景做分级路由。
| 场景 | 推荐模型类型 | 原因 |
|---|---|---|
| 日常问答、闲聊、摘要、翻译 | 轻量低价模型 | 延迟低、成本低,体验足够 |
| 代码生成、复杂推理、长文分析 | 能力更强的模型 | 对逻辑和上下文要求更高 |
| 批量任务、后台整理 | 轻量模型 + 缓存 | 降低单次调用成本 |
| 关键业务、高可靠场景 | 多模型备选 | 某个模型异常时可切换 |
一个实用的降本方法是分级路由:普通消息走轻量模型,复杂任务再切换到强模型。这样既能保证日常响应速度,又能避免所有请求都消耗高价模型。
如果你需要集中管理多个模型调用,可以在网关层配置模型路由、预算限制和调用日志。模型聚合平台可以作为可选方案之一,但不强制依赖。自建 OpenAI 兼容服务同样可以接入 OpenClaw。
成本控制建议包括:
飞书接入是本文重点。核心步骤包括创建应用、开启机器人能力、配置权限、订阅事件、填写凭证,以及处理回调安全。
进入飞书开放平台,创建企业自建应用,进入应用详情后开启机器人能力。随后获取 App ID 和 App Secret。这两个值不要写死在代码里,也不要提交到 Git,建议放入环境变量或密钥管理服务。
根据功能开通权限,不要一次性开启无关权限。通常需要关注:
权限越最小,后期越安全。
飞书机器人需要接收用户消息事件。配置方式通常有两种:
方式一:长连接方式
如果当前 OpenClaw 版本支持飞书长连接模式,优先使用长连接。这样可以减少公网回调暴露,也更容易在内网环境部署。
方式二:公网 HTTPS 回调
如果使用回调模式,需要提供一个公网可访问的 HTTPS 地址,例如:
https://ai.example.com/openclaw/feishu/callback
注意:飞书回调通常要求 HTTPS,并且需要完成回调地址验证。若你的服务器没有公网 HTTPS,需要配置反向代理、域名和证书。
为了安全,建议开启事件订阅加密策略,并配置 Encrypt Key 和 Verification Token。OpenClaw 侧需要同步填写这些配置。回调请求应校验签名、时间戳和来源,防止伪造请求。
在 OpenClaw 的飞书通道配置中填写:
feishu:app_id: 你的AppIDapp_secret: 你的AppSecretencrypt_key: 你的EncryptKeyverification_token: 你的VerificationToken
保存后重启网关,或在支持的版本中热加载配置。
接入后建议按以下清单检查:
纸飞机即 Telegram。接入相对简单,但也要重视 Bot Token 的保管。
在 Telegram 中搜索 @BotFather,发送:
/newbot
按提示设置机器人名称和用户名,完成后会获得一个 Bot Token。这个 Token 等同于机器人密码,不要公开。
在 OpenClaw 的 Telegram 通道中填写:
telegram:bot_token: 你的BotToken
保存后重启网关。
先与机器人发起私聊,发送:
/start
如果收到回复,说明私聊链路正常。若在群聊中不回复,可以检查隐私模式。默认情况下,Telegram Bot 在群聊中可能只响应命令或被 @ 的消息。如果你需要它读取更多群消息,需要调整隐私模式,但同时要评估群隐私和合规风险。
如果 Bot Token 泄露,应立即在 BotFather 中执行:
/revoke
然后重新生成 Token,并同步更新 OpenClaw 配置。
检查以下几点:
ss -lntp | grep 18789
如果端口没有监听,说明服务没有启动。可以查看日志:
journalctl -u openclaw
或者使用 Docker:
docker logs openclaw
如果是 SSH 转发失败,可以用详细模式排查:
ssh -vvv -L 18789:127.0.0.1:18789 root@开发机公网IP地址 -p 22
同时检查 token 是否正确,防火墙是否拦截。
先确认模型服务状态是否正常,再用 curl 测试:
curl https://api.example.com/v1/models \-H "Authorization: Bearer 你的API_KEY"
常见错误:
重点检查:
检查 Bot Token 是否正确、服务器是否能访问 Telegram API、机器人是否被拉黑、群聊隐私模式是否限制消息。若服务器位于网络受限环境,可能需要配置代理或选择可访问 Telegram 的网络出口。
正式使用前,建议逐项确认:
base_url 和 API Key 是否测试通过;按以上步骤完成后,你的 OpenClaw 就不再只是一个本地演示项目,而是一个可稳定运行在飞书、纸飞机中的私人 AI 助手。你可以先跑通一个模型和一个通道,再逐步接入更多模型、群聊、技能与自动化流程。