OpenClaw na Rússia: Gateway seguro e configuração de API

O que o OpenClaw executa

OpenClaw tem várias camadas. Um problema em uma camada muitas vezes parece problema em outra, por isso separe suas funções antes de ajustar.

Neste esquema BetterToken responde apenas pela Provider API. Não garante site OpenClaw, instalador, channels, community skills ou serviços terceiros. BetterToken API Endpoint pode ser conectado da Rússia sem VPN; isso não se aplica a downloads OpenClaw nem integrações externas.

Instalar OpenClaw sem Gateway permanente

No primeiro controle, use instalador oficial com --no-onboard. Assim não inicia o assistente de setup nem cria serviço permanente antes da verificação do provider.

macOS, Linux ou WSL2

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

Windows PowerShell

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

Confira a CLI:

openclaw --version

O instalador oficial verifica a versão Node.js suportada e a instala se necessário. Não se prenda a Node antiga de guia de terceiros: requisitos atuais estão na página de instalação OpenClaw.

Configurar provider BetterToken sem API Key pública

O arquivo principal OpenClaw fica em:

~/.openclaw/openclaw.json

Antes de editar, crie um workspace separado:

mkdir -p ~/openclaw-first-check

No primeiro lançamento, selecione Model ID atual do grupo BetterToken GPT. A configuração usa openai-responses; para outro provider, não adivinhe protocolo pelo nome do modelo. Verifique openai-completions ou outra opção na documentação BetterToken atual.

{
  "models": {
    "mode": "merge",
    "providers": {
      "bettertoken": {
        "baseUrl": "https://www.bettertoken.ai/v1",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "BETTERTOKEN_API_KEY"
        },
        "api": "openai-responses",
        "models": [
          { "id": "YOUR_MODEL_ID", "name": "YOUR_MODEL_ID" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/openclaw-first-check",
      "model": { "primary": "bettertoken/YOUR_MODEL_ID" }
    }
  },
  "gateway": { "mode": "local", "bind": "loopback" },
  "tools": { "profile": "minimal" }
}
Mostrar mais

YOUR_MODEL_ID é placeholder. Troque pela ID completa do catálogo ou da janela Setup para sua Key. Deixe Base URL sem /responses ou /chat/completions.

O campo apiKey usa OpenClaw SecretRef. BETTERTOKEN_API_KEY deve estar em ambiente protegido acessível ao processo Gateway; a chave não é escrita em openclaw.json. OpenClaw oferece suporte oficial a SecretRef para models.providers.*.apiKey.

Confira se não há credenciais abertas na configuração nem arquivos gerados antigos:

openclaw secrets audit --check

Se a auditoria encontrar texto simples, use migração interativa:

openclaw secrets configure --apply

Não copie a chave para prompt, log, commit ou workspace do agente.

Verificar configuração, Gateway e modelo

1. Verificar JSON antes de executar

openclaw config validate

O comando valida schema ativo sem iniciar Gateway. Se houver erro, corrija campo indicado, aspas ou parênteses e confira de novo.

2. Verificar provider e modelo selecionado

openclaw models list --provider bettertoken
openclaw models status

bettertoken/YOUR_MODEL_ID deve estar na lista e status deve mostrá-lo como default resolvido. models list é leitura apenas; não prova chamada API bem-sucedida, então é preciso uma solicitação curta separada.

3. Iniciar Gateway em primeiro plano

Em outro terminal execute:

openclaw gateway --force

Deixe o processo aberto. No primeiro terminal confira:

openclaw gateway status --require-rpc
openclaw status

No teste local Gateway deve escutar em loopback, exigir auth e devolver probe RPC funcional. Não mude bind para lan, tailnet ou 0.0.0.0 na primeira vez.

4. Abrir uma sessão nova

openclaw tui --session first-check

Envie uma solicitação mínima sem ações em arquivos:

Retorne somente JSON: {"agent":"openclaw","sum":4}. Não use tools e não altere arquivos.

O primeiro lançamento é confirmado se:

• TUI retornou JSON válido;
• openclaw models status mostra bettertoken/YOUR_MODEL_ID;
• uma solicitação com modelo, status e consumo de Token esperados apareceu no Dashboard BetterToken;
• não há alterações inesperadas no workspace.

Após verificar, pare Gateway em primeiro plano com Ctrl+C. Só então decida se serviço permanente é necessário.

5. Instalar serviço somente após a verificação

Se Gateway deve funcionar após fechar o terminal:

openclaw gateway install
openclaw gateway restart
openclaw gateway status --require-rpc

Para reiniciar use openclaw gateway restart. O runbook oficial não recomenda trocar isso por cadeia stop e start.

Por que o primeiro lançamento precisa de direitos mínimos

Gateway é projetado por padrão para um circuito confiável. Um agente com tools pode ler e mudar arquivos, executar comandos e acessar a rede. Prompt injection não vem apenas de chat público: instruções nocivas podem estar em página, documento, anexo ou log.

No primeiro teste, mantenha tools.profile em minimal, Gateway em loopback e channels sem configurar. Não instale community skills ou plugins antes de conferir fonte e permissões. Antes de ampliar acesso, execute:

openclaw security audit --deep

Se conectar um channel depois, comece com pairing ou allowlist e session scope separado. Um Gateway compartilhado por usuários que não confiam entre si não é limite de isolamento suportado.

Por que sessão antiga pode usar modelo antigo

Após mudar agents.defaults.model.primary, uma edição JSON não basta para conversa já aberta. Confira configuração, reinicie Gateway e crie chave de sessão nova:

openclaw config validate
openclaw gateway restart
openclaw tui --session after-model-change

Assim a verificação não se mistura ao contexto antigo. Se sessão nova ainda usar provider diferente, compare agents.defaults.model.primary, models.providers.bettertoken.models e saída de openclaw models status.

Erros frequentes

config validate não passa

Confira estrutura JSON e valores api compatíveis. Não inicie Gateway com configuração inválida: trate alterações diretas do editor como não confiáveis até a validação passar.

Gateway não inicia ou probe RPC falha

Primeiro execute openclaw gateway status. EADDRINUSE significa conflito de porta ou segundo processo Gateway. Erro auth indica incompatibilidade entre credential Gateway e cliente. Não desative auth nem abra bind para rede externa para contornar o erro.

401, 404 ou erro de protocolo

Em 401, confira se SecretRef é resolvido no ambiente Gateway. Para grupo GPT use openai-responses e Base URL https://www.bettertoken.ai/v1. Para outro provider, obtenha protocolo exato em Docs; não adicione endpoint manualmente.

Modelo está no JSON, mas não aparece

Compare ID em models.providers.bettertoken.models com agents.defaults.model.primary, depois execute openclaw config validate, openclaw models list --provider bettertoken e openclaw models status.

OpenClaw ou Hermes Agent

Esta instrução responde apenas à instalação. Se você ainda escolhe arquitetura, o artigo Hermes Agent ou OpenClaw: como escolher compara runtime local, abordagem Gateway e complexidade operacional sem repetir esta configuração.

FAQ

Preciso conectar Telegram ou Discord de imediato?

Não. Primeiro confirme provider local, Gateway, modelo e sessão nova. Channels aumentam a superfície de acesso e exigem política separada de pairing ou allowlist.

Posso escrever API Key diretamente em openclaw.json?

Texto simples é tecnicamente suportado, mas para operação segura use SecretRef. Uma chave exposta na configuração é acessível a qualquer processo ou Agent tool que consiga ler o arquivo.

Como testar Gateway sem solicitação de modelo bem-sucedida?

openclaw gateway status --require-rpc verifica RPC e openclaw models status verifica permissão de modelo e credential. Um teste end-to-end completo termina apenas após resposta curta em sessão nova e a solicitação aparecer no BetterToken Dashboard.