> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw 使用 Ace Data Cloud 教程

> AceDataCloud Coding Plan 集成指南 - Ace Data Cloud

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

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

## 申请流程

要使用本插件，首先可以到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)，获取您的 API Token，留作备用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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

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

## 安装 OpenClaw

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

```bash theme={null}
npm install -g openclaw
```

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

```bash theme={null}
openclaw --version
```

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

## 安装 Ace Data Cloud 插件

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

```bash theme={null}
openclaw plugins install npm:@acedatacloud/openclaw-provider@2026.5.34 --pin
```

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

安装后先做静态检查：

```bash theme={null}
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`：

```bash theme={null}
export ACEDATA_API_KEY="{token}"
```

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

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

```bash theme={null}
source ~/.zshrc
```

### 方式二：交互式 onboarding

运行：

```bash theme={null}
openclaw onboard --auth-choice acedatacloud-api-key
```

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

### 方式三：命令行参数

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

## 使用 Chat 能力

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

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

```bash theme={null}
openclaw agent --local --model acedatacloud/MODEL_ID -m "Reply exactly OPENCLAW_OK"
```

```bash theme={null}
openclaw plugins info acedatacloud --runtime
```

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

```bash theme={null}
openclaw models set acedatacloud/MODEL_ID
```

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

```bash theme={null}
openclaw agent --local --model acedatacloud/MODEL_ID -m "Reply exactly OPENCLAW_OK"
```

### 选择精确模型

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

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

```bash theme={null}
openclaw agent --local --model acedatacloud/MODEL_ID -m "Reply exactly OPENCLAW_OK"
```

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

## 使用 Web Search 能力

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

```bash theme={null}
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 工作流中会按需选用。

## 计费说明

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

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

## 手动配置

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

```json5 theme={null}
{
  env: { ACEDATA_API_KEY: "ace-..." },
  agents: {
    defaults: {
      model: { primary: "acedatacloud/MODEL_ID" },
    },
  },
  plugins: {
    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`](https://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"`。

## 相关链接

* 插件仓库：[`AceDataCloud/OpenClawProvider`](https://github.com/AceDataCloud/OpenClawProvider)
* npm 包：[`@acedatacloud/openclaw-provider`](https://www.npmjs.com/package/@acedatacloud/openclaw-provider)
* OpenClaw 官网：[`openclaw.ai`](https://openclaw.ai)
* Ace Data Cloud 控制台：[`platform.acedata.cloud`](https://platform.acedata.cloud)