从零部署OpenClaw：构建跨平台AI助手网关的完整实践指南

1. 项目概述：为什么需要 OpenClaw？

如果你和我一样，每天的工作流被 Telegram 和飞书这两个应用切得七零八落，一边是团队在飞书里讨论需求、沉淀文档，另一边是客户、合作伙伴在 Telegram 上发来各种文件和信息，那你肯定也幻想过：要是有个 AI 助手能同时在这两个地方待命就好了。我不用在应用间反复横跳，无论是飞书群里的技术问题，还是 Telegram 私聊里的文件摘要，都能让同一个“大脑”来处理。OpenClaw 的出现，正好击中了这个痛点。

简单来说，OpenClaw 是一个开源的 AI 助手网关。它的核心价值在于“连接”——它本身不生产 AI 模型，而是模型的搬运工和调度员。你可以把它想象成一个智能的“接线总机”，一头连着 OpenAI、Anthropic、DeepSeek 乃至你本地部署的 Ollama 模型，另一头则连着 Telegram、飞书、Discord、Slack 等各类通讯平台。通过 OpenClaw，你可以在这些平台上创建一个统一的 AI 助手分身，用同一个身份、同一套知识（如果你接入了知识库）去响应不同场景的需求。

我最初被它吸引，就是因为厌倦了在每个平台单独配置机器人的繁琐。OpenClaw 提供了一种“一次配置，多处部署”的优雅方案。更关键的是，它的配置过程虽然涉及一些开发概念，但官方文档和社区已经做了相当多的简化，只要跟着步骤走，即使不是资深 DevOps，也能把它跑起来。接下来，我就把自己从零开始，在 Ubuntu 服务器上部署 OpenClaw，并成功接入 Telegram 和飞书的完整过程，以及踩过的坑、总结的技巧，毫无保留地分享给你。

2. 环境准备与核心依赖安装

部署 OpenClaw 就像搭积木，地基必须打牢。它基于 Node.js 生态，同时重度依赖数据库（MySQL/PostgreSQL）和缓存（Redis）来管理状态、会话和知识库。因此，我们的准备工作需要分三步走：搭建运行环境、部署支撑服务、获取必要的密钥。

2.1 服务器与运行环境配置

首先是一台服务器。我选择的是 Ubuntu 22.04 LTS，系统纯净且社区支持好。你完全可以在自己的云服务器、本地虚拟机，甚至配置好端口转发的家用 NAS 上操作。核心是保证网络可达，后续 Telegram 和飞书的回调才能成功。

1. 系统更新与基础工具安装登录服务器后，第一件事是更新软件源并安装一些必备工具，这能避免很多因依赖缺失导致的奇怪问题。

sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git vim net-tools

2. Node.js 环境安装（使用 NVM）OpenClaw 对 Node.js 版本有要求（建议 v18+），为了灵活管理版本，我强烈推荐使用 NVM（Node Version Manager）来安装，而不是直接用 apt 安装。

# 下载并安装 NVM curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 安装完成后，重新加载 shell 配置，或新开一个终端 source ~/.bashrc # 安装 Node.js 18（LTS 版本，稳定兼容） nvm install 18 nvm use 18 # 验证安装 node -v # 应输出 v18.x.x npm -v

注意：使用 NVM 安装的 Node.js 和 npm 位于用户目录下，避免了全局权限问题。确保在后续所有步骤中，你都位于安装了 Node 18 的终端会话中。

3. 安装 PM2 进程管理工具OpenClaw 需要以服务形式常驻运行。PM2 是一个优秀的 Node.js 进程管理器，能实现开机自启、日志管理、监控等功能。

npm install -g pm2

2.2 支撑服务部署：MySQL 与 Redis

OpenClaw 使用 MySQL（或 PostgreSQL）作为主数据库存储用户、会话、知识库等元数据，用 Redis 作为缓存和消息队列，提升响应速度。这里我们使用 Docker 来快速部署，这比手动安装配置要干净利落得多。

1. 安装 Docker 与 Docker Compose如果你的系统还没有 Docker，可以快速安装：

# 安装 Docker curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh # 将当前用户加入 docker 组，避免每次都用 sudo sudo usermod -aG docker $USER # 需要退出重新登录生效，或者执行 newgrp docker newgrp docker # 安装 Docker Compose Plugin (Docker 新版本已集成) sudo apt install -y docker-compose-plugin

2. 编写 Docker Compose 配置文件在用户目录下创建一个openclaw-infra文件夹，并编写docker-compose.yml文件。

mkdir ~/openclaw-infra && cd ~/openclaw-infra vim docker-compose.yml

将以下内容粘贴进去。这里我做了几点关键配置：为 MySQL 设置了 root 密码和专用数据库，为 Redis 设置了密码，并将数据卷挂载到本地，防止容器重启数据丢失。

version: '3.8' services: mysql: image: mysql:8.0 container_name: openclaw-mysql restart: always environment: MYSQL_ROOT_PASSWORD: YourStrongRootPassword123! # 请务必修改！ MYSQL_DATABASE: openclaw MYSQL_USER: openclaw_user MYSQL_PASSWORD: YourOpenClawDBPassword123! # 请务必修改！ ports: - "3306:3306" volumes: - ./mysql_data:/var/lib/mysql command: --default-authentication-plugin=mysql_native_password healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p$$MYSQL_ROOT_PASSWORD"] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: openclaw-redis restart: always command: redis-server --requirepass YourRedisPassword123! # 请务必修改！ ports: - "6379:6379" volumes: - ./redis_data:/data healthcheck: test: ["CMD", "redis-cli", "-a", "YourRedisPassword123!", "ping"] # 密码需与上面一致 interval: 10s timeout: 5s retries: 5

3. 启动支撑服务并验证

# 在 docker-compose.yml 所在目录执行 docker compose up -d # 查看服务状态 docker compose ps

你应该看到mysql和redis两个服务的状态都是running (healthy)。可以通过以下命令简单测试：

# 测试 MySQL 连接（用上面设置的密码） docker exec openclaw-mysql mysql -uopenclaw_user -pYourOpenClawDBPassword123! -e "SHOW DATABASES;" # 应该能看到包含 `openclaw` 数据库的列表 # 测试 Redis 连接 docker exec openclaw-redis redis-cli -a YourRedisPassword123! ping # 应返回 `PONG`

实操心得：务必记录下你设置的 MySQL 和 Redis 的密码、端口以及数据库名，下一步配置 OpenClaw 时会用到。我习惯用一个本地的infra-notes.txt文件记录这些信息。

2.3 获取三方平台密钥与配置

OpenClaw 需要与 AI 模型平台和通讯平台通信，因此我们需要提前准备好几把“钥匙”。

1. AI 模型 API 密钥这是 OpenClaw 的“大脑”。你可以选择其中之一或组合使用：

• OpenAI: 访问 platform.openai.com/api-keys 创建 API Key。记下以sk-开头的密钥。
• DeepSeek: 访问 platform.deepseek.com/api-keys 创建 API Key。
• Ollama (本地模型): 如果你在本地或同一内网部署了 Ollama，则不需要密钥，但需要知道服务地址（如http://localhost:11434）。

2. Telegram Bot Token这是让 OpenClaw 化身 Telegram 机器人的关键。

1. 在 Telegram 中搜索@BotFather并开始对话。
2. 发送/newbot命令，按提示设置机器人名称和用户名（必须以bot结尾）。
3. 创建成功后，BotFather会返回一个HTTP API令牌，格式如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。妥善保存。

3. 飞书应用凭证这是接入飞书最复杂的一步，需要创建一个“企业自建应用”。

1. 登录 飞书开放平台 。
2. 点击“创建企业自建应用”，填写应用名称（如“我的AI助手”）、描述等。
3. 进入应用后，在“凭证与基础信息”页面，找到App ID和App Secret。点击App Secret旁的“重置”即可获取。请务必立即复制保存App Secret，关闭弹窗后将无法再次查看。
4. 在“事件订阅”页面，你需要设置“请求地址 URL”。这个地址是你的 OpenClaw 服务对公网暴露的地址，格式为https://你的域名或IP:端口/feishu/events。在 OpenClaw 部署完成并配置好反向代理（如 Nginx）之前，这里可以先留空，部署完成后再来补全。这是很多人卡住的地方。
5. 在“权限管理”页面，为应用添加以下权限（根据你的需求选择）：
   • 必选：contact:user.id:readonly（获取用户 ID）、im:message（发送与接收单聊、群组@消息）。
   • 可选：如果希望机器人能读取频道消息，添加im:message.group_at_msg:readonly；如果需要访问知识库文件，添加drive:drive:readonly等。

3. OpenClaw 服务部署与核心配置

环境就绪，钥匙在手，现在可以开始部署 OpenClaw 本体了。官方提供了多种部署方式，考虑到稳定性和易管理性，我选择直接从源码构建并部署。

3.1 获取源码与安装依赖

# 1. 克隆仓库（建议选择稳定版本，如 main 分支的最新提交） cd ~ git clone https://github.com/openclaw-ai/openclaw.git cd openclaw # 2. 安装项目依赖（这个过程可能需要几分钟） npm install # 3. 复制环境变量配置文件模板 cp .env.example .env

.env文件是 OpenClaw 所有配置的核心，接下来我们要仔细修改它。

3.2 详解环境变量配置 (.env)

用编辑器打开.env文件，我们需要配置数据库连接、AI模型、平台插件等。以下是我根据实际部署整理的关键配置段与注释：

# ==================== 基础配置 ==================== NODE_ENV=production # 生产环境 PORT=3000 # OpenClaw 服务监听的端口 # ==================== 数据库配置 ==================== # 使用我们刚部署的 MySQL DB_CLIENT=mysql2 DB_HOST=localhost # 如果数据库不在本机，改为对应IP DB_PORT=3306 DB_USER=openclaw_user # 前面 docker-compose 里创建的用户 DB_PASSWORD=YourOpenClawDBPassword123! # 替换为你的密码 DB_DATABASE=openclaw DB_POOL_MIN=2 DB_POOL_MAX=20 # ==================== Redis 缓存配置 ==================== REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD=YourRedisPassword123! # 替换为你的密码 REDIS_DB=0 # ==================== AI 模型提供商配置 ==================== # 你可以配置多个，OpenClaw 支持按策略调用 # 使用 OpenAI OPENAI_API_KEY=sk-your-openai-api-key-here OPENAI_BASE_URL=https://api.openai.com/v1 # 默认，如果用第三方代理可改 # 使用 DeepSeek DEEPSEEK_API_KEY=your-deepseek-api-key-here # 使用本地 Ollama OLLAMA_BASE_URL=http://localhost:11434 # Ollama 服务地址 # 指定默认使用的模型 DEFAULT_MODEL=gpt-4o-mini # 可以是 gpt-4o, deepseek-chat, llama3.2 等 # ==================== 平台插件配置 ==================== # 启用 Telegram 插件 TELEGRAM_ENABLED=true TELEGRAM_BOT_TOKEN=1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ # 替换为你的 Bot Token TELEGRAM_WEBHOOK_DOMAIN=https://your-domain.com # Telegram 回调地址，需 HTTPS # 启用飞书插件 FEISHU_ENABLED=true FEISHU_APP_ID=cli_xxxxxx # 替换为你的 App ID FEISHU_APP_SECRET=your_app_secret_here # 替换为你的 App Secret FEISHU_ENCRYPT_KEY= # 如果飞书应用配置了“加密”，需填写此处 FEISHU_VERIFICATION_TOKEN= # 同上，在事件订阅页面可找到 # 飞书事件回调路径，与你在飞书开放平台设置的“请求地址 URL”后缀一致 FEISHU_EVENT_CALLBACK_PATH=/feishu/events # ==================== 其他可选配置 ==================== # 日志级别 LOG_LEVEL=info # 会话记忆长度 MAX_HISTORY_MESSAGES=20

关键注意事项：

1. TELEGRAM_WEBHOOK_DOMAIN和飞书的回调地址，必须是一个支持 HTTPS 的公网域名或 IP。本地开发可以用ngrok或localhost.run等工具生成临时地址，生产环境务必配置你自己的域名和 SSL 证书。
2. 飞书的FEISHU_VERIFICATION_TOKEN和FEISHU_ENCRYPT_KEY仅在飞书应用后台“事件订阅”中启用了“加密”或“校验 Token”时才需要填写。初次配置建议先关闭这些选项以简化流程。
3. 所有密码、Token、Secret 务必妥善保管，.env文件绝不能提交到公开的代码仓库。

3.3 数据库初始化与启动服务

配置好.env后，需要让 OpenClaw 创建数据库表结构。

# 运行数据库迁移（Migration） npx knex migrate:latest

如果看到类似Batch 1 run: 10 migrations的提示，说明数据库表创建成功。你可以连接 MySQL 查看openclaw数据库，应该能看到一系列以_openclaw_为前缀的表。

现在，我们可以用 PM2 来启动服务了，这能保证服务在后台稳定运行，并在服务器重启后自动拉起。

# 使用 PM2 启动 OpenClaw，并命名为 openclaw-server pm2 start npm --name "openclaw-server" -- run start # 设置 PM2 开机自启 pm2 startup pm2 save # 查看服务状态和日志 pm2 status openclaw-server pm2 logs openclaw-server --lines 50

如果一切顺利，日志中不应有ERROR级别的报错，并且会输出服务已启动在http://localhost:3000的信息。此时，OpenClaw 的核心服务已经在你的服务器上跑起来了。

4. 反向代理与 HTTPS 配置（关键一步）

到目前为止，OpenClaw 还只能通过服务器的3000端口在内网访问。但 Telegram 和飞书的机器人回调（Webhook）强制要求 HTTPS。因此，我们必须通过一个 Web 服务器（如 Nginx）做反向代理，为 OpenClaw 配置一个安全的公网访问入口。

4.1 安装并配置 Nginx

# 安装 Nginx sudo apt install -y nginx

假设你的公网 IP 是123.123.123.123，域名是ai.yourcompany.com。你需要配置 Nginx 将对该域名的请求转发到本地的3000端口。

创建一个新的 Nginx 配置文件：

sudo vim /etc/nginx/sites-available/openclaw

写入以下配置（请替换server_name和ssl_certificate路径）：

server { listen 80; server_name ai.yourcompany.com; # 你的域名 # 将 HTTP 请求重定向到 HTTPS，强制使用安全连接 return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name ai.yourcompany.com; # 你的域名 # SSL 证书路径（如何获取证书见下文） ssl_certificate /etc/letsencrypt/live/ai.yourcompany.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/ai.yourcompany.com/privkey.pem; # SSL 优化配置（提升安全性） ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512; ssl_prefer_server_ciphers off; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; # 反向代理到 OpenClaw location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # 以下两行对 WebSocket 支持很重要（如果未来插件需要） proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_read_timeout 86400s; proxy_send_timeout 86400s; } # 可选：静态文件缓存（如果 OpenClaw 有前端资源） # location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { # expires 1y; # add_header Cache-Control "public, immutable"; # } }

4.2 获取 SSL 证书（使用 Certbot）

免费的 SSL 证书可以通过 Let‘s Encrypt 获取，Certbot 工具让这个过程自动化。

# 安装 Certbot 和 Nginx 插件 sudo apt install -y certbot python3-certbot-nginx # 运行 Certbot，自动修改 Nginx 配置并获取证书 sudo certbot --nginx -d ai.yourcompany.com

按照提示输入邮箱、同意协议即可。Certbot 会自动验证域名所有权（需要你的域名 DNS 已解析到该服务器 IP），并修改上面的 Nginx 配置文件，添加证书路径。

4.3 启用配置并测试

# 创建软链接，启用站点配置 sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ # 测试 Nginx 配置语法 sudo nginx -t # 如果显示 “syntax is ok”，则重载 Nginx sudo systemctl reload nginx

现在，你应该可以通过https://ai.yourcompany.com访问 OpenClaw 的服务了（可能是一个简单的欢迎页面或 API 文档）。同时，http的请求会被自动跳转到https。

5. 平台接入与机器人配置

服务端和网络通道都已打通，现在是最后一步：让 Telegram 和飞书知道我们的 AI 助手在哪里，并建立连接。

5.1 配置 Telegram Bot Webhook

Telegram 机器人需要通过 Webhook 接收消息。OpenClaw 提供了 CLI 工具来设置，但需要先确保服务已运行且 HTTPS 可访问。

# 进入 OpenClaw 项目目录 cd ~/openclaw # 使用 OpenClaw CLI 设置 Webhook npx openclaw-cli telegram set-webhook --url https://ai.yourcompany.com/telegram/webhook

这个命令会向 Telegram 服务器注册你的 Webhook 地址。如果成功，你会看到类似Webhook was set successfully的提示。

验证与测试：

1. 在 Telegram 中找到你创建的 Bot，点击“Start”或发送/start消息。
2. 查看 OpenClaw 的实时日志：pm2 logs openclaw-server。你应该能看到类似[Telegram] Received message from user ...的日志条目。
3. 尝试向 Bot 发送一条消息，比如“你好”，你应该能收到 AI 助手的回复。

踩坑记录：如果设置 Webhook 失败，最常见的原因是：

• URL 无法访问：确保你的域名ai.yourcompany.com能从公网解析并访问到 Nginx，且 Nginx 正确代理到了localhost:3000。可以用curl https://ai.yourcompany.com测试。
• SSL 证书问题：Telegram 对 SSL 证书要求严格，自签名证书或证书链不完整会导致失败。务必使用 Let‘s Encrypt 等权威机构颁发的证书。
• 路径错误：OpenClaw Telegram 插件的 Webhook 路径固定为/telegram/webhook，确保 Nginx 配置的location /能正确转发到这个路径。

5.2 配置飞书事件订阅与权限

这是整个流程中最容易出错的一环，需要耐心在飞书开放平台后台操作。

1. 补全事件订阅 URL：回到飞书开放平台你的应用管理后台，进入“事件订阅”页面。

   • 在“请求地址 URL”中填入：https://ai.yourcompany.com/feishu/events（与.env中的FEISHU_EVENT_CALLBACK_PATH拼接而成）。
   • 暂时不要点击“保存”！

2. 获取 Verification Token（可选但推荐）：在“事件订阅”页面，你会看到“Encrypt Key”和“Verification Token”。点击“重置 Verification Token”并复制它。然后，将这个 Token 填入你的.env文件中的FEISHU_VERIFICATION_TOKEN变量。修改后，必须重启 OpenClaw 服务使配置生效。

   pm2 restart openclaw-server

3. 保存并验证 URL：现在，点击飞书后台“请求地址 URL”下方的“保存”按钮。飞书会立即向你的https://ai.yourcompany.com/feishu/events发送一个带有challenge参数的 GET 请求进行验证。

   • 如果验证成功：页面会提示“请求地址验证成功”，并且输入框下方会显示“保存成功”。
   • 如果验证失败：请按以下步骤排查： a.检查 OpenClaw 日志：pm2 logs openclaw-server，看是否收到验证请求，以及是否有错误信息。 b.检查 Nginx 日志：sudo tail -f /var/log/nginx/access.log和error.log，看请求是否转发到了3000端口。 c.检查.env配置：确保FEISHU_APP_ID,FEISHU_APP_SECRET,FEISHU_VERIFICATION_TOKEN完全正确，且已重启服务。 d.检查防火墙/安全组：确保服务器的443端口对公网开放。

4. 订阅所需事件：URL 验证通过后，在“事件订阅”页面下方，找到“订阅事件”区域。根据你的需要，至少需要订阅：

   • im.message.receive_v1（接收用户发送的消息） 点击“添加事件”，搜索并勾选上述事件，然后再次点击页面底部的“保存”。

5. 发布版本并启用：在飞书开放平台左侧菜单，进入“版本管理与发布”。

   • 点击“创建版本”，填写版本号（如1.0.0）和描述。
   • 至关重要的一步：在“可用性”范围，选择“企业自用”或根据情况选择“全员”。如果选择“企业自用”，则需要添加允许使用该应用的企业（即你的飞书企业）。
   • 点击“保存”，然后“申请发布”。通常“企业自用”的应用会很快自动审核通过。

6. 将应用添加到聊天群或启用为个人助手：

   • 添加到群聊：在飞书群聊的设置中，找到“群机器人”，点击“添加机器人”，选择你刚刚发布的应用。
   • 作为个人助手：在飞书搜索框中搜索你的应用名称，点击打开，即可开始私聊。

现在，无论是在飞书群聊中 @ 你的机器人，还是在私聊窗口，你发送的消息都应该能触发 OpenClaw 的 AI 助手进行回复了。

6. 进阶配置与使用技巧

基础功能跑通后，你可以根据需求进一步调优和扩展 OpenClaw。

6.1 多模型切换与路由策略

OpenClaw 支持配置多个 AI 模型提供商。你可以在.env中同时配置OPENAI_API_KEY和DEEPSEEK_API_KEY。那么，如何决定使用哪个模型呢？

1. 默认模型：通过DEFAULT_MODEL环境变量设置，如gpt-4o-mini。
2. 模型路由：OpenClaw 支持更智能的路由策略。你可以在管理界面（如果部署了前端）或通过 API，为不同的用户、群组甚至对话类型指定不同的模型。例如，让技术讨论群使用gpt-4，而日常闲聊群使用成本更低的deepseek-chat。
3. 本地模型优先：如果你同时配置了OLLAMA_BASE_URL，可以在路由策略中设置，让内网请求优先使用本地模型，以保护隐私和节省成本。

6.2 知识库与长期记忆

OpenClaw 的一个强大特性是支持知识库（RAG）。你可以将公司文档、产品手册、常见问题等文件上传，AI 助手在回答问题时，会优先从这些知识库中检索相关信息，生成更精准、更符合上下文的回答。

配置知识库通常涉及以下步骤：

1. 启用向量数据库：除了 MySQL 和 Redis，还需要一个向量数据库（如 Qdrant、Weaviate 或 PGVector）来存储文档的嵌入向量。需要在.env中配置对应的连接信息。
2. 文档处理：通过 OpenClaw 的管理接口或 API 上传文档（支持 txt, pdf, docx, md 等格式）。系统会自动进行文本分割、向量化并存入向量库。
3. 对话中应用：当用户提问时，OpenClaw 会先从向量库中检索相关文档片段，然后将这些片段作为上下文与问题一起发送给 AI 模型，从而得到基于知识库的答案。

6.3 监控、日志与问题排查

一个稳定的服务离不开监控。

1. PM2 监控：pm2 monit命令可以打开一个仪表盘，实时查看 CPU、内存占用。
2. 日志管理：OpenClaw 的日志默认输出到 PM2。你可以使用pm2 logs openclaw-server --json输出 JSON 格式日志，便于接入 ELK 等日志系统。关键的日志类型包括：
   • [Platform]开头：平台连接与消息接收日志。
   • [Model]开头：AI 模型调用日志，包含耗时和 Token 使用情况。
   • ERROR级别：任何错误都应立即关注。
3. 健康检查：可以为 OpenClaw 的根路径/或特定健康检查端点配置一个定时任务（cron job）或监控系统探针，定期检查服务是否存活。

7. 常见问题与故障排除实录

在实际部署和运维中，我遇到了不少问题。这里把一些典型问题和解决方案整理成表，希望能帮你快速排雷。

问题现象	可能原因	排查步骤与解决方案
启动时报数据库连接错误	1. 数据库服务未运行。 2..env中数据库连接参数错误。 3. MySQL 用户权限不足。	1.docker compose ps检查 MySQL 容器状态。 2. 核对.env中的DB_HOST,PORT,USER,PASSWORD。 3. 用mysql -uopenclaw_user -p手动连接测试。 4. 检查 MySQL 用户是否有openclaw数据库的所有权限。
Telegram Bot 无响应	1. Webhook 未设置或设置失败。 2. Nginx 配置错误，请求未转发。 3. SSL 证书问题。	1. 执行npx openclaw-cli telegram get-webhook-info查看 Webhook 状态。 2. 使用curl -X POST https://ai.yourcompany.com/telegram/webhook -d "test"测试端点是否可达。 3. 检查 Nginxaccess.log和error.log。 4. 确保域名 SSL 证书有效且被 Telegram 信任。
飞书 URL 验证失败	1. 回调 URL 无法从公网访问。 2. OpenClaw 服务未运行或崩溃。 3.FEISHU_VERIFICATION_TOKEN配置错误或未重启服务。	1. 用浏览器或curl直接访问回调 URL，看是否有响应（可能是错误页面，但需有响应）。 2.pm2 logs openclaw-server查看启动和请求日志。 3. 确认.env中的 Token 与飞书后台完全一致，且已pm2 restart。 4. 飞书后台“事件订阅”页面，暂时取消“加密”和“Token校验”选项重试。
飞书机器人收不到消息	1. 事件未订阅。 2. 应用未发布或未启用。 3. 机器人未被添加到会话中。	1. 检查飞书后台“事件订阅”中，im.message.receive_v1是否已订阅并保存。 2. 检查“版本管理与发布”，应用是否已发布成功。 3. 在飞书群或私聊中，确认已成功添加该机器人。
AI 回复慢或超时	1. 模型 API 网络延迟高。 2. 服务器资源（CPU/内存）不足。 3. 知识库检索耗时过长。	1. 尝试切换不同的模型提供商（如从 OpenAI 换到 DeepSeek）。 2. 使用htop或pm2 monit监控服务器资源。 3. 对于知识库查询，优化文档分块大小和检索 top_k 参数。
[openclaw] could not start the cli	1. Node.js 版本不兼容。 2. 项目依赖未正确安装。 3. 环境变量文件.env缺失或格式错误。	1. 确认 Node.js 版本为 v18 或更高：node -v。 2. 删除node_modules和package-lock.json，重新运行npm install。 3. 检查项目根目录下是否存在.env文件，且内容格式正确（每行KEY=VALUE，无多余空格）。
PM2 服务频繁重启	1. 应用内存泄漏导致崩溃。 2. 未捕获的异常。	1. 查看pm2 logs openclaw-server --lines 100寻找崩溃前的错误日志。 2. 尝试增加 PM2 的 max-memory-restart 参数：pm2 restart openclaw-server --max-memory-restart 500M。

整个部署过程像是一次精心策划的联合作战，数据库、缓存、应用服务、反向代理、通讯平台，每一个环节都要严丝合缝。最大的体会是，日志是你的第一道防线，无论是 PM2 的日志、Nginx 的日志，还是飞书/Telegram 平台后台的事件日志，遇到问题先看日志，十有八九能找到线索。另外，对于飞书这类国内平台，网络连通性和 HTTPS 证书的有效性是重中之重，在服务器选择上（尤其是海外服务器）可能需要考虑加速方案。当你在两个完全不同的平台上，看到同一个 AI 助手用同一种口吻回复消息时，那种“一处部署，处处智能”的体验，会让之前所有的折腾都变得值得。