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

2026-05-22 12:02:56 Jeff Me

系统要求

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

基础安装

安装 Node.js 和 npm

使用 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

# 全局安装 OpenClaw
npm install -g openclaw

# 验证安装
openclaw --version

初始化 OpenClaw

# 运行初始化向导
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
          }
        ]
      }
    }
  }
}

API 类型说明

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>

配置 API 密钥

方法 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"
      }
    }
  }
}

频道配置

Telegram 配置

获取 Bot Token

在 Telegram 中找到 @BotFather
发送 /newbot 创建新机器人
按提示设置名称和用户名
获取 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 完整流式)

Discord 配置

获取 Bot Token

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

配置 Discord

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

飞书 (Feishu) 配置

创建飞书应用

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

安装飞书插件

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
      }
    }
  }
}

启动与管理

启动 Gateway

# 启动 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

升级 OpenClaw

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

# 验证版本
openclaw --version

WebUI 访问

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

http://localhost:18789

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

常见问题

422 Unsupported request body 错误

原因: API 请求格式不兼容

解决方案:

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

端口已被占用

错误: Address already in use

解决方案:

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

# 停止现有服务
openclaw gateway stop

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

插件 ID 重复警告

警告: Duplicate plugin ID: feishu

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

无法连接到 Gateway

错误: disconnected [WS] unauthorized gateway token missing

解决方案:

检查 Gateway 是否正在运行: openclaw health
验证认证令牌是否正确
检查防火墙设置
尝试使用 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安装与配置内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！