如何在 OpenClaw 中使用 Omniside：一个 API Key 接入所有模型

OpenClaw 是近期在开发者社区中大受欢迎的开源个人 AI 助手。它运行在你的本地机器上，可连接 Telegram、Discord、WhatsApp 等消息应用，处理从编程任务到邮件管理的一切事务——由 LLM 驱动。

麻烦在哪里？OpenClaw 至少需要配置一个 LLM 提供商才能工作。默认情况下，这意味着你要分别注册 Anthropic、OpenAI、Google 等服务商，每家都有独立的 API Key 和账单账户。

有了 Omniside，这些都不需要了。一个 API Key，一个账单账户，通过统一的 OpenAI 兼容端点访问 Claude、GPT-4o、Gemini、Grok、DeepSeek 等所有主流模型。

本指南覆盖所有主流平台的安装与配置：macOS、Ubuntu、Debian、CentOS 和 Windows。

OpenClaw 界面

前置条件

你需要准备：

一台运行 OpenClaw 的机器 — Mac、Linux 或 Windows（推荐使用 WSL）
Node.js 22+ — 没有的话安装脚本会自动处理
Omniside API Key — 在这里注册（约 30 秒）

第一步：安装 OpenClaw

macOS

推荐方式：

curl -fsSL https://openclaw.ai/install.sh | bash

或通过 Homebrew：

brew install openclaw

或通过 npm：

npm install -g openclaw

也可下载桌面客户端 .dmg 安装包，见 GitHub Releases。

Ubuntu / Debian

curl -fsSL https://openclaw.ai/install.sh | bash

或通过 npm（需要 Node.js 22+）：

# 如需安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 OpenClaw
npm install -g openclaw

CentOS / RHEL / Fedora

curl -fsSL https://openclaw.ai/install.sh | bash

或通过 npm：

# 如需安装 Node.js
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs    # CentOS/RHEL
# 或：sudo dnf install -y nodejs  # Fedora

npm install -g openclaw

Windows

强烈推荐使用 WSL 以获得最佳体验：

# 在 PowerShell（管理员）中安装 WSL
wsl --install

# 进入 WSL 后运行：
curl -fsSL https://openclaw.ai/install.sh | bash

也支持 Windows 原生安装：

npm install -g openclaw

Docker

如果偏好容器化部署：

docker run -it --rm ghcr.io/openclaw/openclaw

验证安装

openclaw --version

第二步：获取 Omniside API Key

前往 platform.omniside.ai
注册或登录
进入 API Keys 页面
点击 Create API Key
复制 Key（以 sk- 开头）

第三步：将 Omniside 配置为自定义提供商

OpenClaw 使用 openclaw.json（或 openclaw.json5）配置文件，存放路径：

全局：~/.config/openclaw/openclaw.json（Linux/macOS）或 %USERPROFILE%\.config\openclaw\openclaw.json（Windows）
旧版路径：~/.openclaw/openclaw.json
项目级：项目根目录下的 openclaw.json

我们做全局配置，先创建目录：

mkdir -p ~/.config/openclaw

配置结构说明

OpenClaw 自定义提供商需要同时配置两处：

models.providers 中的提供商定义 — 告诉 OpenClaw 向哪里发请求
agents.defaults.models 中的模型白名单 — 告诉 OpenClaw 哪些模型可用
mode: "merge" — 关键字段，缺少它自定义提供商无法与内置提供商共存
api: "openai-completions" — 所有兼容 OpenAI 的端点必填

方案 A：完整版 — 所有模型 + 自动故障转移

最佳体验。以 Claude Sonnet 4.5 为主模型，自动降级至 GPT-4o、Gemini、DeepSeek。

{
  "models": {
    "mode": "merge",
    "providers": {
      "omniside": {
        "baseUrl": "https://api.omniside.ai/v1",
        "apiKey": "sk-your-omniside-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250514",
            "name": "Claude Sonnet 4.5",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 16384
          },
          {
            "id": "gemini-2.5-pro",
            "name": "Gemini 2.5 Pro",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65536
          },
          {
            "id": "deepseek-chat",
            "name": "DeepSeek V3",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 64000,
            "maxTokens": 8192
          },
          {
            "id": "grok-3",
            "name": "Grok 3",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "omniside/claude-sonnet-4-5-20250514",
        "fallbacks": [
          "omniside/gpt-4o",
          "omniside/gemini-2.5-pro",
          "omniside/deepseek-chat"
        ]
      },
      "models": {
        "omniside/claude-sonnet-4-5-20250514": { "alias": "sonnet" },
        "omniside/gpt-4o": { "alias": "gpt4o" },
        "omniside/gemini-2.5-pro": { "alias": "gemini" },
        "omniside/deepseek-chat": { "alias": "deepseek" },
        "omniside/grok-3": { "alias": "grok" }
      }
    }
  }
}

方案 B：智能版 — 最佳性价比（推荐）

Claude Sonnet 4.5 为主，GPT-4o 兜底。适合大多数用户。

{
  "models": {
    "mode": "merge",
    "providers": {
      "omniside": {
        "baseUrl": "https://api.omniside.ai/v1",
        "apiKey": "sk-your-omniside-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250514",
            "name": "Claude Sonnet 4.5",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 16384
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "omniside/claude-sonnet-4-5-20250514",
        "fallbacks": ["omniside/gpt-4o"]
      },
      "models": {
        "omniside/claude-sonnet-4-5-20250514": { "alias": "sonnet" },
        "omniside/gpt-4o": { "alias": "gpt4o" }
      }
    }
  }
}

方案 C：经济版 — 最低成本

DeepSeek V3 为主，适合日常任务、成本敏感场景。

{
  "models": {
    "mode": "merge",
    "providers": {
      "omniside": {
        "baseUrl": "https://api.omniside.ai/v1",
        "apiKey": "sk-your-omniside-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek V3",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 64000,
            "maxTokens": 8192
          },
          {
            "id": "gpt-4o-mini",
            "name": "GPT-4o Mini",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 16384
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "omniside/deepseek-chat",
        "fallbacks": ["omniside/gpt-4o-mini"]
      },
      "models": {
        "omniside/deepseek-chat": { "alias": "deepseek" },
        "omniside/gpt-4o-mini": { "alias": "gpt4omini" }
      }
    }
  }
}

保存配置

Linux / macOS 一行命令（以方案 B 为例，记得替换 Key）：

cat > ~/.config/openclaw/openclaw.json << 'EOF'
{
  "models": {
    "mode": "merge",
    "providers": {
      "omniside": {
        "baseUrl": "https://api.omniside.ai/v1",
        "apiKey": "sk-your-omniside-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-sonnet-4-5-20250514",
            "name": "Claude Sonnet 4.5",
            "reasoning": true,
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192
          },
          {
            "id": "gpt-4o",
            "name": "GPT-4o",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 16384
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "omniside/claude-sonnet-4-5-20250514",
        "fallbacks": ["omniside/gpt-4o"]
      },
      "models": {
        "omniside/claude-sonnet-4-5-20250514": { "alias": "sonnet" },
        "omniside/gpt-4o": { "alias": "gpt4o" }
      }
    }
  }
}
EOF

Windows（PowerShell）：

$configDir = "$env:USERPROFILE\.config\openclaw"
New-Item -ItemType Directory -Force -Path $configDir | Out-Null
notepad "$configDir\openclaw.json"
# 粘贴你选择的配置并保存

重要：将 sk-your-omniside-key 替换为你的真实 Key。也可以用环境变量写法："apiKey": "${OMNISIDE_API_KEY}"，在 shell 配置文件中 export 即可。

第四步：运行引导配置

启动 OpenClaw 引导流程：

openclaw onboard

在提示选择模型时选择 “Skip for now”——你的 Omniside 模型已在 JSON 文件中配置好了。引导向导会带你完成连接消息渠道（Telegram、Discord、WhatsApp 等）的步骤。

第五步：验证配置

引导完成后，确认模型是否正常加载：

openclaw models list

你应该能看到带 omniside/ 前缀的模型列表。切换模型：

openclaw models set omniside/gpt-4o

或重启网关应用配置变更：

openclaw gateway restart

使用环境变量管理 API Key

不想把 Key 写进配置文件，可以改用环境变量引用：

"apiKey": "${OMNISIDE_API_KEY}"

在 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.profile）中添加：

export OMNISIDE_API_KEY="sk-your-key-here"

这样 Key 不会出现在可能被提交到 Git 的配置文件里。

各平台注意事项

Ubuntu / Debian

如果 npm install -g 报权限错误：

使用 sudo npm install -g openclaw，或
设置 npm 前缀：npm config set prefix ~/.npm-global，将 ~/.npm-global/bin 加入 PATH

CentOS / RHEL

CentOS 7 可能需要更新 gcc 和 glibc 才能运行 Node.js 22，建议使用 Rocky Linux 9 或 CentOS Stream 9。

macOS

首次运行可能触发 Gatekeeper 拦截。前往系统设置 → 隐私与安全性 → 仍要打开。

Windows

强烈推荐 WSL。如需原生 Windows：

配置路径：%USERPROFILE%\.config\openclaw\openclaw.json
使用 Windows Terminal 获得最佳 TUI 体验
文件监听等部分功能在 WSL 下表现更好

Docker

容器化部署时，通过环境变量传入 API Key：

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    environment:
      - OMNISIDE_API_KEY=sk-your-key-here
    volumes:
      - ./openclaw.json:/root/.config/openclaw/openclaw.json

问题排查

”No API provider registered for api: undefined”

提供商配置中缺少 "api": "openai-completions" 字段，这是最常见的错误。

“Config validation failed: baseUrl expected string”

设置了 apiKey 但忘了 baseUrl。自定义提供商两者都必须填写：

"baseUrl": "https://api.omniside.ai/v1",
"apiKey": "sk-your-key",
"api": "openai-completions"

模型未出现在 `openclaw models list`

检查：

models 块中是否有 "mode": "merge"
模型是否同时出现在 models.providers.omniside.models 和 agents.defaults.models 中
是否重启了网关：openclaw gateway restart

401 / 403 认证错误

验证你的 API Key 是否正确，直接测试：

curl https://api.omniside.ai/v1/models \
  -H "Authorization: Bearer sk-your-key"

baseUrl 必须以 /v1 结尾

确保 URL 是 https://api.omniside.ai/v1，不能是 /v1/chat/completions。

为什么选择 Omniside 搭配 OpenClaw？

不用 Omniside 时，配置多个模型意味着分别注册 Anthropic、OpenAI、Google、xAI——四次注册、四个 API Key、四个账单账户。

有了 Omniside，你只需在配置文件中添加一个提供商块，即可访问所有主流模型。用 openclaw models set 一条命令在 Claude、GPT、Gemini 之间切换——无需重新配置。

查看完整模型列表：platform.omniside.ai/models

前往 platform.omniside.ai 获取 API Key，开始使用。

前置条件

第一步：安装 OpenClaw

macOS

Ubuntu / Debian

CentOS / RHEL / Fedora

Windows

Docker

验证安装

第二步：获取 Omniside API Key

第三步：将 Omniside 配置为自定义提供商

配置结构说明

方案 A：完整版 — 所有模型 + 自动故障转移

方案 B：智能版 — 最佳性价比（推荐）

方案 C：经济版 — 最低成本

保存配置

第四步：运行引导配置

第五步：验证配置

使用环境变量管理 API Key

各平台注意事项

Ubuntu / Debian

CentOS / RHEL

macOS

Windows

Docker

问题排查

”No API provider registered for api: undefined”

“Config validation failed: baseUrl expected string”

模型未出现在 openclaw models list

401 / 403 认证错误

baseUrl 必须以 /v1 结尾

为什么选择 Omniside 搭配 OpenClaw？

模型未出现在 `openclaw models list`