Configuração do provedor de modelos do OpenClaw

O OpenClaw é instalado sem exigir uma chave de API de modelo no Appbox.

A forma recomendada de concluir a configuração é conectar ao seu app OpenClaw por SSH e executar o assistente integrado openclaw onboard. O assistente é mais seguro do que editar a configuração completa manualmente, porque preserva as configurações de gateway do Appbox enquanto orienta você por provedores de modelos, chaves de API, canais, verificações de integridade e skills.

Se você não puder ou não quiser usar SSH, use o método alternativo pelo dashboard.

Método recomendado: acessar o OpenClaw por SSH e executar o onboarding

Use este método para novas instalações e para instalações existentes que precisam adicionar ou alterar credenciais de provedores de modelos.

O que você precisa primeiro

• A página de detalhes do seu app OpenClaw no Appbox.
• O SSH Command mostrado na seção Configuration.
• Seu Gateway Token / SSH Password. Esse é o mesmo segredo gerado usado para login no dashboard do OpenClaw.
• Uma conta ou chave de API de um provedor de modelos. Se você ainda não tiver uma, veja Como obter chaves de API.

A página de detalhes do app mostra o comando SSH pronto para copiar:

Conectar pelo macOS

1. Abra o Terminal ou o iTerm2.
2. Copie o SSH Command da página de detalhes do app OpenClaw.
3. Cole e execute o comando. Ele será parecido com isto:

ssh node@your-openclaw-domain.example -p 12345

4. Se o macOS perguntar se você confia no host, digite yes e pressione Enter.
5. Quando a senha for solicitada, cole seu Gateway Token / SSH Password e pressione Enter. O Terminal não exibirá nenhum caractere enquanto você digita ou cola a senha.

Conectar pelo Windows

O Windows 10 e o Windows 11 incluem o cliente OpenSSH por padrão.

1. Abra o Windows Terminal ou o PowerShell.
2. Copie o SSH Command da página de detalhes do app OpenClaw.
3. Cole e execute:

ssh node@your-openclaw-domain.example -p 12345

4. Se o Windows perguntar se você confia no host, digite yes e pressione Enter.
5. Quando a senha for solicitada, cole seu Gateway Token / SSH Password e pressione Enter. O PowerShell não exibirá a senha colada.

Se o Windows disser que ssh não é reconhecido, instale OpenSSH Client em Settings > System > Optional features, reabra o Windows Terminal e tente novamente.

Executar o assistente de onboarding do OpenClaw

Depois que a conexão SSH for estabelecida, execute:

openclaw onboard

O assistente é interativo. Use estas opções específicas do Appbox:

1. Configuração existente: escolha a opção para revisar ou modificar a configuração atual. Não escolha uma redefinição completa, a menos que você realmente queira reconstruir sua configuração do OpenClaw do zero.
2. Modelo e autenticação: escolha seu provedor, como OpenRouter, OpenAI, Anthropic, Google, xAI ou um provedor personalizado compatível com OpenAI. Cole a chave de API quando o assistente pedir. O OpenRouter é o padrão mais fácil para a maioria dos usuários, porque uma chave pode rotear para muitos modelos. Se você tiver uma assinatura OpenAI Codex, escolha OpenAI Codex na lista de provedores, não uma opção chamada apenas codex.
3. Modelo padrão: escolha o modelo que o assistente recomenda para esse provedor ou informe manualmente um valor provider/model, como openrouter/auto.
4. Workspace: mantenha o workspace padrão, a menos que você tenha um motivo específico para alterá-lo.
5. Configurações de gateway: mantenha as configurações de gateway existentes do Appbox. Em especial, mantenha a autenticação por token ativada e mantenha as configurações atuais de porta/bind do gateway.
6. Canais: configure WhatsApp, Telegram, Discord, Signal, iMessage ou outros canais agora, ou ignore-os e adicione-os depois com openclaw configure.
7. Busca na web: escolha um provedor de busca se você tiver um, ou ignore por enquanto.
8. Instalação de daemon/serviço: o Appbox já supervisiona o OpenClaw dentro do contêiner, então ignore a instalação de daemon se o assistente oferecê-la.
9. Verificação de integridade: deixe o assistente executar a verificação de integridade.
10. Skills: permita que o assistente verifique as skills incluídas. Quando ele perguntar Preferred node manager for skill installs, escolha npm.

Quando o onboarding terminar, volte ao dashboard do OpenClaw. Se o dashboard já estava aberto, atualize a página e teste um prompt curto no chat.

Comandos úteis por SSH:

openclaw configure
openclaw status --deep
openclaw health

Como obter chaves de API (com links para dashboards)

Use estes consoles de provedores para gerar chaves. Com o método recomendado por SSH, cole a chave quando openclaw onboard pedir. Com o método alternativo pelo dashboard, mescle a chave em Config > Secrets > Raw.

Recomendado primeiro: OpenRouter (melhor padrão para a maioria dos usuários)

Por que recomendamos:

• Ele fornece uma chave para vários provedores de modelos.
• Você pode usar openrouter/auto, que pode alternar modelos com base na dificuldade da tarefa.
• auto pode reduzir custos roteando tarefas mais simples para modelos mais baratos.

Como obter uma chave:

1. Acesse OpenRouter e faça login.
2. Abra as configurações de API Keys.
3. Clique em Create e copie a chave (mostrada uma vez).
4. Use-a quando o assistente do OpenClaw pedir sua chave de API do OpenRouter. Para o método alternativo pelo dashboard, a chave de configuração é models.providers.openrouter.apiKey.

Tutorial original: How to Get an OpenRouter API Key

OpenAI

Como obter uma chave:

1. Faça login na OpenAI Platform.
2. Abra API Keys.
3. Clique em Create new secret key.
4. Copie imediatamente (a OpenAI só mostra o valor completo uma vez).

Tutorial original: How to Get an OpenAI API Key

Anthropic

Como obter uma chave:

1. Faça login no Anthropic Console.
2. Abra API Keys.
3. Clique em Create Key.
4. Copie a chave imediatamente (mostrada uma vez).

Tutorial original: How to get your Claude API key

Google (Gemini via AI Studio)

Como obter uma chave:

1. Abra o Google AI Studio.
2. Acesse API Keys.
3. Clique em Create API key (projeto novo ou existente).
4. Copie e salve a chave.

Tutorial original: Get Google AI API Key

Observação: os dashboards dos provedores podem mudar com frequência e podem mostrar uma solicitação de login dependendo do estado da sua sessão.

Método alternativo: configurar a autenticação do provedor no dashboard

Use este método apenas se SSH não estiver disponível ou se você preferir configuração manual. O editor Raw do dashboard funciona, mas edita o objeto completo de configuração do OpenClaw de uma só vez. Tenha cuidado para mesclar as configurações do provedor no arquivo existente em vez de substituir os padrões de gateway e skills do Appbox.

1. Abra a URL do dashboard do OpenClaw na página de detalhes do app instalado.
2. Acesse Config > Secrets.
3. Selecione Raw em vez de Form.
4. Clique no botão Reveal sensitive values (parecido com um olho riscado).
5. Mescle as configurações do provedor dos exemplos abaixo com sua configuração existente (veja Como a configuração manual do provedor se encaixa no arquivo completo) — não substitua o arquivo inteiro, a menos que você pretenda redefinir o gateway, as skills e outros padrões do Appbox.
6. Salve e aplique as alterações de configuração.

Como a configuração manual do provedor se encaixa no arquivo completo

Config > Secrets > Raw edita a configuração inteira do OpenClaw em um único objeto. No Appbox, esse arquivo já inclui coisas como gateway (bind, autenticação por token, Control UI), skills.load.extraDirs (skills incluídas), commands e, às vezes, meta. Os trechos na seção Exemplos dos principais provedores mostram apenas as partes necessárias para modelos: a árvore models e agents.defaults.model.primary.

O que fazer: mantenha as chaves de nível superior existentes (gateway, skills, commands, etc.) e adicione ou atualize estas duas seções:

• models.providers — adicione seu provedor (por exemplo openrouter) e seu apiKey, baseUrl quando necessário e a lista models.
• agents.defaults.model.primary — defina a string do modelo padrão (por exemplo openrouter/auto) para que o agent use esse provedor.

Se models ou agents já existirem, mescle novas chaves nesses objetos em vez de duplicá-los.

Abaixo está um exemplo de um formato completo de arquivo Raw em JSON (na prática, o editor também pode aceitar aspas no estilo JSON5). Seu arquivo real pode incluir mais campos (por exemplo, metadados de modelo mais detalhados, meta). Os blocos de provedor nos exemplos mais abaixo são as partes que você alinha com models e agents aqui.

{
  "models": {
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "YOUR_OPENROUTER_KEY",
        "models": [
          {
            "id": "auto",
            "name": "Auto (OpenRouter)",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/auto"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "bind": "lan",
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true,
      "dangerouslyDisableDeviceAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "YOUR_GATEWAY_TOKEN"
    }
  },
  "skills": {
    "load": {
      "extraDirs": ["/app/skills"]
    }
  }
}

Token do gateway vs. chave de API do provedor: gateway.auth.token serve apenas para fazer login na Control UI / gateway do OpenClaw. models.providers.*.apiKey é sua chave do provedor de LLM (OpenRouter, OpenAI, etc.) — são configurações diferentes.

Exemplos dos principais provedores

Use primeiro um bloco de provedor por vez, confirme que ele funciona e só então adicione mais provedores. Cada exemplo abaixo é um fragmento de mesclagem: ... é a configuração omitida (linhas acima ou abaixo), e o }, antes de "models" fecha qualquer chave que esteja acima de models no seu arquivo (por exemplo skills ou commands). Os trechos não são JSON válidos por si só — mescle as seções models e agents no objeto raiz.

OpenRouter

...
  },
  "models": {
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-...",
        "models": [
          {
            "id": "auto",
            "name": "Auto (OpenRouter)"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/auto"
      }
    }
  },
...

OpenAI

...
  },
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-...",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.4"
      }
    }
  },
...

Anthropic

...
  },
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "https://api.anthropic.com/v1",
        "apiKey": "sk-ant-...",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6"
      }
    }
  },
...

Google (Gemini)

...
  },
  "models": {
    "providers": {
      "google": {
        "apiKey": "AIza...",
        "models": [
          {
            "id": "gemini-3.1-pro-preview",
            "name": "Gemini 3.1 Pro Preview"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3.1-pro-preview"
      }
    }
  },
...

xAI (Grok)

...
  },
  "models": {
    "providers": {
      "xai": {
        "apiKey": "xai-...",
        "models": [
          {
            "id": "grok-4",
            "name": "Grok 4"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "xai/grok-4"
      }
    }
  },
...

Mistral

...
  },
  "models": {
    "providers": {
      "mistral": {
        "baseUrl": "https://api.mistral.ai/v1",
        "apiKey": "sk-...",
        "models": [
          {
            "id": "mistral-large-latest",
            "name": "Mistral Large Latest"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "mistral/mistral-large-latest"
      }
    }
  },
...

Together AI

...
  },
  "models": {
    "providers": {
      "together": {
        "baseUrl": "https://api.together.xyz/v1",
        "apiKey": "together-...",
        "models": [
          {
            "id": "moonshotai/Kimi-K2.5",
            "name": "Kimi K2.5"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "together/moonshotai/Kimi-K2.5"
      }
    }
  },
...

Observação sobre Bedrock (sem chave de API)

O Amazon Bedrock usa credenciais AWS (por exemplo AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) em vez de uma chave de API. Uma entrada mínima de provedor fica assim:

...
  },
  "models": {
    "providers": {
      "amazon-bedrock": {
        "baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
        "api": "bedrock-converse-stream",
        "auth": "aws-sdk",
        "models": [
          {
            "id": "us.anthropic.claude-opus-4-6-v1:0",
            "name": "Claude Opus 4.6 (Bedrock)"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0"
      }
    }
  },
...

Notas

• O token de autenticação do gateway e as chaves de API de provedores de modelos são configurações diferentes.
• Se você receber um erro de provedor (por exemplo, chave Anthropic ausente), atualize seu modelo padrão para um provedor que você configurou.
• Se a validação de um provedor falhar, primeiro confirme se os campos obrigatórios do provedor estão presentes (baseUrl, models e apiKey quando aplicável).

Documentação oficial dos provedores

• OpenClaw provider directory
• OpenRouter provider
• OpenAI provider
• Anthropic provider
• Google provider
• xAI provider
• Mistral provider
• Together AI provider
• Amazon Bedrock provider