> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/16_claude_ecosystem/16.3_other_ecosystems.md).

# 16.3 OpenAI 与本地模型集成

OpenClaw 不绑定单一 AI 供应商。除 Claude 外，OpenAI 与以 Ollama 为代表的本地模型也是生产环境中常见的接入选择。本节介绍这两类生态的接入方式和典型配置，以及与 Claude 组合使用的混合策略。

## 16.3.1 OpenAI 模型接入

OpenClaw 通过不同 provider path、auth profile 与 runtime 接入 OpenAI 相关生态。OpenAI agent 模型引用使用 `openai/*`；ChatGPT/Codex 订阅 OAuth 由 Codex/OpenAI auth profile 与运行时表达，历史 `openai-codex/*` 模型引用应通过 `openclaw doctor --fix` 迁移。不要把历史兼容的 `codex/*`、OpenAI Platform API 路径和 Codex 订阅路径混写。当前模型版本、别名和价格变化很快；长期配置应以 `openclaw models list`、`models status --probe`、OpenAI 官方 Models/Pricing 页和目标 OpenClaw 版本为准。

### 基础配置

```jsonc
{
  // API Key 走 OPENAI_API_KEY、onboarding 或 auth profiles。
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-5.5",
        fallbacks: ["anthropic/claude-sonnet-4-6"],
      },
    },
  },
}
```

### 使用 Azure OpenAI

企业用户通常通过 Azure OpenAI Service 调用 GPT 模型。当前 OpenClaw 的 `models.providers.openai.baseUrl` Azure resource 形态只适用于图像生成路径；聊天 / Responses 使用 `azure-openai-responses/<deployment>` 或 onboarding 生成的专用 Azure provider 配置。不要把 API Key 模式下的 `openai/*` 片段原样照抄到 Azure 聊天环境。

```jsonc
{
  models: {
    providers: {
      "azure-openai-responses": {
        apiKey: "${AZURE_OPENAI_API_KEY}",
        baseUrl: "https://your-resource.openai.azure.com/openai/v1",
        api: "azure-openai-responses",
        models: [{ id: "<deployment>", name: "Azure GPT deployment" }],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "azure-openai-responses/<deployment>" },
    },
  },
}
```

### OpenAI 接入要点

| 能力             | 说明                                                                               |
| -------------- | -------------------------------------------------------------------------------- |
| **工具调用**       | Function Calling 与 OpenClaw 工具系统兼容，格式自动转换                                        |
| **结构化输出**      | `response_format: { type: "json_schema" }` 可配合 OpenClaw 输出解析                     |
| **o 系列推理模型**   | `openai/o3` 等推理模型对提示层级更敏感；稳定角色、策略与边界约束优先放在 developer message，任务细节留在 user message |
| **Embeddings** | OpenAI Embeddings API 可通过 MCP 服务器或自定义工具接入                                        |

> **注意**：OpenAI 模型版本与定价以 [OpenAI Models](https://platform.openai.com/docs/models) 和 [OpenAI Pricing](https://openai.com/api/pricing/) 为准。本书示例中的模型标识符仅反映撰写时的版本。

### OpenAI Agent 栈的覆盖边界

OpenAI 官方 agent 栈通常涉及 Responses API、Agents SDK、内置工具/函数调用、tracing 与 guardrails 等组件。本节只讲 OpenClaw 的 OpenAI provider 接入和混合模型路由，不等同于完整介绍 OpenAI 原生 agent 平台；需要直接构建 OpenAI 原生 agent 时，应回到 OpenAI Agents SDK 与 Responses API 文档确认当前接口。

## 16.3.2 本地模型：Ollama 接入

Ollama 是主流的本地模型运行平台，支持 Llama、Mistral、Qwen、DeepSeek 等开源模型。本地部署的优势是数据不出本地网络、无 API 调用费用，适合对隐私敏感或网络受限的场景。

### 接入原理

OpenClaw 当前推荐先通过 `openclaw onboard` / 模型发现路径识别 Ollama，再按需补充手工 provider 配置。不要把 OpenClaw 指向 `http://localhost:11434/v1` 这样的 OpenAI-compatible 路径；OpenClaw 官方文档明确警告，这会破坏 OpenClaw 的原生工具调用适配，让模型把工具 JSON 当普通文本输出。只有在自定义 endpoint、离线发现失败或需要固定私有模型目录时，才手工维护下面这种原生 `baseUrl` provider：

```jsonc
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://localhost:11434",
        apiKey: "ollama-local", // 本地/LAN Ollama 通常不需要真实 bearer token；这里只是本地标记
        api: "ollama",
        models: [
          {
            id: "gpt-oss:20b",
            name: "GPT-OSS 20B",
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
      },
    },
  },
}
```

这里的 `contextWindow` 是 OpenClaw 侧用于提示词预算和压缩决策的模型容量提示，不等于 Ollama 服务端一定为本次运行分配了 128K runtime context。原生 Ollama 默认 runtime context 会受 VRAM、应用设置、`OLLAMA_CONTEXT_LENGTH`、Modelfile 或 `params.num_ctx` 影响；需要长上下文时应显式配置并用实际 prompt 测试确认。

### 启动 Ollama 并拉取模型

```bash
# 安装 Ollama（macOS）
brew install ollama

# 启动服务
ollama serve

# 拉取模型（以 GPT-OSS 20B 为例）
ollama pull gpt-oss:20b

# 验证服务
curl http://localhost:11434/api/tags
```

### 本地模型选型参考

| 模型                  | 参数量  | 适用场景      | 显存需求                                        |
| ------------------- | ---- | --------- | ------------------------------------------- |
| `llama3.1:8b`       | 8B 级 | 快速问答、通用助手 | \~6GB                                       |
| `llama3.3:70b`      | 70B  | 高质量通用推理   | 取决于量化，通常需要高显存                               |
| `gpt-oss:20b`       | 20B  | 通用推理、工具调用 | \~16GB+（模型文件约 14GB；实际以 `ollama show` 与量化为准） |
| `qwen2.5-coder:32b` | 32B  | 代码生成、代码审查 | \~20GB                                      |
| `deepseek-r1:32b`   | 32B  | 复杂推理、代码生成 | \~20GB                                      |

> 实际显存占用取决于量化精度（Q4/Q8 等），以 `ollama show <model>` 输出为准。

## 16.3.3 多生态混合策略

在实际生产中，不同任务对模型能力和成本的要求不同，混合使用多生态模型可以兼顾质量与效率。

### 典型混合配置

```jsonc
{
  agents: {
    list: [
      {
        id: "chat",
        // 通用对话：用本地模型降低成本
        model: {
          primary: "ollama/gpt-oss:20b",
          fallbacks: ["openai/gpt-5.4"],
        },
      },
      {
        id: "dev_assistant",
        // 复杂推理与代码生成：用 Claude Sonnet
        model: {
          primary: "anthropic/claude-sonnet-4-6",
          fallbacks: ["openai/gpt-5.4"],
        },
      },
      {
        id: "classifier",
        // 高并发轻量任务：替换为当前目录中实际可用的低延迟模型
        model: {
          primary: "<provider/low-latency-model>",
        },
      },
    ],
  },
}
```

### 混合策略选型参考

| 策略   | 主模型                           | Fallback                      | 适用场景     |
| ---- | ----------------------------- | ----------------------------- | -------- |
| 隐私优先 | 本地（Ollama）                    | `anthropic/claude-sonnet-4-6` | 敏感数据不出本地 |
| 成本优先 | 本地（Ollama）                    | 当前目录中的低延迟模型                   | 高并发、低复杂度 |
| 质量优先 | `anthropic/claude-sonnet-4-6` | `openai/gpt-5.5`              | 推理质量要求高  |
| 离线兜底 | `anthropic/claude-sonnet-4-6` | 本地（Ollama）                    | 网络不稳定环境  |

Fallback 链路的触发条件和行为详见 [4.4 故障转移基础](/openclaw_guide/di-yi-bu-fen-ji-chu-ru-men/04_config_models/4.4_failover.md)。

## 16.3.4 统一管理多生态模型

无论接入哪家供应商，OpenClaw 的模型管理界面提供统一视图。可通过以下命令查看当前所有已配置模型的状态：

```bash
openclaw models status --probe
```

建议在混合部署中：

1. 为每个供应商配置独立的 `apiKey` 环境变量，避免密钥混用。
2. 对本地模型定期运行探针，确认 Ollama 服务存活。
3. 将各供应商的配额告警阈值统一纳入监控，防止某一路径静默失效。