OpenClaw安装与配置指南之如何使用自定义模型提供商

目录

• 系统要求
• 基础安装
• 安装 Node.js 和 npm
• 安装 OpenClaw
• 初始化 OpenClaw
• 配置自定义模型
• 添加自定义模型提供商
• API 类型说明
• 设置默认模型
• 配置 API 密钥
• 频道配置
• Telegram 配置
• Discord 配置
• 飞书 (Feishu) 配置
• 启动与管理
• 启动 Gateway
• 查看状态
• 停止服务
• 升级 OpenClaw
• WebUI 访问
• 常见问题
• 422 Unsupported request body 错误
• 端口已被占用
• 插件 ID 重复警告
• 无法连接到 Gateway
• 模型调用失败
• 配置文件完整示例
• 有用的命令

• 操作系统: Linux / macOS / Windows
• Node.js: v18.0.0 或更高版本
• npm: v9.0.0 或更高版本
• 内存: 建议 2GB 以上

使用 nvm (Node Version Manager) 安装：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 重新加载配置
source ~/.bashrc
# 安装 Node.js
nvm install 22
nvm use 22

# 全局安装 OpenClaw
npm install -g openclaw

# 验证安装
openclaw --version

# 运行初始化向导
openclaw onboard

初始化过程会：

• 创建配置目录 ~/.openclaw/
• 生成默认配置文件 openclaw.json
• 设置工作空间目录
• 配置认证令牌

配置文件位置

~/.openclaw/openclaw.json

编辑 openclaw.json，在 models.providers 中添加新的提供商配置：

示例 1: OpenAI 兼容 API (如 CrazyRouter)

{
  "models": {
    "mode": "merge",
    "providers": {
      "crazyrouter": {
        "baseUrl": "https://crazyrouter.com/v1",
        "apiKey": "sk-your-api-key-here",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

示例 2: Anthropic 兼容 API (如 MiniMax)

{
  "models": {
    "providers": {
      "minimax": {
        "baseUrl": "https://api.minimax.io/anthropic",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "MiniMax-M2.1",
            "name": "MiniMax M2.1",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 15,
              "output": 60,
              "cacheRead": 2,
              "cacheWrite": 10
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

OpenClaw 支持两种主要的 API 格式：

openai-completions: OpenAI Chat Completions API 格式

适用于: OpenAI, Azure OpenAI, 各种 OpenAI 兼容服务

anthropic-messages: Anthropic Messages API 格式

适用于: Anthropic Claude, 兼容 Anthropic API 的服务

在 agents.defaults.model 中设置主模型：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "crazyrouter/claude-opus-4-6"
      }
    }
  }
}

格式: <provider>/<model-id>

方法 1: 直接在配置文件中

{
  "models": {
    "providers": {
      "your-provider": {
        "apiKey": "your-api-key-here"
      }
    }
  }
}

方法 2: 使用环境变量

export OPENCLAW_PROVIDER_APIKEY="your-api-key-here"

方法 3: 使用认证配置

{
  "auth": {
    "profiles": {
      "provider:default": {
        "provider": "your-provider",
        "mode": "api_key"
      }
    }
  }
}

获取 Bot Token

1. 在 Telegram 中找到 @BotFather
2. 发送 /newbot 创建新机器人
3. 按提示设置名称和用户名
4. 获取 Bot Token

配置 Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token-here",
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "streamMode": "partial"
    }
  }
}

配置说明:

• dmPolicy: 私聊策略 (pairing 需要配对, open 开放)
• groupPolicy: 群组策略 (open 开放, whitelist 白名单)
• streamMode: 流式输出模式 (partial 部分流式, full 完整流式)

获取 Bot Token

1. 访问 Discord Developer Portal
2. 创建新应用
3. 在 Bot 选项卡中创建 Bot
4. 复制 Token
5. 启用必要的 Intents (Message Content Intent)

配置 Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-discord-bot-token",
      "groupPolicy": "open"
    }
  }
}

创建飞书应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 获取 App ID 和 App Secret
4. 配置权限和事件订阅

安装飞书插件

openclaw plugin install @m1heng-clawd/feishu

配置飞书

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_your_app_id",
      "appSecret": "your_app_secret",
      "connectionMode": "websocket",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

# 启动 WebSocket Gateway (默认端口 18789)
openclaw gateway --port 18789

# 后台运行
openclaw gateway --port 18789 &

# 绑定到所有网络接口
openclaw gateway --port 18789 --bind 0.0.0.0

# 查看健康状态
openclaw health

# 查看服务状态
openclaw status

# 查看会话列表
openclaw sessions

# 停止 Gateway
openclaw gateway stop

# 或使用 systemctl (如果配置了服务)
systemctl --user stop openclaw-gateway.service

# 升级到最新版本
npm update -g openclaw

# 验证版本
openclaw --version

启动 Gateway 后，可以通过浏览器访问 WebUI：

http://localhost:18789

认证令牌: 在 openclaw.json 的 gateway.auth.token 中查看

原因: API 请求格式不兼容

解决方案:

• 检查 api 字段是否正确 (openai-completions 或 anthropic-messages)
• 确认模型 ID 是否正确
• 验证 API 提供商是否支持该格式

错误: Address already in use

解决方案:

# 查找占用端口的进程
lsof -i :18789

# 停止现有服务
openclaw gateway stop

# 或使用不同端口
openclaw gateway --port 18790

警告: Duplicate plugin ID: feishu

解决方案: 这是已知的配置警告，不影响使用，可以忽略。

错误: disconnected [WS] unauthorized gateway token missing

解决方案:

1. 检查 Gateway 是否正在运行: openclaw health
2. 验证认证令牌是否正确
3. 检查防火墙设置
4. 尝试使用 127.0.0.1 而不是 localhost

检查清单:

• API Key 是否正确
• baseUrl 是否可访问
• 模型 ID 是否存在
• API 格式是否匹配
• 网络连接是否正常

{
  "meta": {
    "lastTouchedVersion": "2026.2.15",
    "lastTouchedAt": "2026-02-18T00:00:00.000Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-your-openai-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4",
            "name": "GPT-4",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 30,
              "output": 60,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      },
      "anthropic": {
        "baseUrl": "https://api.anthropic.com",
        "apiKey": "sk-ant-your-key",
        "api": "anthropic-messages",
        "models": [
          {
            "id": "claude-3-5-sonnet-20241022",
            "name": "Claude 3.5 Sonnet",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 3,
              "output": 15,
              "cacheRead": 0.3,
              "cacheWrite": 3.75
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-3-5-sonnet-20241022"
      },
      "workspace": "~/.openclaw/workspace",
      "maxConcurrent": 4
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-telegram-bot-token",
      "dmPolicy": "pairing",
      "groupPolicy": "open"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-generated-token"
    }
  }
}

# 查看帮助
openclaw --help
openclaw gateway --help

# 查看配置
cat ~/.openclaw/openclaw.json

# 查看日志
tail -f ~/.openclaw/agents/main/sessions/*.jsonl

# 测试 API 连接
curl -X POST https://your-api-endpoint/v1/chat/completions 
  -H "Authorization: Bearer your-api-key" 
  -H "Content-Type: application/json" 
  -d '{"model":"your-model","messages":[{"role":"user","content":"test"}]}'

# 备份配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

到此这篇关于OpenClaw安装与配置指南之如何使用自定义模型提供商的文章就介绍到这了,更多相关OpenClaw安装与配置内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！