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

# OpenClaw 自定义模型接入 LLMEasy 指南

> 在 OpenClaw 这个多平台 AI 智能体 Gateway 网关中接入 LLMEasy。

OpenClaw 是一个适用于 Discord、Google Chat、iMessage、Matrix、Microsoft Teams、Signal、Slack、Telegram、WhatsApp、Zalo 等更多平台的任意操作系统 AI 智能体 Gateway 网关。这篇文档会带你把 LLMEasy 接入 OpenClaw，并完成基础验证。

## 安装 OpenClaw

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://openclaw.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```
  </Tab>
</Tabs>

## 安装接入

<Tabs>
  <Tab title="自动配置">
    你可以直接运行 LLMEasy 提供的自动配置脚本。运行前请准备好 LLMEasy API Key。脚本需要 `Node.js`。如果你没有显式传入 API Key 或模型，脚本会按工具能力提示你交互输入。脚本执行完成后，请继续看下方“运行生效”。

    按你的操作系统执行对应步骤。你只需要执行其中一项。

    <Steps>
      <Step title="如果你使用 macOS / Linux">
        ```bash theme={null}
        curl -fsSL https://www.llmeasy.ru/install-openclaw-provider.sh | bash
        ```
      </Step>

      <Step title="如果你使用 Windows">
        ```powershell theme={null}
        iwr https://www.llmeasy.ru/install-openclaw-provider.ps1 -OutFile "$env:TEMP\install-openclaw-provider.ps1"; powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-openclaw-provider.ps1"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="通过 CC-Switch 配置">
    这条接入路径由 [CC Switch 接入文档](/zh/ai-tools/cc-switch#openclaw) 统一维护。

    直接查看 [CC Switch 中的 OpenClaw 配置步骤](/zh/ai-tools/cc-switch#openclaw)。

    通过 CC Switch 完成配置后，再回到本页继续参考启动、验证或生效说明。
  </Tab>

  <Tab title="手动配置">
    <Steps>
      <Step title="清除冲突的环境变量">
        ```bash theme={null}
        unset ANTHROPIC_AUTH_TOKEN
        unset ANTHROPIC_BASE_URL
        unset OPENAI_API_KEY
        unset OPENAI_BASE_URL
        ```
      </Step>

      <Step title="运行 onboarding">
        ```bash theme={null}
        openclaw onboard --install-daemon
        ```

        按向导完成 Gateway 和基础组件安装。
      </Step>

      <Step title="通过认证入口添加 LLMEasy 凭证">
        ```bash theme={null}
        openclaw models auth add
        ```
      </Step>

      <Step title="添加或确认 LLMEasy provider">
        在向导或 provider 编辑器中填写或确认以下内容：

        * **Base URL**：`https://www.llmeasy.ru/v1`
        * **API**：`openai-responses`
        * **API Key**：你的 LLMEasy API Key
        * **模型**：从<a href={"https://www.llmeasy.ru/pricing"}>模型广场</a>复制当前可用的 GPT 分组模型 ID

        最小 provider 配置片段可以写成：

        ```json theme={null}
        {
          "models": {
            "mode": "merge",
            "providers": {
              "llmeasy": {
                "baseUrl": "https://www.llmeasy.ru/v1",
                "apiKey": "YOUR_LLMEASY_API_KEY",
                "api": "openai-responses",
                "models": [
                  {
                    "id": "YOUR_GPT_MODEL_ID",
                    "name": "YOUR_GPT_MODEL_ID"
                  }
                ]
              }
            }
          }
        }
        ```
      </Step>

      <Step title="一般不需要额外配置 `headers`">
        接入 LLMEasy 时通常不需要额外设置 `User-Agent`。

        只有在你同时接入了自定义网关、租户路由或其他要求额外 headers 的上游服务时，再按对应文档补充。
      </Step>

      <Step title="设置默认模型并验证">
        先运行 `openclaw models list`，确认当前 provider id，再设置默认模型并检查状态：

        ```bash theme={null}
        openclaw models list
        openclaw models set <provider>/<从 https://www.llmeasy.ru/pricing 复制的 Codex 模型 ID>
        openclaw gateway restart
        openclaw models status
        ```

        配置写入后，请继续看下方“运行生效”完成重启和会话验证。
      </Step>
    </Steps>
  </Tab>
</Tabs>

### 多 Agent 与已有会话的注意事项

OpenClaw 中模型生效的优先级通常是：

`session override` > `agents.list[*].model` > `agents.defaults.model.primary`

这意味着：

* 如果某个 agent 在 `agents.list` 里显式写了 `model`，它不会继承全局默认模型。
* 如果你把 LLMEasy 设为全局默认模型，但 `main` 仍写着旧模型，那么 Discord 私聊等默认走 `main` 的场景仍会继续使用旧模型。
* 如果历史会话里残留了 `providerOverride`、`modelOverride` 或 `authProfileOverride`，即使你已经修改了默认模型，当前会话也可能继续使用旧渠道。

推荐做法：

1. 想让 `main` 跟随全局默认时，不要给 `main` 单独写 `model`，或者把它改成 LLMEasy。
2. 修改配置后执行 `openclaw gateway restart`。
3. 在 Discord 中执行 `/new` 新开会话。
4. 再用 `/status` 和 `/model` 验证当前生效模型。

### 最小配置示例

provider id 以 `openclaw models list` 的实际输出为准。下面用 `llmeasy/gpt-5.4` 举例；如果你的 provider id 不同，请按实际值替换。

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "llmeasy/gpt-5.4",
        "fallbacks": []
      },
      "models": {
        "llmeasy/gpt-5.4": {
          "alias": "llmeasy"
        }
      }
    },
    "list": [
      {
        "id": "main"
      },
      {
        "id": "fitness-coach"
      },
      {
        "id": "trade-recorder",
        "model": {
          "primary": "llmeasy/gpt-5.4",
          "fallbacks": []
        }
      }
    ]
  }
}
```

* `main` 没写 `model`，所以会继承全局 LLMEasy。
* `trade-recorder` 写了 `model`，所以它不会跟随全局默认变化。

## 运行生效

<Tip>
  如果你在旧版 OpenClaw 上遇到 `/model` picker 不稳定、热刷新不及时或模型列表异常，先升级到最新版再排查。
</Tip>

<Steps>
  <Step title="先做配置层验证">
    运行以下命令，确认 LLMEasy provider 和默认模型已经写入配置：

    ```bash theme={null}
    openclaw models list
    openclaw models status
    ```
  </Step>

  <Step title="重载服务">
    ```bash theme={null}
    openclaw gateway restart
    ```
  </Step>

  <Step title="新开会话">
    在 Discord 中执行 `/new`。
  </Step>

  <Step title="验证当前会话实际模型">
    在 Discord 中执行 `/status`，确认当前 Agent / 当前会话已经切到 LLMEasy。
  </Step>

  <Step title="按需检查可选模型列表">
    在 Discord 中执行 `/model`。

    如果这里看不到 LLMEasy，优先检查：

    * 当前模型是否已加入 `agents.defaults.models`
    * provider 下该模型的显示名是否正常，必要时是否已在 `agents.defaults.models` 中添加 `alias`
    * 是否已经执行过 `openclaw gateway restart`
    * 是否已经通过 `/new` 新开会话
  </Step>
</Steps>

## 排障提示

* 默认模型改了但实际仍是旧模型，优先检查 `agents.list.main.model`
* `/model` 看不到 LLMEasy，优先检查它是否在 `agents.defaults.models` 中
* 改完配置后 Discord 里仍是旧结果，先执行 `openclaw gateway restart`，再执行 `/new`
* 如果模型 picker 或热刷新仍不稳定，先升级到最新版 OpenClaw 再排查

## 让 Codex 帮你兜底配置

如果你不想手动改配置，可以先在终端里设置 API Key 环境变量，然后启动 Codex：

```bash theme={null}
export LLMEASY_API_KEY="YOUR_API_KEY"
codex
```

然后把下面这段 prompt 发给 Codex：

```text theme={null}
请帮我检查并修复本机 OpenClaw 的 LLMEasy 配置。要求：
1. 先读取当前 OpenClaw 配置，确认 provider id、默认模型，以及 agents.list 中哪些 agent 显式写了 model。
2. 如果 LLMEasy provider 不存在，就新增一个指向 Base URL `https://www.llmeasy.ru/v1` 的 provider，并写入 `api: "openai-responses"`。
3. 优先复用 OpenClaw 已保存的认证信息。只有当当前版本或你的上游网关明确要求额外 headers 时，才单独配置；不要默认把 `User-Agent` 当作 LLMEasy 必填项。
4. 把默认模型切到 LLMEasy，并检查 `main` 是否被显式 model 覆盖；如果我希望 `main` 跟随全局默认，就删除它的显式 model。
5. 确保当前 LLMEasy 模型出现在 `agents.defaults.models` 中，并补一个易识别的 `alias`。
6. 备份原配置，使用最小 diff 修改，修改前先告诉我会改哪些字段。
7. 修改后执行 `openclaw gateway restart`，最后提醒我在 Discord 里依次执行 `/new`、`/status`、`/model` 做验证。

约束：
- 如果需要 API Key，请从环境变量 `LLMEASY_API_KEY` 读取，不要把密钥写进聊天或日志。
- 如果当前配置里没有 LLMEasy 模型，请先提示我从 LLMEasy 模型广场提供一个 GPT 分组模型 ID。
```

## 相关 FAQ

* [OpenAI-compatible API 和 Anthropic-compatible API 有什么区别？](/zh/faq/concepts/openai-compatible-vs-anthropic-compatible)
* [MCP 和 API Key / Base URL 有什么区别？](/zh/faq/concepts/mcp-vs-api-key-base-url)
* [Codex CLI 中 model\_provider、base\_url 和 wire\_api 是什么？](/zh/faq/codex/model-provider-base-url-wire-api)
* [Cline 如何配置 OpenAI-compatible API？](/zh/faq/cline/openai-compatible-api)