OpenClaw 接入说明

说明: OpenClaw 是一个开源、自托管的 AI 助手平台，适合希望把消息渠道、Agent 能力和数据控制权都掌握在自己手里的开发者使用。

如果你希望让 OpenClaw 通过 Nbility 访问模型，可以参考这份配置方法。

OpenClaw 是什么

它的核心特点包括：

• 可以连接飞书、Discord、Slack、Teams 等多个渠道
• 支持语音交互和画布式界面
• 采用自托管模式，数据和上下文保存在你自己的环境里
• 支持长期运行、定时任务、多 Agent 协作和工具调用

相关资料：

• 官网：https://openclaw.ai
• 文档：https://docs.openclaw.ai
• GitHub：https://github.com/openclaw/openclaw

前提条件

在开始之前，请先准备好：

• 已安装 OpenClaw
• 已拥有可用的 Nbility Token

Token 可以在 /console/token 获取。

安装方式

如果你还没装 OpenClaw，可以任选以下一种方法：

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

npm install -g openclaw@latest

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

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm run build
pnpm run openclaw onboard

说明: 使用 npm 或 git 方式时，通常需要 Node.js 22 及以上版本；一键安装脚本会帮你处理更多环境细节。

安装完成后，可以执行一次初始化向导：

openclaw onboard

配置文件位置

OpenClaw 默认使用 ~/.openclaw/openclaw.json 作为主配置文件。

常见路径如下：

• macOS: /Users/你的用户名/.openclaw/openclaw.json
• Linux: /home/你的用户名/.openclaw/openclaw.json
• Windows: C:\\Users\\你的用户名\\.openclaw\\openclaw.json

如果文件还不存在，可以先手动创建：

mkdir -p ~/.openclaw
touch ~/.openclaw/openclaw.json

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.openclaw"
New-Item -ItemType File -Force -Path "$env:USERPROFILE\.openclaw\openclaw.json"

提示: 如果你已经运行过 openclaw onboard，通常不需要重新创建文件，只要在现有配置上调整即可。

基本结构

配置一般会分成 models 和 agents 两块：

{
  "models": {
    "mode": "merge",
    "providers": {}
  },
  "agents": {
    "defaults": {}
  }
}

重点字段可以这样理解：

• models.providers：定义你的模型提供商、认证信息和模型列表
• models.mode：建议固定使用 "merge"，避免把内置配置整个替掉
• agents.defaults.model.primary：指定默认模型，格式通常是 provider/模型ID
• api：决定具体走哪种协议

配置 Claude 模型

如果你准备通过 Nbility 使用 Claude 系列，可参考如下配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "nbility-anthropic": {
        "baseUrl": "https://api.nbility.dev",
        "apiKey": "sk-你的NBility-Token",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nbility-anthropic/claude-opus-4-6"
      }
    }
  }
}

重要: 使用 Anthropic 协议时，baseUrl 只写 https://api.nbility.dev，不要带 /v1，否则容易出现路径重复。

配置 GPT 模型

如果你要接入 OpenAI 系列模型，建议使用 openai-responses：

{
  "models": {
    "mode": "merge",
    "providers": {
      "nbility-openai": {
        "baseUrl": "https://api.nbility.dev/v1",
        "apiKey": "sk-你的NBility-Token",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5",
            "name": "GPT-5",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nbility-openai/gpt-5"
      }
    }
  }
}

提示: OpenAI 协议与上面的 Claude 配置不同，这里需要保留 https://api.nbility.dev/v1。

同时接入 Claude 与 GPT

如果你想保留多组 provider，并设置回退模型，可以使用类似下面的结构：

{
  "models": {
    "mode": "merge",
    "providers": {
      "nbility-anthropic": {
        "baseUrl": "https://api.nbility.dev",
        "apiKey": "sk-你的NBility-Token",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false
          },
          {
            "id": "claude-sonnet-4-5-20250929",
            "name": "Claude Sonnet 4.5",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      },
      "nbility-openai": {
        "baseUrl": "https://api.nbility.dev/v1",
        "apiKey": "sk-你的NBility-Token",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5",
            "name": "GPT-5",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384,
            "reasoning": true
          },
          {
            "id": "gpt-5-codex",
            "name": "GPT-5 Codex",
            "input": ["text", "image"],
            "contextWindow": 200000,
            "maxTokens": 16384,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nbility-anthropic/claude-opus-4-6",
        "fallbacks": [
          "nbility-anthropic/claude-sonnet-4-5-20250929",
          "nbility-openai/gpt-5"
        ]
      }
    }
  }
}

如果你只是想切换默认模型，通常只需要改 model.primary 的值。

字段对照

验证配置

完成配置后，可以先运行：

openclaw

如果一切正常，再继续检查模型状态：

openclaw models list

openclaw models status

openclaw doctor

启动服务

正式启动时可使用：

openclaw start

如果需要重启网关：

openclaw gateway restart

常见问题

直接请求正常，OpenClaw 却返回 403

这通常不是 Key 错误，而是底层 SDK 发出的 User-Agent 被某些 CDN 或 WAF 拦截。

可以在 provider 里手动补一个 headers 字段覆盖 UA：

{
  "nbility-anthropic": {
    "baseUrl": "https://api.nbility.dev",
    "apiKey": "your-api-key",
    "api": "anthropic-messages",
    "headers": {
      "User-Agent": "Mozilla/5.0"
    },
    "models": []
  }
}

Anthropic 的 baseUrl 为什么不能带 /v1

因为 Anthropic SDK 会自动补路径，如果你已经手动写了 /v1，最终请求可能变成 /v1/v1/messages，从而导致 404。

api 字段有哪些合法值

OpenClaw 对这个字段校验比较严格，常用值包括：

• anthropic-messages
• openai-completions
• openai-responses

通过 Nbility 使用 Claude 时，建议选 anthropic-messages；调用 GPT 时，建议选 openai-responses。

为什么不推荐 openai-completions

某些情况下它会请求成功但界面显示空回复，因此如果你接的是 GPT 系列，更稳妥的做法还是使用 openai-responses。

改了配置却没有生效

需要注意 OpenClaw 可能还会读取另一处 provider 配置：

~/.openclaw/openclaw.json
~/.openclaw/agents/main/agent/models.json

如果只修改一处，结果可能不会立即反映出来。改完后建议重新执行：

openclaw models status

或者直接重启：

openclaw gateway restart

JSON 报错怎么排查

常见问题包括：

• 末尾多写了逗号
• 并列字段之间少逗号
• 使用了单引号或中文引号
• 花括号和方括号没有配平

你可以用下面的命令快速检查格式：

python3 -m json.tool ~/.openclaw/openclaw.json

reasoning 字段是什么意思

这个字段用于控制模型是否启用更强的推理模式。开启后通常会增加推理过程和 token 消耗。如果你不确定模型是否支持，先设成 false 会更稳妥。

有哪些排查命令值得记住

提示: 排查时先确认 Nbility API 本身可用，再对比 OpenClaw 实际发出的路径、协议和请求头，效率会更高。