# OpenClaw 接入 OfoxAI 配置指南

Source: https://ofox.io/zh/docs/integrations/openclaw

[OpenClaw](https://openclaw.ai) 是一款开源的本地 AI 助手，通过 WhatsApp、Telegram、Slack 等消息应用与你交互，能执行实际操作 — 管理邮件、日历、航班值机、浏览网页等。它完全在本地运行，数据不离开你的设备。

> **使用 Ofox Desktop 更快完成配置。** 在 Apple 芯片 Mac 上，Desktop 可以检测此工具、备份现有配置，并应用 Ofox API Key 和兼容模型。[打开 Ofox Desktop](https://ofox.io/zh/desktop)。

## 为什么搭配 OfoxAI？

- **100+ 模型统一调用** — 一个 API Key 访问 Claude、GPT、Gemini、Qwen、豆包等所有主流模型
- **灵活的 Agent 策略** — 不同 Agent 分配不同模型，主力用 Sonnet、推理用 Opus、轻量用 Haiku
- **99.9% SLA** — 多节点冗余，自动故障切换
- **成本可控** — 统一计费面板，实时监控 Token 消耗

OpenClaw 作为 Agentic AI 助手，单次任务的 Token 消耗较大（通常 10K-100K+ tokens）。建议根据任务复杂度选择模型，避免不必要的成本。本文提供三种配置方案供参考。

## 安装

```bash filename="macOS / Linux"
curl -sSL https://openclaw.ai/install.sh | bash
```

```powershell filename="Windows (PowerShell)"
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1)))
```

## 快速开始

### 1. 获取 API Key

前往 [OfoxAI 控制台](https://app.ofox.io) 创建 API Key。

### 2. 运行配置向导

OpenClaw 提供交互式向导，输入以下命令即可快速完成配置：

```bash
openclaw onboard
```

在向导中选择 **Custom Provider**，填入以下信息：

| 配置项 | 值 |
|--------|-----|
| **Provider Type** | `anthropic-messages` |
| **Base URL** | `https://api.ofox.io/anthropic` |
| **API Key** | 你的 OfoxAI API Key |
| **Model** | `anthropic/claude-sonnet-5.5` |

### 3. 启动验证

```bash
openclaw start
```

向 OpenClaw 发送一条消息测试连通性。如果收到正常回复，配置成功。

向导会自动生成 `openclaw.json` 配置文件。如果你需要更细粒度的控制，请参考下方的完整配置。

## 完整配置

OpenClaw 通过 `~/.openclaw/openclaw.json` 管理所有配置（支持 JSON5 格式，可写注释）。

### Provider 配置

Provider 定义在 `models.providers` 下，每个 Provider 需要指定 API 协议类型、地址和密钥：

```json filename="~/.openclaw/openclaw.json"
{
  "models": {
    "providers": {
      "ofoxai-anthropic": {
        "baseUrl": "https://api.ofox.io/anthropic",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "anthropic-messages",
        "models": []
      },
      "ofoxai-openai": {
        "baseUrl": "https://api.ofox.io/v1",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "openai-responses",
        "models": []
      },
      "ofoxai-gemini": {
        "baseUrl": "https://api.ofox.io/gemini",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "google-generative-ai",
        "models": []
      }
    }
  }
}
```

`apiKey` 支持 `${ENV_VAR}` 语法引用环境变量，避免明文写入配置文件。三种协议对应不同模型系列：Claude 使用 `ofoxai-anthropic`（`anthropic-messages`），OpenAI 使用 `ofoxai-openai`（`openai-responses`），Gemini 使用 `ofoxai-gemini`（`google-generative-ai`），其余模型可通过 `ofoxai-openai` 接入。

### Models 配置

模型定义在对应 Provider 的 `models` 数组中。我们提供三套方案，根据你的需求选择：

**最强配置**

**全 Claude 阵容** — 追求最强能力，适合高要求场景。

```json filename="openclaw.json — models.providers"
{
  "models": {
    "providers": {
      "ofoxai-anthropic": {
        "baseUrl": "https://api.ofox.io/anthropic",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "anthropic/claude-sonnet-5.5",
            "name": "Claude Sonnet 5.5",
            "input": ["text", "image", "file"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          },
          {
            "id": "anthropic/claude-opus-5.5",
            "name": "Claude Opus 5.5",
            "reasoning": true,
            "input": ["text", "image", "file"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          },
          {
            "id": "anthropic/claude-haiku-5.5",
            "name": "Claude Haiku 5.5",
            "input": ["text", "image", "file"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          }
        ]
      }
    }
  }
}
```

| 模型 | 角色定位 | 适用场景 |
|------|----------|----------|
| `anthropic/claude-sonnet-5.5` | 主力模型 | 日常对话、任务执行、代码生成 |
| `anthropic/claude-opus-5.5` | 深度推理 | 复杂分析、长链推理、研究任务 |
| `anthropic/claude-haiku-5.5` | 快速响应 | 简单查询、快速回复、轻量任务 |

**平衡组合**

**OpenAI Codex 组合** — 代码能力突出，通用任务均衡。

```json filename="openclaw.json — models.providers"
{
  "models": {
    "providers": {
      "ofoxai-openai": {
        "baseUrl": "https://api.ofox.io/v1",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "openai/gpt-5.3-codex",
            "name": "GPT 5.3 Codex",
            "reasoning": true,
            "input": ["text", "image", "audio", "file"],
            "contextWindow": 512000,
            "maxTokens": 128000
          },
          {
            "id": "openai/gpt-5.1-codex-mini",
            "name": "GPT 5.1 Codex Mini",
            "input": ["text", "image", "audio", "file"],
            "contextWindow": 256000,
            "maxTokens": 65536
          }
        ]
      }
    }
  }
}
```

| 模型 | 角色定位 | 适用场景 |
|------|----------|----------|
| `openai/gpt-5.3-codex` | 主力 + 推理 | 日常对话、复杂任务、代码重构 |
| `openai/gpt-5.1-codex-mini` | 快速响应 | 轻量任务、代码补全、快速问答 |

OpenAI 模型通过 `ofoxai-openai` Provider 接入，使用 `openai-responses` 协议。

**最具性价比**

**国产模型性价比之选** — Token 单价低，适合高频日常使用。

```json filename="openclaw.json — models.providers"
{
  "models": {
    "providers": {
      "ofoxai-openai": {
        "baseUrl": "https://api.ofox.io/v1",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "qwen/qwen3.7-plus",
            "name": "Qwen3.7 Plus",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 64000
          },
          {
            "id": "volcengine/doubao-seed-2.0-code",
            "name": "豆包 Seed 2.0 Code",
            "input": ["text", "image"],
            "contextWindow": 256000,
            "maxTokens": 128000
          }
        ]
      }
    }
  }
}
```

| 模型 | 角色定位 | 适用场景 |
|------|----------|----------|
| `qwen/qwen3.7-plus` | 主力 + 推理 | 日常对话、通用任务、中文优化 |
| `volcengine/doubao-seed-2.0-code` | 代码 + 快速 | 代码生成、调试、快速回复 |

### Agents 配置

OpenClaw 通过 `agents.defaults` 设置全局默认，通过 `agents.list` 数组定义不同 Agent，每个 Agent 可覆盖默认配置：

```json filename="openclaw.json — agents 部分"
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ofoxai-anthropic/anthropic/claude-sonnet-5.5",
        "fallbacks": ["ofoxai-anthropic/anthropic/claude-haiku-5.5"]
      },
      "models": {
        "ofoxai-anthropic/anthropic/claude-opus-5.5": { "alias": "opus" },
        "ofoxai-anthropic/anthropic/claude-sonnet-5.5": { "alias": "sonnet" },
        "ofoxai-anthropic/anthropic/claude-haiku-5.5": { "alias": "haiku" }
      },
      "thinkingDefault": "low",
      "timeoutSeconds": 600,
      "maxConcurrent": 3
    },
    "list": [
      {
        "id": "main",
        "default": true
      },
      {
        "id": "research",
        "model": {
          "primary": "ofoxai-anthropic/anthropic/claude-opus-5.5"
        }
      },
      {
        "id": "quick",
        "model": {
          "primary": "ofoxai-anthropic/anthropic/claude-haiku-5.5"
        }
      }
    ]
  }
}
```

| Agent | 模型 | 用途 |
|-------|------|------|
| **main** | `claude-sonnet-5.5`（继承 defaults） | 默认 Agent，日常所有任务 |
| **research** | `claude-opus-5.5` | 深度研究、复杂推理、长文分析 |
| **quick** | `claude-haiku-5.5` | 简单问答、快速响应、低成本 |

模型引用格式为 `provider名/model-id`（如 `ofoxai-anthropic/anthropic/claude-sonnet-5.5`）。`defaults` 中的 `models` 字段定义模型别名，可在对话中用 `/model opus` 快速切换。`list` 中的 Agent 会继承 `defaults` 的所有配置，只需覆盖需要变更的字段。

## 完整配置示例

以下是一份完整的 `openclaw.json`，整合了 Provider、Models 和 Agents 配置（最强配置方案）：

```json filename="~/.openclaw/openclaw.json"
{
  "models": {
    "providers": {
      "ofoxai-anthropic": {
        "baseUrl": "https://api.ofox.io/anthropic",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "anthropic/claude-sonnet-5.5",
            "name": "Claude Sonnet 5.5",
            "input": ["text", "image", "file"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          },
          {
            "id": "anthropic/claude-opus-5.5",
            "name": "Claude Opus 5.5",
            "reasoning": true,
            "input": ["text", "image", "file"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          },
          {
            "id": "anthropic/claude-haiku-5.5",
            "name": "Claude Haiku 5.5",
            "input": ["text", "image", "file"],
            "contextWindow": 1000000,
            "maxTokens": 128000
          }
        ]
      },
      "ofoxai-gemini": {
        "baseUrl": "https://api.ofox.io/gemini",
        "apiKey": "${OFOXAI_API_KEY}",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "models/google/gemini-3.8-flash",
            "name": "Gemini 3.8 Flash",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 64000
          },
          {
            "id": "models/google/gemini-3.1-pro-preview",
            "name": "Gemini 3.1 Pro",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 64000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ofoxai-anthropic/anthropic/claude-sonnet-5.5",
        "fallbacks": ["ofoxai-anthropic/anthropic/claude-haiku-5.5"]
      },
      "models": {
        "ofoxai-anthropic/anthropic/claude-opus-5.5": { "alias": "opus" },
        "ofoxai-anthropic/anthropic/claude-sonnet-5.5": { "alias": "sonnet" },
        "ofoxai-anthropic/anthropic/claude-haiku-5.5": { "alias": "haiku" }
      },
      "thinkingDefault": "low",
      "timeoutSeconds": 600,
      "maxConcurrent": 3
    },
    "list": [
      {
        "id": "main",
        "default": true
      },
      {
        "id": "research",
        "model": {
          "primary": "ofoxai-anthropic/anthropic/claude-opus-5.5"
        }
      },
      {
        "id": "quick",
        "model": {
          "primary": "ofoxai-anthropic/anthropic/claude-haiku-5.5"
        }
      }
    ]
  }
}
```

## 使用场景

配置完成后，通过消息应用向 OpenClaw 发送指令：

- **邮件管理** — "帮我整理今天未读的邮件，按优先级排序"
- **日程安排** — "明天下午 3 点安排一个团队会议"
- **信息检索** — "搜索最近关于 AI Agent 的技术文章，总结要点"
- **代码辅助** — "帮我 review 这段 Python 代码，检查安全问题"
- **工作流自动化** — "每天早上 9 点发送团队日报到 Slack #general 频道"

## 故障排除

**无法连接 OfoxAI**

确认 `baseUrl` 配置正确：
- Anthropic 协议：`https://api.ofox.io/anthropic`
- OpenAI-Response 协议：`https://api.ofox.io/v1`
- Gemini 协议：`https://api.ofox.io/gemini`

**模型不存在**

确认模型 ID 格式正确。在 `models.providers` 中定义模型时，`id` 使用 OfoxAI 返回的完整 ID（如 `anthropic/claude-sonnet-5.5`）。在 `agents` 中引用模型时需要加 Provider 名前缀：`ofoxai-anthropic/anthropic/claude-sonnet-5.5`。

**Token 消耗过高**

OpenClaw 单次任务消耗较大，建议：
1. 日常任务使用 `claude-haiku-5.5` 或性价比模型
2. 仅在复杂任务时切换到 `research` Agent（使用 `claude-opus-5.5`）
3. 在 [OfoxAI 控制台](https://app.ofox.io) 监控用量

**如何快速切换模型**

在对话中使用别名切换：`/model opus`、`/model sonnet`、`/model haiku`（需要在 `agents.defaults.models` 中配置别名）。