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

# OpenClaw

> 通过自定义提供商入驻或配置文件，将 OpenClaw 指向 FlexInference。

OpenClaw 通过自定义提供商连接任何与 OpenAI 兼容的端点。入驻过程会为您写入条目，之后配置文件会保存它。

OpenClaw 本身没有单独的每请求截止时间字段，因此截止时间会附加到密钥上。请先创建一个密钥（参见[代理密钥](/zh/agent-keys)）。

## 使用代理进行设置

打开下方代码块并将其复制到任何编码代理中。提示词绝不会要求您的 API 密钥：代理会配置所有其他内容，然后打印出您需要自行运行的导出命令。

<Accordion title="复制代理设置提示">
  ```text theme={null}
  Configure OpenClaw to send its requests to FlexInference through a custom provider. Use the OpenClaw CLI, not hand-edited JSON, so every write is schema-validated.

  You will never see or handle my API key. OpenClaw will read it from the `FLEXINFERENCE_API_KEY` environment variable through a secret reference, and I export that myself. Do not ask me for the key, do not pass it on any command line, and do not read it from my environment.

  Ask whether to use my default OpenClaw profile or a separate one. A separate profile isolates config, state, gateway port, and workspace, and is the safe way to try this. Prefix every command with `--profile flex` if I choose one.

  1. Confirm which config file is active with `openclaw config file`.

  2. Tell me to export the key first, and stop until I confirm. Print this line; do not run it and do not ask for the value:

  export FLEXINFERENCE_API_KEY=<paste your key here>

  3. Write the provider entry. It carries no credential. The model row is required, because OpenClaw refuses a third-party provider that declares no `models`; step 5 replaces it with the full catalog:

  openclaw config set models.providers.flexinference --merge --strict-json '{"baseUrl":"https://api.flexinference.com/v1","api":"openai-completions","models":[{"id":"gpt-5.6-sol","name":"GPT-5.6 Sol","compat":{"supportsUsageInStreaming":true}}]}'

  4. Declare an environment secrets provider, then point the provider's apiKey at it. Both commands pass only the VARIABLE NAME, never the value:

  openclaw config set secrets.providers.default \
    --provider-source env --provider-allowlist FLEXINFERENCE_API_KEY

  openclaw config set models.providers.flexinference.apiKey \
    --ref-provider default --ref-source env --ref-id FLEXINFERENCE_API_KEY

  5. Fill the model list from the live FlexInference catalog rather than by hand:

  curl -s https://api.flexinference.com/v1/models \
    -H "Authorization: Bearer $FLEXINFERENCE_API_KEY" \
  | jq '{models:{providers:{flexinference:{models:
      [.data[] | {id, name: .id, compat: {supportsUsageInStreaming: true}}]}}}}' \
  | openclaw config patch --stdin

  Run every write with `--dry-run` first and show me the diff before applying it.

  6. Verify with `openclaw models list --provider flexinference`, then run `openclaw security audit`.

  Rules that matter, do not deviate:
  - Never pass my key as an argument to an `openclaw` command, and never write it into a config file. `openclaw onboard --custom-api-key` does both, which is why step 4 uses a reference instead.
  - Step 5 is the one place the key expands, into curl's `-H` argument, where a same-user process can read it. That is a deliberate trade for a single catalog read. Do not extend it to any other command.
  - The provider id must be `flexinference` in every command. If an earlier setup derived `custom-api-flexinference-com` from the host, tell me, and use that id consistently instead of creating a second provider.
  - `api` must be `openai-completions`. That is the only adapter FlexInference's Chat Completions surface works with here.
  - The base URL must end in `/v1`.
  - You MUST list models explicitly. OpenClaw only lets its own built-in provider ids omit `models`, and it will never call `GET /v1/models` for a provider defined in config. Model discovery is a plugin capability and does not apply here.
  - Every model row needs `compat: { supportsUsageInStreaming: true }`. OpenClaw makes streaming usage opt-in for third-party endpoints, and without it every streamed turn reports zero tokens and no cost.
  - Leave `"mode": "merge"` alone so my existing providers survive.
  - Step 4 resolves the reference at write time, so it fails if I have not exported the variable yet. That failure is expected, not a reason to fall back to a literal key.
  - FlexInference's catalog publishes no context window or token ceiling, so generated rows carry neither. Do not invent values; leave them out unless I give you numbers.

  Report what you changed and which config file you wrote.
  ```
</Accordion>

## 入驻自定义提供商

1. 启动引导式设置。

   ```bash theme={null}
   openclaw onboard
   ```

2. 当询问身份验证时，选择自定义提供商选项。即 `custom-api-key`。

3. 输入路由器作为基础 URL，包括 `/v1` 后缀。

   ```text theme={null}
   https://api.flexinference.com/v1
   ```

4. 粘贴您的代理密钥。

5. 将兼容模式保留为 `openai`。这是我们的 Chat Completions 接口。

6. 输入我们运行的模型 ID，例如 `gpt-5.6-sol`。

提示词绝不会将您的密钥放在命令行上，这就是此处显示此路径的原因。

`openclaw onboard --non-interactive` 也存在，但其 `custom-api-key` 身份验证模式会从 `--custom-api-key` 读取凭据，因此密钥会出现在您的 shell 历史记录和进程参数中。请改用配置命令和密钥引用来编写设置脚本，这样可以在不暴露密钥的情况下达到相同的效果。

无论您选择哪种方式，请自行设置提供商 ID：

```bash theme={null}
openclaw config set models.providers.flexinference --merge --strict-json \
  '{"baseUrl":"https://api.flexinference.com/v1","api":"openai-completions","models":[{"id":"gpt-5.6-sol","name":"GPT-5.6 Sol","compat":{"supportsUsageInStreaming":true}}]}'
```

如果不手动设置，OpenClaw 会从主机派生 ID，最终得到 `custom-api-flexinference-com`，那么本页上的所有后续命令都需要使用该名称。

写入操作包含一个模型行，因为这是必需的。OpenClaw 会拒绝未声明 `models` 的第三方提供商，因此仅包含 `baseUrl` 的写入会因架构验证失败。请在下一节中替换整个行。

兼容模式映射到 `api`。`openai` 会写入 `openai-completions`，这是我们的 Chat Completions 端点所支持的。其他选项是 `openai-responses` 和 `anthropic`。

## 配置文件

入驻过程会将配置写入 `~/.openclaw/openclaw.json` 的 `models.providers` 下。使用 `openclaw config file` 打印 OpenClaw 正在使用的路径。

```json theme={null}
{
  "models": {
    "mode": "merge",
    "providers": {
      "flexinference": {
        "baseUrl": "https://api.flexinference.com/v1",
        "api": "openai-completions",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "FLEXINFERENCE_API_KEY"
        },
        "models": [
          {
            "id": "gpt-5.6-sol",
            "name": "GPT-5.6 Sol",
            "contextWindow": 400000,
            "maxTokens": 128000,
            "input": ["text", "image"],
            "compat": { "supportsUsageInStreaming": true }
          }
        ]
      }
    }
  }
}
```

`"mode": "merge"` 会保留您内置的提供商，并在其旁边添加此提供商。

`api` 必须是 `openai-completions`。入驻时的 `openai` 兼容模式正是写入此值。

`apiKey` 也可以接受纯字符串，这也是入驻时写入的内容。此处显示的引用将密钥保留在文件之外。请参阅将密钥保留在配置文件之外。

**请自行列出您的模型。** 只有 OpenClaw 的内置提供商 ID 可以省略 `models`。第三方 ID 必须同时声明 `baseUrl` 和 `models`，因此请为您希望在选择器中显示的每个模型添加一行。

**设置 `compat.supportsUsageInStreaming`。** OpenClaw 允许第三方端点选择启用流式传输使用情况，因为某些服务器会拒绝它。如果没有此标志，我们将永远不会收到使用情况帧的请求，因此每次流式传输的回合都会报告零令牌和零成本。

## 从我们的目录填充模型列表

OpenClaw 不会为您在配置中定义的提供商调用 `GET /v1/models`。模型发现是一种插件功能，只有捆绑的具有此功能的插件才会使用它。配置定义的提供商只读取其 `models` 数组，不读取其他任何内容。

请改为从我们的目录生成该数组，并用一个命令写入。

```bash theme={null}
export FLEXINFERENCE_API_KEY=<your agent key>

curl -s https://api.flexinference.com/v1/models \
  -H "Authorization: Bearer $FLEXINFERENCE_API_KEY" \
| jq '{models:{providers:{flexinference:{models:
    [.data[] | {id, name: .id, compat: {supportsUsageInStreaming: true}}]}}}}' \
| openclaw config patch --stdin
```

`config patch` 会合并对象并替换数组，因此这会交换模型列表，并保持 `baseUrl` 和 `apiKey` 不变。添加 `--dry-run` 可以先查看写入内容。

通过筛选目录自身的标志，只保留那些参与更便宜层级竞争的模型。

```bash theme={null}
jq '[.data[] | select(.flexinference.flex_race) | {id, name: .id}]'
```

我们的目录不发布上下文窗口和令牌上限，因此以这种方式生成的行不包含这些信息。如果 OpenClaw 的默认值不适合模型，请自行添加 `contextWindow` 和 `maxTokens`。

每当我们的目录发生变化时，请重新运行此命令。检查结果：

```bash theme={null}
openclaw models list --provider flexinference
```

## 全局配置和配置文件

OpenClaw 为每个配置文件保留一个配置，而不是每个文件夹一个。工作目录绝不会改变它读取的文件。

| 范围 | 配置路径                        | 如何选择                   |
| -- | --------------------------- | ---------------------- |
| 默认 | `~/.openclaw/openclaw.json` | 默认                     |
| 命名 | `~/.openclaw-<name>/`       | `--profile <name>`     |
| 开发 | `~/.openclaw-dev/`          | `--dev`                |
| 显式 | 任何路径                        | `OPENCLAW_CONFIG_PATH` |

使用命名配置文件来尝试 FlexInference，而无需更改您常用的设置。

```bash theme={null}
openclaw --profile flex onboard
```

配置文件不仅隔离配置，还隔离状态，因此其网关端口和工作区也是独立的。

## 将密钥保留在配置文件之外

入驻过程会将密钥以纯文本形式写入 `openclaw.json`。请改为将 `apiKey` 设置为密钥引用，这样配置会存储变量的名称而不是其值。

1. 在您将运行这些命令的 shell 中导出密钥。

   ```bash theme={null}
   export FLEXINFERENCE_API_KEY=<your agent key>
   ```

2. 声明一个环境变量密钥提供商并允许该变量。

   ```bash theme={null}
   openclaw config set secrets.providers.default \
     --provider-source env --provider-allowlist FLEXINFERENCE_API_KEY
   ```

3. 将提供商的 `apiKey` 指向它。

   ```bash theme={null}
   openclaw config set models.providers.flexinference.apiKey \
     --ref-provider default --ref-source env --ref-id FLEXINFERENCE_API_KEY
   ```

此时，配置将包含 `{"source": "env", "provider": "default", "id": "FLEXINFERENCE_API_KEY"}`，不含任何密钥。密钥也永远不会到达命令行，因为步骤 3 只传递变量的名称。

OpenClaw 在您运行步骤 3 时解析引用，因此请先导出变量。缺少或为空的变量会导致写入失败并出现 `SecretRefResolutionError`，而不是存储损坏的内容。添加 `--dry-run` 可以在不写入的情况下进行检查。

使用内置审计功能检查暴露了哪些内容。

```bash theme={null}
openclaw security audit
```

## 确认密钥已应用

每个响应都附带 `x-flexinference-defaults-applied`。OpenClaw 不显示响应头，因此请改为在仪表板的**日志**下查看请求。

## 故障排除

**模型选择器不完整，或缺少某个模型。** 配置定义的提供商从不调用 `GET /v1/models`，因此它只显示您写入的行。请从我们的目录重新生成列表。

**回合报告零令牌和零成本。** OpenClaw 没有向我们请求流式传输使用情况，因此我们没有发送使用情况帧。请在每个模型行上将 `compat.supportsUsageInStreaming` 设置为 `true`。

**模型 ID 被拒绝。** 您手动写入的行可能与我们运行的行不一致，因为 `id` 会按原样发送。请从我们的目录重新生成列表，而不是编辑 ID。

**配置更改未生效。** 网关保留了旧配置。请重启它，并确认您编辑的是 `openclaw config file` 打印的文件。

有关我们返回的所有拒绝信息，请参阅[错误](/zh/errors)；有关非 OpenClaw 特有的问题，请参阅[代理密钥](/zh/agent-keys)。