Use o OpenClaw com o CometAPI

Use este guia para conectar OpenClaw ao CometAPI. Escolha um formato de API e um ID de modelo para a primeira configuração.

O OpenClaw v2026.8.1 também é denominado OpenClaw 2.0. O pacote não usa um número com o prefixo 2.x de versão. Consulte o anúncio do OpenClaw 2.0 e as notas de versão da v2026.8.1.

Referências oficiais do OpenClaw:

Pré-requisitos

Node.js 22.22.3+, 24.15+ ou 25.9+. O Node 26 é recomendado. O Node 23 não é compatível.
Uma conta do CometAPI com uma chave de API ativa no painel.
Um ID de modelo da página de modelos do CometAPI.

Instalação e atualizações

Primeira instalação
Atualizar uma instalação

O instalador oficial pode instalar a CLI sem iniciar a integração inicial. Isso mantém a configuração do modelo como uma etapa separada.

macOS / Linux / WSL2
Windows PowerShell

O comando a seguir executa o instalador oficial:

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

O comando a seguir executa o instalador oficial do PowerShell:

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

Se você mesmo gerencia o Node.js e o npm, o npm 11.16+ e o npm 12 aceitam a --allow-scripts opção. O comando a seguir instala o OpenClaw sem iniciar a integração inicial:

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

No npm 11.15 e anteriores, omita --allow-scripts=openclaw porque essa versão do npm não reconhece a opção.Confirme que a CLI instalada atende à versão mínima exigida para este guia:

openclaw --version

Prossiga para Configurar o CometAPI. Não execute a integração inicial simples primeiro, pois o fluxo guiado não expõe todos os adaptadores de API personalizados. adaptadores.

Crie e verifique um backup antes de uma atualização importante. O arquivo pode conter chaves de API, estado de canais e dados de autenticação, portanto proteja-o como você protege o diretório de estado do OpenClaw.Os comandos a seguir criam o backup e atualizam o OpenClaw:

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

Após a atualização, corrija as migrações compatíveis e verifique a integridade do Gateway:

openclaw doctor --fix
openclaw gateway restart
openclaw health

Uma atualização preserva a rota de modelo configurada. Não repita a integração inicial a menos que queira alterar o provedor do modelo ou sua autenticação.

Configurar o CometAPI

Usar a integração clássica

A integração clássica é o caminho preferencial para a primeira instalação do Chat Completions, Responses e Anthropic Messages. O comando a seguir abre a integração clássica e instala o serviço em segundo plano:

openclaw onboard --classic --install-daemon

Em Modelo/Autenticação, escolha Provedor personalizado. Em seguida, insira os valores de uma destas opções de compatibilidade:

Formato da API	ID do provedor	Opção de compatibilidade	URL base
Chat Completions	`cometapi-openai`	Compatível com OpenAI	`https://api.cometapi.com/v1`
Responses	`cometapi-openai-responses`	Compatível com OpenAI Responses	`https://api.cometapi.com/v1`
Anthropic Messages	`cometapi-claude`	Compatível com Anthropic	`https://api.cometapi.com`

Insira o ID do provedor correspondente, your-model-id e sua chave de API do CometAPI quando solicitado. O assistente do terminal oculta a entrada da chave de API. O menu clássico de Provedor personalizado não inclui o adaptador do Google Generative AI adaptador. Para usar esse adaptador, conclua Configurar um provedor com comandos de configuração, defina o modelo principal e execute a integração clássica. Escolha Manter a configuração existente do modelo quando o assistente apresentar essa opção.

Configurar um provedor com comandos de configuração

Use este caminho para o adaptador do Google ou para alterações controladas de configuração. O OpenClaw oferece suporte a JSON5, portanto não analise nem reescreva openclaw.json com uma ferramenta JSON estrita.

O gravador de configuração nativo do OpenClaw valida JSON5, mas normaliza o arquivo para JSON ao gravá-lo. Comentários existentes, vírgulas finais e formatação podem ser removidos. Crie um backup verificado antes de aplicar um patch se esses detalhes forem importantes para você.

Primeiro, exiba o caminho da configuração ativa e valide seu conteúdo:

openclaw config file
openclaw config validate

O OpenClaw lê as chaves de API do provedor a partir do ambiente do processo ou do arquivo de estado global .env. Ele não confia em um arquivo .env do espaço de trabalho para chaves de API do provedor . O arquivo global é ~/.openclaw/.env, ou $OPENCLAW_STATE_DIR/.env quando OPENCLAW_STATE_DIR está definido. Se a integração clássica armazenou a chave de API, pule a etapa a seguir. Caso contrário, use a guia do seu sistema operacional para armazenar a chave de API sem exibi-la .

macOS / Linux / WSL2
Windows PowerShell

Os comandos a seguir atualizam COMETAPI_KEY atomicamente e rejeitam um valor vazio:

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

Os comandos a seguir atualizam COMETAPI_KEY sem exibi-lo:

$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

Antes de adicionar um provedor, inspecione seu caminho de destino. Substitua o ID do provedor no comando a seguir pelo ID da guia selecionada:

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

Se o comando retornar um provedor configurado, pare antes de aplicar o exemplo. config patch mescla objetos, mas substitui arrays. Mescle o novo modelo ao array de modelos do provedor antes de gravar esse array. Isso preserva os metadados do modelo, cabeçalhos personalizados e outras configurações do provedor. Escolha um formato de API. Cada patch usa um SecretRef com suporte de ambiente, altera apenas os caminhos de configuração de destino e mantém intactas as outras seções de configuração.

Um ID de modelo não é automaticamente compatível com todos os adaptadores de API. Selecione um adaptador compatível com o modelo e a rota exatos do CometAPI e, em seguida, verifique essa combinação de provedor/modelo/adaptador com uma solicitação ativa. O your-model-id valor abaixo é um placeholder de configuração, não uma declaração universal de compatibilidade.

Chat Completions
Responses
Anthropic Messages
Google Generative AI

ID do provedor: cometapi-openai
Adaptador do OpenClaw: openai-completions
URL base: https://api.cometapi.com/v1
Referência do modelo principal: cometapi-openai/your-model-id

Crie cometapi.patch.json5 com este patch de provedor:

{
  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"],
          },
        ],
      },
    },
  },
}

Valide o patch antes que o OpenClaw grave a configuração:

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

Se a validação for bem-sucedida, aplique o mesmo patch:

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

Se nenhum modelo principal estiver configurado, defina este modelo como padrão:

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

Verifique a configuração do provedor e envie uma solicitação mínima ao modelo:

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

Para alternar a sessão de chat ativa do OpenClaw, execute este comando de chat:

/model cometapi-openai/your-model-id

ID do provedor: cometapi-openai-responses
Adaptador do OpenClaw: openai-responses
URL base: https://api.cometapi.com/v1
Referência do modelo principal: cometapi-openai-responses/your-model-id

Crie cometapi.patch.json5 com este patch de provedor:

{
  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"],
          },
        ],
      },
    },
  },
}

Valide o patch antes que o OpenClaw grave a configuração:

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

Se a validação for bem-sucedida, aplique o mesmo patch:

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

Se nenhum modelo principal estiver configurado, defina este modelo como padrão:

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

Verifique a configuração do provedor e envie uma solicitação mínima ao modelo:

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

Para alternar a sessão de chat ativa do OpenClaw, execute este comando de chat:

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

ID do provedor: cometapi-claude
Adaptador do OpenClaw: anthropic-messages
URL base: https://api.cometapi.com
Referência do modelo principal: cometapi-claude/your-model-id

Crie cometapi.patch.json5 com este patch de provedor:

{
  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"],
          },
        ],
      },
    },
  },
}

Valide o patch antes que o OpenClaw grave a configuração:

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

Se a validação for bem-sucedida, aplique o mesmo patch:

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

Se nenhum modelo principal estiver configurado, defina este modelo como padrão:

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

Verifique a configuração do provedor e envie uma solicitação mínima ao modelo:

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

Para alternar a sessão de chat ativa do OpenClaw, execute este comando de chat:

/model cometapi-claude/your-model-id

ID do provedor: cometapi-google
Adaptador do OpenClaw: google-generative-ai
URL base: https://api.cometapi.com/v1beta
Referência do modelo principal: cometapi-google/your-model-id

Crie cometapi.patch.json5 com este patch de provedor:

{
  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"],
          },
        ],
      },
    },
  },
}

Valide o patch antes que o OpenClaw grave a configuração:

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

Se a validação for bem-sucedida, aplique o mesmo patch:

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

Se nenhum modelo principal estiver configurado, defina este modelo como padrão:

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

Verifique a configuração do provedor e envie uma solicitação mínima ao modelo:

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

Para alternar a sessão de chat ativa do OpenClaw, execute este comando de chat:

/model cometapi-google/your-model-id

Se uma configuração já usa o ID de provedor cometapi-gemini, mantenha esse ID e use-o nas referências de modelo e nos comandos. Não o renomeie nem crie um provedor duplicado apenas para corresponder a este guia.

Lista de modelos do OpenClaw 2026.8.1 com quatro formatos de provedor CometAPI

Para um novo provedor, openclaw config set fornece o mesmo esquema e verificações de SecretRef. Use --strict-json, --merge e --dry-run antes da gravação. A alternativa a seguir pré-visualiza o provedor Chat Completions:

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

Se a execução de teste for bem-sucedida, repita o comando sem --dry-run para salvá-lo. Não aplique este exemplo a um provedor configurado. O array models deve incluir a lista completa de modelos mesclada do provedor antes de uma gravação.

Entender os metadados do modelo

Os patches mínimos declaram um modelo somente de texto. Adicione metadados opcionais apenas quando tiver verificado as especificações do modelo:

Campo	Efeito
`input`	Declara as modalidades de entrada aceitas. Use `["text", "image"]` somente quando o modelo aceitar entrada nativa de imagem.
`contextWindow`	Registra a capacidade nativa da janela de contexto do modelo.
`contextTokens`	Limita o orçamento de entrada ativo sem alterar `contextWindow`.
`maxTokens`	Limita os Tokens de saída que o OpenClaw solicita do modelo.

Valores incorretos podem ocultar entradas compatíveis, superestimar o contexto utilizável ou solicitar um tamanho de saída não compatível. Mantenha your-model-id em exemplos reutilizáveis, e use a página de modelos do CometAPI para selecionar um ID de modelo.

Verifique a configuração completa

Após alterações no arquivo de configuração ou no arquivo global .env, reinicie o Gateway:

openclaw gateway restart

Em seguida, valide a configuração e o estado do Gateway:

openclaw config validate
openclaw doctor
openclaw health

Execute os comandos específicos do provedor na guia de formato de API selecionada. Uma lista de modelos ou verificação de status confirma apenas a configuração. O comando openclaw agent exec envia uma solicitação real ao modelo. Confirme que ele retorna OPENCLAW_OK sem um erro não resolvido de autenticação, adaptador ou modelo. Se o OpenClaw tentar novamente uma solicitação, registre e inspecione cada tentativa em vez de tratar o marcador final como sucesso em uma única tentativa.

Solução de problemas

A chave de API está ausente

Confirme que COMETAPI_KEY está presente no ambiente do processo ou no arquivo de estado global .env. Não imprima o valor na saída do terminal.Depois de corrigir a fonte confiável da chave, reinicie e verifique o Gateway:

openclaw gateway restart
openclaw health

Um ID de provedor tem configurações diferentes

Não sobrescreva um provedor que tenha um baseUrl, api diferente, cabeçalhos personalizados ou metadados de modelo. Primeiro, inspecione o provedor de destino:

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

Use um ID de provedor diferente quando ambas as configurações forem intencionais. Se a diferença for acidental, crie um backup verificado antes de alterar o provedor de destino.

Uma atualização não foi concluída

Inspecione o estado da atualização antes de reparar a instalação:

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

Estes comandos preservam o diretório de estado.

É necessário reverter o código

Reinstale uma versão conhecida do pacote mantendo o diretório de estado. Primeiro, visualize a operação:

openclaw update --tag 2026.8.1 --dry-run

Se a visualização estiver correta, execute a mesma operação sem --dry-run:

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

Restaure um backup do estado somente quando o código instalado não conseguir ler o estado. Uma restauração do estado pode descartar sessões e alterações de configuração que foram criadas após o backup.

Visão Geral

Agentes de programação de IA

Agentes de IA

Clientes de chat de IA

Tradução e idioma

Plataformas de automação

Observabilidade e avaliação

Frameworks de IA

Pré-requisitos

Instalação e atualizações

Configurar o CometAPI

Usar a integração clássica

Configurar um provedor com comandos de configuração

Entender os metadados do modelo

Verifique a configuração completa

Solução de problemas

​Pré-requisitos

​Instalação e atualizações

​Configurar o CometAPI

​Usar a integração clássica

​Configurar um provedor com comandos de configuração

​Entender os metadados do modelo

​Verifique a configuração completa

​Solução de problemas

Pré-requisitos

Instalação e atualizações

Configurar o CometAPI

Usar a integração clássica

Configurar um provedor com comandos de configuração

Entender os metadados do modelo

Verifique a configuração completa

Solução de problemas