OpenClaw 安装配置指南

Mac Mini + OpenAI Codex (OAuth) + Telegram 消息接入，手把手完整教程

Mac Mini OpenAI Codex Telegram

目录

01环境准备 (Mac Mini) 02安装 OpenClaw 03Onboard 引导配置 (重点) 04配置 Telegram (详细) 05启动与验证 06常见问题
安装 Node.js
→
npm install
→
onboard 引导
→
配置 Telegram
→
开始使用
⚙

01 / 环境准备 (Mac Mini)

1

安装 Homebrew（如果还没有）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2

安装 Node.js 22+

# 方式一：Homebrew
brew install node

# 方式二：nvm (推荐，方便管理多版本)
brew install nvm
nvm install 24
nvm use 24
3

验证环境

node --version   # v22.16+ 或 v24.x
npm --version    # 10.x+
📦

02 / 安装 OpenClaw

npm (推荐)
一键脚本
npm install -g openclaw@latest
💡 如遇到 sharp/libvips 构建错误：SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest 
curl -fsSL https://openclaw.ai/install.sh | bash

一键脚本会自动检测 Node.js、安装 OpenClaw 并启动引导程序。

安装完成后，验证：

openclaw --version
⚠ 如果提示 command not found，将 npm 全局目录加入 PATH：在 ~/.zshrc 中添加 export PATH="$(npm prefix -g)/bin:$PATH"，然后 source ~/.zshrc
🤖

03 / Onboard 引导配置 (每步详解)

运行以下命令启动引导程序，下面逐步告诉你每一步选什么：

openclaw onboard --install-daemon
1

安全声明确认

会显示一段安全提示，说明 OpenClaw 默认是个人使用模式。

OpenClaw is "personal-by-default" ...
Do you understand the above?
❯ Yes, I understand

选 Yes, I understand，回车继续。

2

选择配置模式

How would you like to set up?
❯ QuickStart - minimal prompts, sensible defaults
Manual - granular control over port, bind, auth...

选 QuickStart。除非你需要自定义端口、绑定地址等，否则默认即可。

3

选择 AI 模型提供商 (关键步骤)

这一步会列出所有支持的 AI 提供商，你需要选择 OpenAI OAuth (Codex)：

Choose your AI provider:
Anthropic API key
Anthropic OAuth
OpenAI API key
❯ OpenAI Code (Codex) - OAuth login, uses ChatGPT subscription
Google Gemini
xAI (Grok)
Ollama (local)
...

选 OpenAI Code (Codex)，回车。

🌐
接下来会发生什么：
  • 浏览器自动打开 OpenAI / ChatGPT 登录页面
  • 用你的 ChatGPT 账号登录并授权
  • 授权成功后浏览器显示 "Authorization successful"，回到终端自动继续
  • 模型会自动设置为 openai-codex/gpt-5.4
💡 已有 Codex CLI？ 如果你之前用过 OpenAI Codex CLI，本地已有 ~/.codex/auth.json，OpenClaw 会自动复用，无需重新登录。
4

设置工作目录

Workspace directory:
❯ ~/.openclaw/workspace (default)

直接回车用默认路径即可，或输入自定义路径。

5

Gateway 配置

QuickStart 模式下大部分会用默认值，你只需一路回车：

Gateway port:
❯ 18789 (default)
Bind mode:
❯ Loopback (127.0.0.1) - local access only
LAN (0.0.0.0)
Tailnet
Auto
Custom IP
Auth mode:
❯ Token (recommended)
Password

三项都选默认：端口 18789、绑定 Loopback、认证 Token。

6

添加消息渠道

Add a messaging channel? (optional)
WhatsApp
❯ Telegram
Discord
Google Chat
Signal
iMessage (native)
Skip

选 Telegram。然后会要求你输入 Bot Token（下一章详细教你怎么获取）。

Telegram Bot Token:
❯ 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

粘贴你的 Bot Token，回车。如果还没有 Token，可以先选 Skip，后续用 openclaw channels add 再配置。

7

安装后台服务 (Daemon)

Install Gateway as a background service?
❯ Yes

选 Yes。在 Mac 上会通过 launchd 安装一个 LaunchAgent，效果是：

  • 开机自动启动 Gateway
  • 崩溃后自动重启
  • 配置文件位于 ~/Library/LaunchAgents/
8

健康检查 & 推荐 Skills

引导程序会自动运行健康检查，确认一切正常。然后可能会问是否安装推荐 Skills：

Install recommended skills?
❯ Yes
Package manager:
❯ npm
pnpm

选 Yes 安装推荐 Skills，包管理器选 npm。

✓

Onboard 完成！

终端会显示 Gateway 已启动，Dashboard 地址为 http://127.0.0.1:18789/

🛠 一键命令：如果你想跳过交互，也可以直接运行：
openclaw onboard --auth-choice openai-codex --install-daemon
✈

04 / 配置 Telegram (详细)

✈ Telegram Bot 创建与配置 消息平台

1

创建 Telegram Bot

  • 打开 Telegram，搜索并打开 @BotFather（认准蓝色认证标志）
  • 发送 /newbot
  • 按提示输入 Bot 的显示名称（如 "My AI Assistant"）
  • 输入 Bot 的用户名（必须以 bot 结尾，如 my_ai_helper_bot）
  • BotFather 返回 Token，格式如：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
🔒 妥善保管 Token！任何人拿到 Token 都可以控制你的 Bot。
2

设置 Bot 权限（推荐）

在 @BotFather 中继续操作：

  • /setprivacy → 选择你的 Bot → Disable（允许 Bot 读取群聊所有消息）
  • /setjoingroups → Enable（允许 Bot 被添加到群组）
3

在 OpenClaw 中配置 Telegram

如果在 onboard 时已经输入了 Token，这一步可以跳过。否则：

命令行添加
手动编辑配置
环境变量
openclaw channels add
# 选择 "telegram" → 粘贴 Bot Token

编辑 ~/.openclaw/openclaw.json：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "dmPolicy": "pairing"
    }
  }
}
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
4

首次对话 & 配对授权

Gateway 运行后，在 Telegram 中找到你的 Bot 发一条消息。默认 pairing 模式下，Bot 会返回一个配对码。

# 查看配对请求
openclaw pairing list telegram

# 审批配对（CODE 是 Bot 返回给你的配对码）
openclaw pairing approve telegram <CODE>

审批后即可正常对话。

5

获取你的 User ID（用于 allowlist 模式）

  • 方式一：openclaw logs --follow，发消息后在日志中找 from.id
  • 方式二：浏览器访问 https://api.telegram.org/bot<TOKEN>/getUpdates

拿到 User ID 后可以切换为 allowlist 模式，跳过配对步骤：

// ~/.openclaw/openclaw.json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "...",
      "dmPolicy": "allowlist",
      "allowFrom": ["你的UserID"]
    }
  }
}
✓

Telegram 配置完成！

现在可以在 Telegram 中和你的 AI Bot 对话了。

访问控制策略 (dmPolicy)

策略行为适用场景
pairing未知用户收到配对码，CLI 审批后才能交互默认，安全适中
allowlist仅 allowFrom 中的 User ID 可对话推荐个人使用
open任何人都能对话（需设 allowFrom: ["*"]）公开 Bot
disabled禁止所有私聊仅群组使用

群组配置（可选）

// ~/.openclaw/openclaw.json 中的 telegram 部分
{
  "groupPolicy": "allowlist",
  "groups": {
    "-1001234567890": {    // 群组 Chat ID
      "enabled": true,
      "requireMention": true,  // 需要 @Bot 才回复
      "allowFrom": ["你的UserID"]
    }
  }
}
🌐 代理设置（国内网络）："proxy": "socks5://user:pass@proxy:1080"
💡 流式输出："streaming": "partial" 让 Bot 边生成边发送，体验更好。可选值：off / partial / block / progress
▶

05 / 启动与验证

1

确认 Gateway 正在运行

openclaw status          # 查看 Gateway 状态
openclaw doctor          # 全面健康检查

如果 onboard 时安装了 daemon，Gateway 已经在后台运行了。如果没有：

openclaw gateway --port 18789 --verbose
2

命令行测试 AI 对话

openclaw agent --message "Hello, are you working?"
3

Telegram 测试

在 Telegram 中给你的 Bot 发一条消息，等待回复。同时可以看日志：

openclaw logs --follow
4

打开 Dashboard

openclaw dashboard      # 浏览器打开 http://127.0.0.1:18789/

常用管理命令

命令用途
openclaw status查看 Gateway 状态
openclaw doctor健康检查
openclaw doctor --fix自动修复常见问题
openclaw logs --follow实时查看日志
openclaw channels add添加消息渠道
openclaw models list查看可用模型
openclaw update更新到最新版
openclaw dashboard打开 Web 管理界面
❓

06 / 常见问题

问题解决方案
openclaw 命令找不到在 ~/.zshrc 中添加：export PATH="$(npm prefix -g)/bin:$PATH"
sharp / libvips 构建失败SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
OAuth 浏览器不弹出手动复制终端显示的 URL 到浏览器打开
OpenAI Codex 登录失败确认你有 ChatGPT Plus/Pro 订阅；删除 ~/.codex/auth.json 重试
Gateway 无法启动openclaw doctor --fix
Telegram Bot 不回复检查 Gateway 是否运行（openclaw status）；查看日志（openclaw logs --follow）
Telegram Bot 群里不回复BotFather 中 /setprivacy 设为 Disable；配置中设置 requireMention: false
配对码过期配对码 1 小时有效，重新发消息获取新码
Telegram 连接不稳定IPv6 问题：添加 "network": {"autoSelectFamily": false}
如何切换 AI 模型openclaw models set openai-codex/gpt-5.4
launchd daemon 管理查看：launchctl list | grep openclaw
重启：openclaw gateway restart
Made with Claude Code · 2026