🦞 OpenClaw 配置 Codex.surf 教程

OpenClaw 是一个开源（MIT 许可）的自托管网关，可将 WhatsApp、Telegram、Discord、iMessage 等聊天应用连接到 AI 编码代理，支持多代理路由、工具使用和会话记忆。更多信息请参考 OpenClaw 官网。本教程将指导你如何在 OpenClaw 中安装并配置 Codex.surf API。

步骤 1：安装 OpenClaw

🍎 macOS / 🐧 Linux

方法一：官方安装脚本（推荐）

自动检测环境并安装所有依赖：

curl -fsSL https://openclaw.ai/install.sh | bash

方法二：npm

npm install -g openclaw@latest

方法三：pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g

⊞ Windows

方法一：PowerShell 安装脚本（推荐）

iwr -useb https://openclaw.ai/install.ps1 | iex

方法二：npm（CMD / PowerShell 均可）

npm install -g openclaw@latest

方法三：pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g

初始化

安装完成后，运行初始化向导：

openclaw onboard --install-daemon

步骤 2：获取 API 密钥

访问 Codex.surf 控制台，创建一个新的令牌：

• 点击「添加令牌」
• 名称：随便填写，方便自己区分即可
• 令牌分组：根据实际需要选择，分组有详细描述（必填项，不能留空）
• 额度建议：设置为无限额度

创建成功后，复制令牌备用。

步骤 3：配置 OpenClaw

配置文件位置

Codex.surf 配置示例

在 openclaw.json 中添加或修改以下内容：

{
  "meta": {
    "lastTouchedVersion": "2026.2.3-1",
    "lastTouchedAt": "2026-02-06T10:08:26.053Z"
  },
  "wizard": {
    "lastRunAt": "2026-02-06T10:06:14.214Z",
    "lastRunVersion": "2026.2.3-1",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  },
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "model": {
        "primary": "codex-surf-claude/claude-opus-4-6"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "codex-surf-claude": {
        "baseUrl": "https://codex.surf",
        "apiKey": "你的API密钥",
        "api": "anthropic-messages",
        "headers": {
          "User-Agent": "claude-cli/2.0.76 (external, cli)",
          "Authorization": "Bearer 你的API密钥"
        },
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "claude-opus-4-6"
          }
        ]
      },
      "codex-surf-codex": {
        "baseUrl": "https://api.codex.surf/v1",
        "apiKey": "你的API密钥",
        "api": "openai-completions",
        "headers": {
          "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
          "Authorization": "Bearer 你的API密钥"
        },
        "models": [
          {
            "id": "gpt-5.2-codex",
            "name": "gpt-5.2-codex"
          }
        ]
      }
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "保留默认值即可"
    },
    "mode": "local"
  }
}

关键配置说明

models.providers.codex-surf-claude — Claude 模型配置：

models.providers.codex-surf-codex — Codex 模型配置：

可用模型：访问 Codex.surf 模型广场 查看所有可用模型。如需添加更多模型，在对应 provider 的 models 数组中追加即可。

步骤 4：启动并验证

配置完成后，先运行诊断命令检查配置是否正确：

openclaw doctor

确认无误后，重启 gateway 使配置生效：

openclaw gateway restart

然后启动 TUI 界面验证配置是否正常：

openclaw tui

如果能正常对话，说明配置成功。

步骤 5：对接 QQ（可选）

如果你希望通过 QQ 与 OpenClaw 交互，可以按照以下步骤完成对接。OpenClaw 官方提供了 QQ 机器人接入页面，整个流程非常简单。

5.1 创建 QQ 机器人

1. 访问 OpenClaw QQ 机器人接入页面，使用 QQ 账号登录
2. 点击页面中的「创建机器人」按钮

5.2 复制机器人凭证

机器人创建成功后，页面会显示以下信息：

• AppID — 机器人的唯一标识
• AppSecret — 机器人的密钥

同时页面会展示 OpenClaw 原生接入流程，包含需要执行的命令。

5.3 在 OpenClaw 侧完成 QQ 配置

根据页面提示，依次执行以下命令：

# 1. 安装 OpenClaw 社区 QQBot 插件
openclaw plugins install @sliverp/qqbot@latest

# 2. 配置绑定当前 QQ 机器人（token 值从页面复制）
openclaw channels add --channel qqbot --token "你的Token"

# 3. 重启网关使配置生效
openclaw gateway restart

5.4 两种安装方式

你可以选择以下任一方式执行上述命令：

方式一：通过 OpenClaw Gateway Dashboard 的聊天界面

直接在 OpenClaw 的 Web 管理界面中，将页面提供的信息和命令发送给 OpenClaw，它会自动执行安装和配置。

方式二：通过已接入的 IM 渠道发送

如果你已经有其他 IM 渠道（如 Telegram、飞书等）连接到 OpenClaw，也可以直接通过该渠道将信息发送给 OpenClaw 完成安装。

5.5 测试验证

配置完成后，即可在 QQ 中测试：

1. 在 QQ 中找到你创建的机器人
2. 发送一条消息，确认机器人能正常响应
3. 支持 Markdown、图片、语音、文件等多媒体消息收发
4. 手机端 QQ、桌面端 QQ 均可使用

QQ 对接常见问题

步骤 6：对接飞书（可选）

如果你希望通过飞书与 OpenClaw 交互，可以按照以下步骤完成对接。

6.1 登录飞书开放平台

1. 访问 飞书开放平台，使用飞书账号登录
2. 需要企业管理员或具备开发者权限的账号
3. 进入「开发者后台」

6.2 创建企业自建应用

1. 点击「创建企业自建应用」
2. 填写应用信息：
   • 应用名称（如 OpenClaw 助手）
   • 应用描述（如 基于 OpenClaw 的 AI 智能助手）
   • 应用图标（上传一张辨识度高的图标）
3. 确认创建

6.3 获取应用凭证

1. 进入刚创建的应用，点击左侧菜单「凭证与基础信息」
2. 记录以下两个值（后续配置 OpenClaw 时需要）：
   • App ID（格式类似 cli_a90f701cf9f99bd8）
   • App Secret

6.4 添加机器人能力

1. 在左侧菜单找到「应用能力」→「机器人」
2. 点击开启机器人能力
3. 可自定义机器人的名称和描述

6.5 配置应用权限

有两种方式，任选其一。

方式一：JSON 批量导入（推荐）

1. 在左侧菜单点击「权限管理」
2. 找到页面右上角的「批量导入」按钮
3. 粘贴以下 JSON 并确认导入：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "cardkit:card:write",
      "im:resource"
    ],
    "user": [
      "aily:file:read",
      "aily:file:write",
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

1. 导入后，检查权限列表，如果有「申请」按钮的权限，点击逐一申请
2. 企业自建应用的权限通常会自动通过审批

方式二：手动逐个开通

在「权限管理」中搜索并开通以下权限：

6.6 配置事件订阅

1. 在左侧菜单找到「事件与回调」→「事件配置」
2. 订阅方式选择「使用长连接接收事件」（推荐）
3. 点击「添加事件」，搜索并添加 im.message.receive_v1（即「接收消息 v2.0」）

6.7 创建版本并发布

1. 进入飞书开放平台「版本管理与发布」
2. 点击「创建版本」，填写版本说明（如 OpenClaw AI 助手 v1.0）
3. 设置应用的「可用范围」（至少添加自己或一个测试群）
4. 点击「保存」→「申请发布」
5. 等待企业管理员审核通过（企业自建应用通常审核较快）

6.8 在 OpenClaw 侧完成飞书配置

飞书应用发布成功后，再配置 OpenClaw 侧并启动网关：

# 1. 安装飞书插件
openclaw plugins install feishu-openclaw

# 2. 启用飞书通道并配置凭证
openclaw config set channels.feishu.enabled true --json
openclaw config set channels.feishu.appId "你的AppID"
openclaw config set channels.feishu.appSecret "你的AppSecret"

# 3. 重启网关使配置生效
openclaw gateway restart

# 4. 验证状态
openclaw status
# 预期输出：Feishu | ON | OK | configured

6.9 测试验证

发布审核通过且 OpenClaw 网关启动后，即可开始测试：

1. 在飞书客户端搜索你的机器人名称，或将其添加到一个测试群
2. 私聊机器人发送一条消息，确认能正常响应
3. 在群聊中 @机器人 发送消息，确认群聊场景也正常
4. 测试图片、文件等富媒体消息的收发（如果需要）

飞书对接常见问题

附录：配置字段说明