> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração do Hermes Agent: instalação, API Key, Base URL e modelos personalizados

> Instale o Hermes Agent, configure a Base URL e a API Key da BetterToken, escolha um modelo de provedor compatível e corrija erros comuns.

Para conectar o Hermes Agent à BetterToken, prepare uma API Key, informe a Base URL abaixo e escolha um ID de modelo atual na model plaza.

## Configurações principais

| Campo    | Valor                                                                               |
| -------- | ----------------------------------------------------------------------------------- |
| API Key  | BetterToken API Key                                                                 |
| Base URL | `https://www.bettertoken.ai/v1`                                                     |
| Modelo   | Um ID de modelo atual da <a href={"https://bettertoken.ai/pricing"}>model plaza</a> |

## Pré-requisitos

* A versão atual da ferramenta está instalada
* Uma BetterToken API Key: <a href={"https://bettertoken.ai/register"}>cadastre-se e crie uma</a>
* Um ID de modelo da <a href={"https://bettertoken.ai/pricing"}>model plaza</a>

### Requisitos adicionais

* O ID de modelo selecionado vem de um **provedor compatível**
* macOS, Linux, or Windows WSL2

## Instalação

### Instalar o Hermes Agent

<Tabs>
  <Tab title="macOS / Linux / WSL2">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows">
    No Windows, prefira WSL2. O suporte nativo ao PowerShell depende da versão atual do Hermes Agent. Se usar Windows nativo, siga as instruções do instalador da versão instalada.
  </Tab>
</Tabs>

### Referência rápida de recursos

| Recurso         | Finalidade                                              |
| --------------- | ------------------------------------------------------- |
| Terminal UI     | Converse com o agente diretamente no terminal           |
| Skills          | Salve fluxos reutilizáveis para tarefas recorrentes     |
| MCP             | Conecte recursos de ferramentas locais ou remotas       |
| Scheduled tasks | Execute tarefas agendadas e fluxos recorrentes          |
| Subagents       | Divida trabalhos complexos entre agentes especializados |
| Message gateway | Conecte o agente a mais pontos de entrada de mensagens  |

## Configuração manual

Use a configuração interativa de modelo do Hermes Agent como caminho principal. Comandos e variáveis de ambiente continuam disponíveis como alternativas.

| Campo    | Valor                                                                               |
| -------- | ----------------------------------------------------------------------------------- |
| API Key  | BetterToken API Key                                                                 |
| Base URL | `https://www.bettertoken.ai/v1`                                                     |
| Modelo   | Um ID de modelo atual da <a href={"https://bettertoken.ai/pricing"}>model plaza</a> |

### Configuração

<Tabs>
  <Tab title="Configuração interativa">
    <Steps>
      <Step title="Execute o seletor de modelos">
        ```bash theme={null}
        hermes model
        ```
      </Step>

      <Step title="Escolha o provedor OpenAI ou OpenAI Compatible">
        Selecione **OpenAI** ou **OpenAI Compatible** na lista de provedores.
      </Step>

      <Step title="Preencha a configuração da BetterToken">
        Informe:

        * **Base URL**: `https://www.bettertoken.ai/v1`
        * **API Key**: sua BetterToken API Key
        * **Model**: um **ID de modelo de um provedor compatível** copiado da <a href={"https://bettertoken.ai/pricing"}>model plaza</a>
      </Step>

      <Step title="Reinicie o Hermes Agent">
        Após atualizar a configuração, encerre a sessão atual do Hermes Agent e inicie-a novamente.
      </Step>

      <Step title="Inicie o Hermes Agent">
        ```bash theme={null}
        hermes
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Configuração por CLI">
    Se preferir comandos para copiar e colar, grave a configuração do Hermes Agent diretamente.

    ```bash theme={null}
    hermes config set llm.provider openai
    hermes config set llm.base_url "https://www.bettertoken.ai/v1"
    hermes config set llm.api_key "YOUR_API_KEY"
    hermes config set llm.model "YOUR_MODEL_ID"
    ```

    Substitua `YOUR_API_KEY` pela sua BetterToken API Key e `YOUR_MODEL_ID` por um ID de modelo de um provedor compatível da <a href={"https://bettertoken.ai/pricing"}>model plaza</a>.

    Depois inicie o Hermes Agent:

    ```bash theme={null}
    hermes
    ```
  </Tab>

  <Tab title="Variáveis de ambiente">
    Se não quiser armazenar a API Key na configuração do Hermes Agent, exporte-a no shell atual.

    ```bash theme={null}
    export OPENAI_API_BASE="https://www.bettertoken.ai/v1"
    export OPENAI_API_KEY="YOUR_API_KEY"
    export HERMES_MODEL="YOUR_MODEL_ID"
    hermes
    ```

    Essas variáveis se aplicam somente à sessão atual do shell. Exporte-as novamente em um novo terminal ou adicione-as ao seu perfil de shell.
  </Tab>
</Tabs>

### Migre do OpenClaw

Se você já usa OpenClaw, primeiro verifique se a versão atual do Hermes Agent oferece o comando de migração. Execute uma simulação antes de alterar algo.

```bash theme={null}
hermes claw migrate --dry-run
```

Depois de confirmar a saída, execute a migração:

```bash theme={null}
hermes claw migrate
```

Após a migração, revise a **Base URL**, a API Key e o ID de modelo do Hermes Agent. Eles devem corresponder a `https://www.bettertoken.ai/v1`, à sua BetterToken API Key e a um ID de modelo de um provedor compatível.

## Verifique a conexão

Envie um prompt de teste curto. Se a ferramenta retornar uma resposta sem erro de autenticação ou de ID de modelo, a conexão funciona. Reinicie completamente a ferramenta depois de alterar a configuração.

## Alterne entre modelos

Abra o seletor de modelos ou altere o campo `Model` na configuração. Use o ID de modelo exato da <a href={"https://bettertoken.ai/pricing"}>model plaza</a> e reinicie a sessão atual.

## Erros comuns

| Erro                            | O que verificar                                                          |
| ------------------------------- | ------------------------------------------------------------------------ |
| `401` ou `Unauthorized`         | Verifique a BetterToken API Key e remova espaços no início ou no fim.    |
| `404`                           | Verifique a Base URL e não acrescente um caminho de endpoint específico. |
| `model not found`               | Copie um ID de modelo atual da model plaza.                              |
| As alterações não são aplicadas | Salve a configuração e reinicie completamente a ferramenta.              |

### Solução de problemas

* Se as solicitações falharem ou não retornarem resposta, confirme que **Base URL** é exatamente `https://www.bettertoken.ai/v1`. Não acrescente `/chat/completions` nesse campo.
* Se o Hermes informar que o modelo não existe, confirme que **Model** é um ID de modelo de um provedor compatível da <a href={"https://bettertoken.ai/pricing"}>model plaza</a>.
* Se a autenticação falhar, verifique espaços copiados e confirme que o ID de modelo selecionado vem do **provedor compatível**.
* Se o Hermes continuar usando o modelo antigo após uma alteração, encerre a sessão atual do Hermes Agent e execute `hermes` novamente.
* A BetterToken geralmente não exige `User-Agent` adicional nem cabeçalhos personalizados. Adicione cabeçalhos somente quando o gateway personalizado, roteamento de tenant, observabilidade ou camada de cache exigir explicitamente.

<Note>
  Não envie API Keys reais ao repositório. Para configurações compartilhadas pela equipe, prefira variáveis de ambiente ou configuração local.
</Note>

### FAQ relacionada

* [MCP vs. API Key e Base URL](/pt-br/faq/concepts/mcp-vs-api-key-base-url)
* [O que são model\_provider, base\_url e wire\_api?](/pt-br/faq/codex/model-provider-base-url-wire-api)
* [Como configurar uma API compatível com OpenAI no Cline](/pt-br/faq/cline/openai-compatible-api)
* [Guia de configuração da BetterToken no OpenClaw](/pt-br/ai-tools/openclaw)

## Advanced setup

## Provedores compatíveis

| Provedor | Status              |
| -------- | ------------------- |
| Claude   | Sem suporte         |
| GPT      | Configuração manual |
| Kimi     | Configuração manual |
| GLM      | Configuração manual |

<Note>Os status se aplicam ao método de configuração do BetterToken descrito nesta página.</Note>

<Accordion title="O que significa cada método de configuração">
  * **Configuração manual**: informe a API Key, a Base URL e o Model.
  * **Sem suporte**: ainda não há um método verificado de conexão direta.
</Accordion>

## Detalhes técnicos

<Accordion title="Protocolo, endpoint e campos internos do provedor">
  Esta configuração usa `https://www.bettertoken.ai/v1`. A ferramenta acrescenta o caminho de endpoint compatível com OpenAI. Não adicione `/chat/completions` ou `/responses`, exceto quando um campo específico exigir isso.
</Accordion>