OpenClaw 使用 Mai 教程

OpenClaw 是一个多渠道 AI 网关与可扩展插件运行时，支持以插件方式接入第三方模型与工具。@acedatacloud/openclaw-provider 是官方的 OpenClaw 插件，把 Mai 上的 50+ 大语言模型以及 Google 网页搜索接入到 OpenClaw 中，使用一个 API Key 即可调用。

本文介绍如何在 OpenClaw 中安装、配置并使用 Mai 插件。

申请流程

要使用本插件，首先可以到 Mai 控制台，获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费体验本插件提供的服务。

安装 OpenClaw

如果尚未安装 OpenClaw，可以通过 npm 全局安装：

npm install -g openclaw

安装完成后检查命令是否可用：

openclaw --version

要求 Node.js 20 或更高版本。

安装 Mai 插件

OpenClaw 通过插件机制接入第三方模型。安装 @acedatacloud/openclaw-provider：

openclaw plugins install npm:@acedatacloud/openclaw-provider@2026.5.34 --pin

安装完成后，OpenClaw 会自动注册一个 acedatacloud 渠道，可以承载 Chat（对话）与 Web Search（网页搜索）两种能力。

安装后先做静态检查：

openclaw plugins info acedatacloud --runtime
openclaw plugins doctor
openclaw models list --all --provider acedatacloud
openclaw models status

配置 API Token

有三种方式配置 API Token：

方式一：环境变量（推荐）

把以下内容写入 ~/.zshrc、~/.bashrc 或 ~/.bash_profile：

export ACEDATA_API_KEY="{token}"

其中 {token} 替换为您在 Mai 控制台复制的 API Token。也可以使用别名环境变量 ACEDATACLOUD_API_KEY，两者等价。

配置后重新打开终端，或执行：

source ~/.zshrc

方式二：交互式 onboarding

运行：

openclaw onboard --auth-choice acedatacloud-api-key

OpenClaw 会提示输入 API Token，并自动写入用户配置文件。

方式三：命令行参数

也可以在调用时直接通过 --acedata-api-key <key> 参数传入。

使用 Chat 能力

配置完成后，即可在 OpenClaw 中调用 Mai 提供的 LLM。模型 ID 形式为 acedatacloud/<model-name>。

一次性 Agent 调用 —— 使用当前 openclaw agent --local 跑单轮对话：

openclaw agent --local --session-id coding-plan-check --model acedatacloud/MODEL_ID --json -m "Reply exactly OPENCLAW_OK"

openclaw plugins info acedatacloud --runtime

设为默认模型 —— 之后交互式 / Agent 运行都会默认使用它：

openclaw models set acedatacloud/MODEL_ID

单次 Agent 任务 —— 让本地 Agent 跑一轮（需当前 shell 已设置 API Token）：

openclaw agent --local --session-id coding-plan-check --model acedatacloud/MODEL_ID --json -m "Reply exactly OPENCLAW_OK"

选择精确模型

模型列表以选择器与实时目录的交集为准，不在本文维护一份容易过期的静态副本。选择器只会为当前profile已完成证据绑定的精确模型生成配置。

插件支持把acedatacloud/<id>请求按OpenAI兼容方式发送到https://api.ai.moses.day/v1：

openclaw agent --local --session-id coding-plan-check --model acedatacloud/MODEL_ID --json -m "Reply exactly OPENCLAW_OK"

动态 ID 仍必须同时出现在选择器当前 allowlist，并完成本 profile 的客户端工具调用证据；仅出现在 /v1/models 不保证 OpenClaw 兼容。

插件同时注册了一个网页搜索 provider，使用 Mai 的 Google SERP 接口。OpenClaw 会在 Agent 工作流中自动调用，也可用 openclaw infer web search 显式调用：

openclaw infer web search --provider acedatacloud --query "最新的 AI Agent 框架" --limit 5

命令行可用参数为 --provider、--query、--limit、--json。底层的 Google SERP 接口还支持 search（网页，默认）、images、news、videos、maps、places 等搜索类型，OpenClaw 在 Agent 工作流中会按需选用。

计费说明

插件本身不会重复计费 —— 所有用量都在 Mai 平台侧按 Credits 计算（按模型与请求大小定价）。Chat 与 Web Search 共用同一个 API Token，调用记录可在 platform.acedata.cloud/console/usages 查看。

为了避免 OpenClaw 客户端做重复估算，插件向 OpenClaw 报告 cost: 0。

手动配置

如果希望直接编辑配置文件，可在 ~/.openclaw/openclaw.json 中写入 API Token、默认模型并启用插件：

{
  agents: {
    defaults: {
      model: { primary: "acedatacloud/MODEL_ID" },
    },
  },
  plugins: {
    allow: ["acedatacloud"],
    entries: {
      acedatacloud: { enabled: true },
    },
  },
}

不要自行添加跨模型fallback。fallback会改变实际模型与计费合同，只有选择器明确生成并标注时才能启用。

故障排查

现象 排查方向
Ace Data Cloud API key not configured 未设置 ACEDATA_API_KEY/ACEDATACLOUD_API_KEY，或 onboarding 未完成
HTTP 401 API Token 错误或被禁用，请到控制台重新生成
HTTP 402 余额不足，请到 platform.acedata.cloud/console/balance 充值
HTTP 429 触发请求频率限制，请稍后重试或在控制台调整并发上限
模型 ID 不在内置目录但仍能调用 这是预期行为：动态 ID passthrough

更多调试日志可通过全局参数 --log-level debug 打开，例如 openclaw --log-level debug agent --local --model acedatacloud/MODEL_ID -m "test"。

相关链接