OpenClaw 部署指南：打造私人 AI 助手

OpenClaw 是一款运行在自有设备上的私人 AI 助手。它采用“本地优先”的设计理念，能够将消息、语音和视觉交互无缝集成到一个统一的系统中。不同于简单的聊天机器人，OpenClaw 作为一个全天候在线的智能中枢，可以连接 Telegram、Slack、WhatsApp 等多种通讯渠道，让用户随时随地都能与自己的 AI 助手保持连接。

本文将详细介绍如何在 Ubuntu 24.04.3 LTS 环境下部署 OpenClaw，配置 Telegram 机器人，以及集成自定义的 OpenAI 兼容 API，快速搭建属于自己的、隐私安全的 AI 智能体。

1. 架构概览

OpenClaw 采用模块化设计，其核心架构如下图所示：

WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │
  │                           │  http://<gateway-host>:18793
  │                           │    /__openclaw__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
              ├─ CLI (openclaw …)
              ├─ Chat UI (SwiftUI)
              ├─ macOS app (OpenClaw.app)
              ├─ iOS node via Gateway WS + pairing
              └─ Android node via Gateway WS + pairing

2. 部署环境准备

服务器环境如下：

• 操作系统: Ubuntu 24.04.3 LTS (Noble Numbat)
• Node.js: v22.22.0 (需要 22 或更高版本)
• 用户权限: 建议使用非特权用户（如 openclaw）运行服务
• OpenClaw 版本: 本文基于 2026.2.1 版本

3. 安装 OpenClaw

3.1 安装 CLI 工具

使用 npm 全局安装 OpenClaw：

npm install -g openclaw@latest

3.2 验证安装

安装完成后，检查版本以确保安装成功：

openclaw --version

4. 初始化配置 (Onboarding)

OpenClaw 提供了一个方便的 onboard 命令来引导我们完成初始化配置。

4.1 运行向导

使用 onboard 命令开始初始化配置，--install-daemon 参数会在初始化完成后自动安装并启动 Gateway 服务守护进程：

openclaw onboard --install-daemon

4.2 配置选项详解

在向导运行过程中，需要根据实际情况进行选择。以下是推荐的配置路径：

1. 安全警告: 选择 Yes 继续。
2. Onboarding mode: 选择 QuickStart 以快速开始。
3. Model/auth provider: 可以选择 Skip for now，我们将在后续手动配置自定义 API。
4. Default model: 选择 Keep current。
5. Select channel: 关键步骤，选择 Telegram (Bot API)。
6. Telegram bot token: 输入从 BotFather 获取的 Token（获取方法见下文）。
7. Configure skills: 选择 Skip for now，后续按需添加。
8. Homebrew: 选择 No。
9. Node manager: 选择 npm。
10. Install missing skill dependencies: 选择 Skip for now。
11. API Keys: 如果有特定的 API Key，可以在此时配置，否则选择 No。
12. Enable hooks: 选择 Skip for now。
13. Install shell completion: 建议选择 Yes，方便后续操作。

初始化完成后，OpenClaw 会提示重新加载 shell 配置。如果在新的终端窗口中找不到 openclaw 命令，请尝试执行以下命令或打开新的终端窗口：

source ~/.bashrc

5. 获取 Telegram Bot Token

如果还没有 Telegram Bot，需按照以下步骤创建：

1. 打开 Telegram，搜索 @BotFather。
2. 发送 /newbot 指令。
3. 设置机器人的显示名称（例如：My AI Assistant）。
4. 设置机器人的用户名（必须以 bot 结尾，例如：my_ai_assistant_bot）。
5. BotFather 会返回一个 API Token，格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz，请妥善保存。

6. Gateway 服务

如果在初始化时添加了 --install-daemon 参数，Gateway 服务会自动启动并设置为开机自启。

6.1 常用管理命令

# 查看服务状态
openclaw gateway status

# 重启服务（修改配置后需要重启）
openclaw gateway restart

# 查看实时日志
openclaw logs --follow

6.2 手动安装（仅限未自动安装时）

如果在初始化时没有安装守护进程，可以手动安装：

openclaw gateway install

7. Telegram 用户配对 (Pairing)

出于安全考虑，OpenClaw 默认不会响应所有 Telegram 用户的消息，需要完成配对流程。

1. 在 Telegram 中给我们的机器人发送任意消息。
2. 会收到一条回复，包含我们的 User ID 和 Pairing Code：
   OpenClaw: access not configured.
   Your Telegram user id: 123456789
   Pairing code: 1234
   Ask the bot owner to approve with:
   openclaw pairing approve telegram 1234

3. 回到服务器终端，执行批准命令：
   openclaw pairing approve telegram <pairing_code>

4. 可以使用 openclaw pairing list telegram 查看当前的配对请求。

8. 配置自定义 OpenAI 兼容 API

OpenClaw 的强大之处在于其灵活性。可以通过修改配置文件来接入任何兼容 OpenAI 接口的模型服务（如本地部署的 LLM、LiteLLM 或其他第三方 API）。

8.1 编辑配置文件

配置文件位于 ~/.openclaw/openclaw.json。我们需要添加 models 部分的配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "myprovider": {
        "baseUrl": "https://your-api-endpoint.com/v1",
        "apiKey": "your-api-key",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.2",
            "name": "GPT-5.2",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 391000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "myprovider/gpt-5.2"
      },
      "models": {
         "myprovider/gpt-5.2": {"alias": "GPT"}
      }
    }
  }
}

8.2 API 协议类型选择

配置中的 api 字段决定了 OpenClaw 如何与模型交互：

• openai-completions: OpenAI 兼容的 Completions 端点。适用于大多数第三方 API 和自建服务。
• openai-responses: OpenAI 兼容的 Response 格式。适用于需要更高级控制的场景。
• anthropic-messages: Anthropic 兼容的消息 API。
• google-generative-ai: Google 的 Generative AI 端点。

配置自定义提供商时，OpenClaw 需要知道目标 API 的类型以便正确格式化请求。对于大多数自建或第三方模型服务，通常选择 openai-completions。如果 API 提供商支持更高级的 openai-responses 格式，则可以获得更好的兼容性。此外，对于需要自定义认证的场景，可以配合 authHeader: true 和 headers 字段使用。

8.3 应用配置

验证配置是否正确：

openclaw models status

重启 Gateway 使配置生效：

openclaw gateway restart

9. 常见问题排查

9.1 API 请求被拦截 (403 Forbidden)

现象： Telegram 机器人回复 “403 Your request was blocked”。

原因： 自定义 API 接入了 Cloudflare 等 CDN 服务，OpenClaw 的请求可能触发了 Cloudflare 的 WAF（Web Application Firewall）或 “Super Bot Fight Mode” 规则，被识别为自动化脚本并拦截。

排查与解决：

1. 确认拦截源： 建议登录 Cloudflare 后台，进入 Security > Events 查看拦截日志。如果能找到来自 OpenClaw Gateway 服务器出口 IP 的拦截记录（Action 通常为 Block 或 Managed Challenge），即可确认为 Cloudflare 拦截。

2. 配置 Cloudflare 白名单（推荐）： 登录 Cloudflare 后台，进入 Security > WAF > Custom rules，创建一个新规则：

   • Rule name: Allow OpenClaw
   • If incoming requests match: IP Source Address equals <OpenClaw Gateway服务器出口公网 IP>
   • Then: Skip (选择 All remaining custom rules, WAF, Super Bot Fight Mode 等)

   这样可以确保服务器发出的 API 请求不会被误拦，同时不影响其他访问者的安全规则。

10. 进阶配置：Telegram 权限策略

除了配对模式，还可以通过 dmPolicy 字段调整 Telegram 的私聊策略。推荐使用 pairing 模式以确保安全。

在 ~/.openclaw/openclaw.json 中配置：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "allowlist"
    }
  }
}

可选策略：

• pairing（默认）：收到未知用户消息时发送配对码，需管理员批准后才能交互。
• allowlist：仅允许 allowFrom 列表中的用户交互。
• open：允许所有用户交互（需在 allowlist 中包含 "*"，慎用）。
• disabled：禁用私聊功能。

11. 总结

通过以上步骤，我们已经成功部署了一个基于 OpenClaw 的 AI 代理服务，并通过 Telegram 与其建立了连接。OpenClaw 的可扩展性很强，可以在此基础上进一步探索 Skill 插件、Agent 编排等高级功能，打造真正属于我们自己的智能助手。

参考文档

• 官方安装文档
• Gateway 配置
• Telegram 配置
• 安全配置