使用 CometAPI 搭配 OpenClaw

使用本指南将 OpenClaw 连接到 CometAPI。请选择一种 API 格式和模型 ID 进行首次配置。

OpenClaw v2026.8.1 也称为 OpenClaw 2.0。该软件包不使用 2.x 版本号。请参阅 OpenClaw 2.0 公告以及 v2026.8.1 发行说明.

OpenClaw 官方参考资料：

前提条件

Node.js 22.22.3+、24.15+ 或 25.9+。建议使用 Node 26。Node 23 不受支持。
拥有有效 API 密钥的 CometAPI 账户，该密钥可从控制台.
来自 CometAPI 模型页面.

安装和升级

首次安装
升级现有安装

官方安装程序可以在不启动初始设置的情况下安装 CLI。这样可将模型配置作为单独的步骤进行。

macOS / Linux / WSL2
Windows PowerShell

以下命令会运行官方安装程序：

curl -fsSL https://openclaw.ai/install.sh \
  | bash -s -- --no-onboard

以下命令会运行官方 PowerShell 安装程序：

& ([scriptblock]::Create(
  (iwr -useb https://openclaw.ai/install.ps1)
)) -NoOnboard

如果您自行管理 Node.js 和 npm，npm 11.16+ 和 npm 12 均接受该 --allow-scripts 选项。以下命令可在不启动初始设置的情况下安装 OpenClaw：

npm install -g openclaw@latest --allow-scripts=openclaw

在 npm 11.15 及更早版本中，请省略 --allow-scripts=openclaw，因为该 npm 版本不识别此选项。确认已安装的 CLI 满足本指南要求的最低版本：

openclaw --version

继续配置 CometAPI。请勿先直接运行初始设置，因为引导式流程不会显示所有自定义 API 适配器。

在进行重大更新前创建并验证备份。归档文件可能包含 API 密钥、通道状态和身份验证数据，因此应像保护 OpenClaw 状态目录一样保护它。以下命令会创建备份并更新 OpenClaw：

mkdir -p ~/Backups/openclaw
openclaw backup create --output ~/Backups/openclaw --verify
openclaw update

更新后，修复受支持的迁移并检查 Gateway 健康状态：

openclaw doctor --fix
openclaw gateway restart
openclaw health

更新会保留已配置的模型路由。请勿重复进行初始设置，除非您想更改模型提供商或其身份验证方式。

配置 CometAPI

使用经典引导

对于聊天补全、响应和 Anthropic 消息，经典引导是首次安装的首选方式。以下命令会打开经典引导并安装后台服务：

openclaw onboard --classic --install-daemon

在 Model/Auth中，选择 Custom Provider。然后输入以下某个兼容性选项的值：

API 格式	提供商 ID	兼容性选项	基础 URL
聊天补全	`cometapi-openai`	与 OpenAI 兼容	`https://api.cometapi.com/v1`
响应	`cometapi-openai-responses`	与 OpenAI Responses 兼容	`https://api.cometapi.com/v1`
Anthropic 消息	`cometapi-claude`	与 Anthropic 兼容	`https://api.cometapi.com`

请输入匹配的提供商 ID、your-model-id 和您的 CometAPI API 密钥，系统提示时输入。终端向导会隐藏 API 密钥输入内容。经典引导的 Custom Provider 菜单不包含 Google Generative AI 适配器。若要使用该适配器，请完成使用配置命令配置提供商, ，设置主模型，然后运行经典引导。选择 保留现有模型配置 ，当向导显示该选项时。

使用配置命令配置提供商

对于 Google 适配器或需要受控配置更改的情况，请使用此路径。 OpenClaw 支持 JSON5，因此请勿使用严格的 JSON 工具解析并重写 openclaw.json。严格的 JSON 工具。

OpenClaw 的原生配置写入器会验证 JSON5，但在写入时会将文件规范化为 JSON。现有注释、尾随逗号和格式可能会被移除。如果这些细节对您很重要，请在应用补丁前创建经过验证的备份。对您很重要。

首先，输出活动配置路径并验证其内容：

openclaw config file
openclaw config validate

OpenClaw 从进程环境或全局状态 .env 文件中读取提供商 API 密钥。它不信任工作区中的 .env 文件来存储提供商 API 密钥。全局文件为 ~/.openclaw/.env，或者在设置了 $OPENCLAW_STATE_DIR/.env OPENCLAW_STATE_DIR 时使用相应文件。如果经典引导已存储 API 密钥，请跳过以下步骤。否则，请使用适用于您操作系统的选项卡来存储 API 密钥，而不显示它。

macOS / Linux / WSL2
Windows PowerShell

以下命令会以原子方式更新 COMETAPI_KEY，并拒绝空值：

state_dir="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
install -d -m 700 "$state_dir"
read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
if [ -z "$COMETAPI_KEY" ]; then
  echo "The CometAPI API key cannot be empty." >&2
  unset COMETAPI_KEY
  exit 1
fi
umask 077
env_file="$state_dir/.env"
temp_file="$(mktemp "${env_file}.XXXXXX")"
if [ -f "$env_file" ]; then
  awk -F= '$1 != "COMETAPI_KEY"' "$env_file" > "$temp_file"
fi
printf 'COMETAPI_KEY=%s\n' "$COMETAPI_KEY" >> "$temp_file"
chmod 600 "$temp_file"
mv "$temp_file" "$env_file"
unset COMETAPI_KEY temp_file env_file state_dir

以下命令会更新 COMETAPI_KEY，但不会显示它：

$stateDir = if ($env:OPENCLAW_STATE_DIR) {
  $env:OPENCLAW_STATE_DIR
} else {
  Join-Path $HOME ".openclaw"
}
New-Item -ItemType Directory -Force -Path $stateDir | Out-Null
$secureKey = Read-Host "CometAPI API key" -AsSecureString
$plainKey = [Net.NetworkCredential]::new("", $secureKey).Password
if ([string]::IsNullOrWhiteSpace($plainKey)) {
  throw "The CometAPI API key cannot be empty."
}
$envFile = Join-Path $stateDir ".env"
$lines = @()
if (Test-Path $envFile) {
  $lines = @(Get-Content $envFile | Where-Object {
    $_ -notmatch '^COMETAPI_KEY='
  })
}
$lines += "COMETAPI_KEY=$plainKey"
$tempFile = Join-Path $stateDir ".$([guid]::NewGuid()).tmp"
[IO.File]::WriteAllLines($tempFile, $lines)
Move-Item -Force $tempFile $envFile
$plainKey = $null
$secureKey = $null

添加提供商前，请检查其目标路径。请将以下命令中的提供商 ID 替换为所选选项卡中的 ID：

openclaw config get models.providers.cometapi-openai --json

如果该命令返回已配置的提供商，请停止操作，不要应用该示例。 config patch 会合并对象，但会替换数组。请在写入该数组前，将新模型合并到提供商的模型数组中。这样可以保留模型元数据、自定义标头和其他提供商设置。选择一种 API 格式。每个补丁均使用由环境变量支持的 SecretRef，并且只会更改目标配置路径，同时保持其他配置部分不变。

模型 ID 并非自动与每个 API 适配器兼容。请选择确切的 CometAPI 模型和路由所支持的适配器，然后通过实时请求验证该提供商/模型/适配器组合。以下 your-model-id 值是配置占位符，并非通用兼容性声明。

聊天补全
响应
Anthropic 消息
Google Generative AI

提供商 ID：cometapi-openai
OpenClaw 适配器：openai-completions
基础 URL：https://api.cometapi.com/v1
主模型引用：cometapi-openai/your-model-id

使用此提供商补丁创建 cometapi.patch.json5：

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-completions",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

在 OpenClaw 写入配置前验证补丁：

openclaw config patch --file ./cometapi.patch.json5 --dry-run

如果验证成功，应用同一补丁：

openclaw config patch --file ./cometapi.patch.json5

如果未配置主模型，请将此模型设为默认模型：

openclaw models set cometapi-openai/your-model-id

验证提供商配置并发送最小模型请求：

openclaw models list --provider cometapi-openai
openclaw models status --probe \
  --probe-provider cometapi-openai
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai/your-model-id \
  --thinking off \
  --json

要切换活动的 OpenClaw 聊天会话，请运行以下聊天命令：

/model cometapi-openai/your-model-id

提供商 ID：cometapi-openai-responses
OpenClaw 适配器：openai-responses
基础 URL：https://api.cometapi.com/v1
主模型引用：cometapi-openai-responses/your-model-id

使用此提供商补丁创建 cometapi.patch.json5：

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-openai-responses": {
        baseUrl: "https://api.cometapi.com/v1",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "openai-responses",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

在 OpenClaw 写入配置前验证补丁：

openclaw config patch --file ./cometapi.patch.json5 --dry-run

如果验证成功，应用同一补丁：

openclaw config patch --file ./cometapi.patch.json5

如果未配置主模型，请将此模型设为默认模型：

openclaw models set cometapi-openai-responses/your-model-id

验证提供商配置并发送最小模型请求：

openclaw models list --provider cometapi-openai-responses
openclaw models status --probe \
  --probe-provider cometapi-openai-responses
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-openai-responses/your-model-id \
  --thinking off \
  --json

要切换活动的 OpenClaw 聊天会话，请运行以下聊天命令：

/model cometapi-openai-responses/your-model-id

提供商 ID：cometapi-claude
OpenClaw 适配器：anthropic-messages
基础 URL：https://api.cometapi.com
主模型引用：cometapi-claude/your-model-id

使用此提供商补丁创建 cometapi.patch.json5：

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-claude": {
        baseUrl: "https://api.cometapi.com",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "anthropic-messages",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

在 OpenClaw 写入配置前验证补丁：

openclaw config patch --file ./cometapi.patch.json5 --dry-run

如果验证成功，应用同一补丁：

openclaw config patch --file ./cometapi.patch.json5

如果未配置主模型，请将此模型设为默认模型：

openclaw models set cometapi-claude/your-model-id

验证提供商配置并发送最小模型请求：

openclaw models list --provider cometapi-claude
openclaw models status --probe \
  --probe-provider cometapi-claude
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-claude/your-model-id \
  --thinking off \
  --json

要切换活动的 OpenClaw 聊天会话，请运行以下聊天命令：

/model cometapi-claude/your-model-id

提供商 ID：cometapi-google
OpenClaw 适配器：google-generative-ai
基础 URL：https://api.cometapi.com/v1beta
主模型引用：cometapi-google/your-model-id

使用此提供商补丁创建 cometapi.patch.json5：

{
  models: {
    mode: "merge",
    providers: {
      "cometapi-google": {
        baseUrl: "https://api.cometapi.com/v1beta",
        apiKey: {
          source: "env",
          provider: "default",
          id: "COMETAPI_KEY",
        },
        api: "google-generative-ai",
        models: [
          {
            id: "your-model-id",
            name: "CometAPI model",
            input: ["text"],
          },
        ],
      },
    },
  },
}

在 OpenClaw 写入配置前验证补丁：

openclaw config patch --file ./cometapi.patch.json5 --dry-run

如果验证成功，应用同一补丁：

openclaw config patch --file ./cometapi.patch.json5

如果未配置主模型，请将此模型设为默认模型：

openclaw models set cometapi-google/your-model-id

验证提供商配置并发送最小模型请求：

openclaw models list --provider cometapi-google
openclaw models status --probe \
  --probe-provider cometapi-google
openclaw agent exec \
  "Reply exactly with: OPENCLAW_OK" \
  --model cometapi-google/your-model-id \
  --thinking off \
  --json

要切换活动的 OpenClaw 聊天会话，请运行以下聊天命令：

/model cometapi-google/your-model-id

如果某个配置已使用 cometapi-gemini 提供商 ID，请保留该 ID，并在模型引用和命令中使用它。请勿重命名它，也不要仅为匹配本指南而创建重复的提供商。

包含四种 CometAPI 提供商格式的 OpenClaw 2026.8.1 模型列表

对于新提供商，openclaw config set 提供相同的架构和 SecretRef 检查。写入前请使用 --strict-json、--merge 和 --dry-run。以下替代方法会预览聊天补全提供商：

openclaw config set models.providers.cometapi-openai \
  '{
    "baseUrl": "https://api.cometapi.com/v1",
    "apiKey": {
      "source": "env",
      "provider": "default",
      "id": "COMETAPI_KEY"
    },
    "api": "openai-completions",
    "models": [
      {
        "id": "your-model-id",
        "name": "CometAPI model",
        "input": ["text"]
      }
    ]
  }' \
  --strict-json --merge --dry-run

如果试运行成功，请在不使用 --dry-run 的情况下重复该命令以保存它。请勿将此示例应用于已配置的提供商。写入前，models 数组必须包含该提供商完整的合并后模型列表。

了解模型元数据

最小补丁声明的是纯文本模型。仅当您已验证模型规格时，才添加可选元数据：

字段	作用
`input`	声明接受的输入模态。仅当模型接受原生图像输入时才使用 `["text", "image"]`。
`contextWindow`	记录模型的原生上下文窗口容量。
`contextTokens`	限制活动输入预算，但不更改 `contextWindow`.
`maxTokens`	限制 OpenClaw 向模型请求的输出 Token 数。

错误的值可能会隐藏受支持的输入、夸大可用上下文，或请求不受支持的输出大小。在可复用示例中保留 your-model-id，并使用 CometAPI 模型页面选择模型 ID。

验证完整设置

在配置或全局 .env 文件更改后，重启 Gateway：

openclaw gateway restart

然后验证配置和 Gateway 状态：

openclaw config validate
openclaw doctor
openclaw health

从所选 API 格式选项卡中运行特定提供商的命令。模型列表或状态检查只能确认配置。openclaw agent exec 命令会发送真实的模型请求。确认其返回 OPENCLAW_OK ，且不存在未解决的身份验证、适配器或模型错误。如果 OpenClaw 重试某个请求，请记录并检查每一次尝试，而不要将最终标记视为单次尝试成功。

故障排除

缺少 API 密钥

确认进程环境或全局状态 COMETAPI_KEY 文件中存在 .env。请勿将该值打印到终端输出中。更正受信任的密钥来源后，重启并检查 Gateway：

openclaw gateway restart
openclaw health

提供商 ID 的设置不同

请勿覆盖具有不同 baseUrl、api、自定义标头或模型元数据的提供商。请先检查目标提供商：

openclaw config get models.providers.cometapi-openai --json
openclaw config validate

当两种配置都有意保留时，请使用不同的提供商 ID。如果差异是意外造成的，请在更改前创建经过验证的备份目标提供商。

更新未完成

修复安装前，请检查更新状态：

openclaw update status --json
openclaw update repair
openclaw doctor --fix
openclaw health

这些命令会保留状态目录。

需要回滚代码

在保留状态目录的同时重新安装已知的软件包版本。首先，预览操作：

openclaw update --tag 2026.8.1 --dry-run

如果预览正确，请运行相同的操作，但不带 --dry-run：

openclaw update --tag 2026.8.1
openclaw doctor --fix
openclaw health

概览

AI 编码智能体

AI 智能体

AI 聊天客户端

翻译与语言

自动化平台

可观测性与评估

AI 框架

前提条件

安装和升级

配置 CometAPI

使用经典引导

使用配置命令配置提供商

了解模型元数据

验证完整设置

故障排除

​前提条件

​安装和升级

​配置 CometAPI

​使用经典引导

​使用配置命令配置提供商

​了解模型元数据

​验证完整设置

​故障排除

前提条件

安装和升级

配置 CometAPI

使用经典引导

使用配置命令配置提供商

了解模型元数据

验证完整设置

故障排除