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

# Claude Code

> Use a AIHubMix com o Claude Code: chame modelos de varios provedores com uma unica chave de API, roteamento estavel e faturamento unificado.

## Inicio rapido

Este guia ajuda voce a usar o Claude Code com a AIHubMix em poucos minutos.

### 1. Instalar o Claude Code

#### Instalacao local

<CodeGroup>
  ```shellscript macOS theme={null}
  curl -fsSL https://claude.ai/install.sh | bash
  ```

  ```shellscript Windows theme={null}
  irm https://claude.ai/install.ps1 | iex
  ```
</CodeGroup>

#### Instalar via npm

Voce precisa do [Node.js 18 ou superior](https://nodejs.org/en/download/).

```shellscript theme={null}
npm install -g @anthropic-ai/claude-code
```

### 2. Configurar a API da AIHubMix

Para acessar os modelos da AIHubMix pela API compativel com Anthropic, configure as seguintes variaveis de ambiente.

1. Defina `ANTHROPIC_BASE_URL` como `https://aihubmix.com`
2. Defina `ANTHROPIC_AUTH_TOKEN` com a chave de API obtida na [plataforma AIHubMix](https://console.aihubmix.com/token)
3. Defina `ANTHROPIC_MODEL` com um modelo Claude suportado na [lista de modelos](https://aihubmix.com/models), por exemplo `claude-sonnet-4-5`.

<Warning>
  `AIHUBMIX_API_KEY` e apenas um placeholder. Substitua pela sua chave real, que normalmente comeca com `sk-`. Se voce copiar exatamente assim, o Claude Code tratara esse texto como a chave real e retornara `401 invalid key: AIHUBMIX_API_KEY`.
</Warning>

<Tabs>
  <Tab title="macOS">
    1. Execute o comando abaixo no terminal para verificar o Shell padrao.

    ```shellscript theme={null}
    echo $SHELL
    ```

    2. Configure as variaveis de ambiente de acordo com seu Shell:

    <CodeGroup>
      ```shellscript Zsh theme={null}
      # Substitua <AIHUBMIX_API_KEY> pela sua chave real da AIHubMix
      echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.zshrc
      echo 'export ANTHROPIC_AUTH_TOKEN="<AIHUBMIX_API_KEY>"' >> ~/.zshrc
      echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.zshrc
      ```

      ```shellscript Bash theme={null}
      # Substitua <AIHUBMIX_API_KEY> pela sua chave real da AIHubMix
      echo 'export ANTHROPIC_BASE_URL="https://aihubmix.com"' >> ~/.bash_profile
      echo 'export ANTHROPIC_AUTH_TOKEN="<AIHUBMIX_API_KEY>"' >> ~/.bash_profile
      echo 'export ANTHROPIC_MODEL="claude-sonnet-4-5"' >> ~/.bash_profile
      ```
    </CodeGroup>

    3. Recarregue a configuracao.

    <CodeGroup>
      ```shellscript Zsh theme={null}
      source ~/.zshrc
      ```

      ```shellscript Bash theme={null}
      source ~/.bash_profile
      ```
    </CodeGroup>

    4. Abra um novo terminal e confira as variaveis.

    ```shellscript theme={null}
    echo $ANTHROPIC_BASE_URL
    test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
    echo $ANTHROPIC_MODEL
    ```
  </Tab>

  <Tab title="Windows">
    No Windows, voce pode definir a Base URL e a [chave de API](https://console.aihubmix.com/token) da AIHubMix usando CMD ou PowerShell.

    <Tabs>
      <Tab title="CMD">
        1. Execute estes comandos no CMD.

        ```shellscript theme={null}
        REM Substitua <AIHUBMIX_API_KEY> pela sua chave real da AIHubMix
        setx ANTHROPIC_AUTH_TOKEN "<AIHUBMIX_API_KEY>"
        setx ANTHROPIC_BASE_URL "https://aihubmix.com"
        setx ANTHROPIC_MODEL "claude-sonnet-4-5"
        ```

        2. Abra uma nova janela do CMD e confira as variaveis.

        ```shellscript theme={null}
        if defined ANTHROPIC_AUTH_TOKEN echo ANTHROPIC_AUTH_TOKEN is set
        echo %ANTHROPIC_BASE_URL%
        echo %ANTHROPIC_MODEL%
        ```
      </Tab>

      <Tab title="PowerShell">
        1. Execute estes comandos no PowerShell.

        ```shellscript theme={null}
        # Substitua <AIHUBMIX_API_KEY> pela sua chave real da AIHubMix
        [Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "<AIHUBMIX_API_KEY>", [EnvironmentVariableTarget]::User)
        [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://aihubmix.com", [EnvironmentVariableTarget]::User)
        [Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-5", [EnvironmentVariableTarget]::User)
        ```

        2. Abra uma nova janela do PowerShell e confira as variaveis.

        ```shellscript theme={null}
        if ($env:ANTHROPIC_AUTH_TOKEN) { "ANTHROPIC_AUTH_TOKEN is set" }
        echo $env:ANTHROPIC_BASE_URL
        echo $env:ANTHROPIC_MODEL
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

<Note>
  Se voce pretende gerenciar o Claude Code pelo CC Switch, evite definir globalmente `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` ou `ANTHROPIC_MODEL` separadamente. Variaveis de ambiente do sistema ou do usuario podem sobrescrever a configuracao do Provider gravada pelo CC Switch, fazendo o Claude Code continuar usando uma chave ou um modelo antigo.
</Note>

### 3. Verificar a configuracao

Depois de configurar as variaveis de ambiente ou o CC Switch, execute primeiro uma requisicao minima para confirmar que a chave, o modelo e o endpoint compativel com Anthropic estao disponiveis antes de iniciar uma sessao longa.

<CodeGroup>
  ```bash macOS/Linux theme={null}
  curl https://aihubmix.com/v1/messages \
    -H "content-type: application/json" \
    -H "anthropic-version: 2023-06-01" \
    -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
    -d '{
      "model": "claude-sonnet-4-5",
      "max_tokens": 16,
      "messages": [{"role": "user", "content": "1+1, output only the answer"}]
    }'
  ```

  ```powershell Windows theme={null}
  curl.exe https://aihubmix.com/v1/messages `
    -H "content-type: application/json" `
    -H "anthropic-version: 2023-06-01" `
    -H "x-api-key: $env:ANTHROPIC_AUTH_TOKEN" `
    -d "{\"model\":\"claude-sonnet-4-5\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"1+1, output only the answer\"}]}"
  ```
</CodeGroup>

Se a requisicao retornar `200` e o conteudo for `2`, sua chave AIHubMix e o modelo Claude estao disponiveis. Em seguida, execute:

```bash theme={null}
claude -p "1+1, output only the answer" --model claude-sonnet-4-5
```

Se retornar `2`, o Claude Code esta configurado corretamente de ponta a ponta.

### 4. Comecar

Depois de concluir a configuracao, entre no diretorio do seu projeto e execute `claude` no terminal.

```bash theme={null}
$ cd /path/your-project
> claude
```

Se a inicializacao mostrar `Not logged in · Please run /login`, ou abrir opcoes de login da Anthropic, normalmente o Claude Code nao leu uma configuracao AIHubMix utilizavel, ou o onboarding inicial ainda nao foi concluido. Primeiro confirme que a requisicao minima acima retorna `2`, e verifique se variaveis globais antigas `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` ou `ANTHROPIC_MODEL` estao sobrescrevendo a configuracao atual. Se a chave estiver funcionando mas o Claude Code ainda entrar no fluxo de login, siga estes passos para pular o onboarding inicial:

<img src="https://mintcdn.com/aihubmix/CJXK0MqAoj3CTV61/public/en/cc-7.jpg?fit=max&auto=format&n=CJXK0MqAoj3CTV61&q=85&s=b7d4c88d3c502ff2841970bdae43955d" alt="Tela inicial do Claude Code com opcoes de login ou configuracao" width="1622" height="438" data-path="public/en/cc-7.jpg" />

1. Localize o arquivo `.claude.json` no diretorio do usuario:
   * macOS / Linux: `~/.claude.json`
   * Windows: `C:\Users\%USERNAME%\.claude.json`
2. Defina `hasCompletedOnboarding` como `true`.

```json theme={null}
{
  "hasCompletedOnboarding": true
}
```

3. Salve o arquivo e execute `claude` novamente.

#### (Opcional) Outros metodos de configuracao de modelo

O Claude Code oferece os seguintes metodos, **em ordem de prioridade da maior para a menor**. Configuracoes de maior prioridade substituem as de menor prioridade.

1. **Durante uma conversa:** use `/model <nome_do_modelo>` para trocar temporariamente de modelo.

```text theme={null}
/model claude-sonnet-4-5
```

2. **Ao iniciar o Claude Code:** use `claude --model <nome_do_modelo>` para uma unica sessao.

```text theme={null}
claude --model claude-sonnet-4-5
```

3. **Variaveis de ambiente:** configure niveis de modelo conforme a complexidade da tarefa.

```shellscript theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
```

* `ANTHROPIC_DEFAULT_OPUS_MODEL`: raciocinio complexo e arquitetura.
* `ANTHROPIC_DEFAULT_SONNET_MODEL`: codificacao e implementacao de funcionalidades.
* `ANTHROPIC_DEFAULT_HAIKU_MODEL`: verificacoes simples, busca de arquivos e tarefas leves.

4. **Arquivo `settings.json`:** escreva a configuracao no arquivo de usuario do Claude Code, como `~/.claude/settings.json` no macOS/Linux ou `C:\Users\%USERNAME%\.claude\settings.json` no Windows, ou em uma configuracao de projeto.

<Note>
  **Configuracao de fallback:** se `/model`, argumentos de inicializacao, variaveis de ambiente ou CC Switch nao surtirem efeito, ou se o Claude Code ainda ler um modelo antigo, edite `settings.json` diretamente. O exemplo abaixo define tanto `ANTHROPIC_MODEL` quanto o campo superior `model`, mantendo nomes de modelo para os slots Opus, Sonnet e Haiku.
</Note>

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "<AIHUBMIX_API_KEY>",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gemini-3.5-flash",
    "ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "gemini-3.5-flash",
    "ANTHROPIC_MODEL": "gpt-5.5"
  },
  "model": "gpt-5.5"
}
```

Substitua `<AIHUBMIX_API_KEY>` pela sua chave real. Depois de salvar, reinicie o Claude Code e use `/models` para conferir os modelos disponiveis na sessao atual.

## Como configurar via CC Switch?

1. Execute o CC Switch, selecione **Claude Code** no lado esquerdo e clique em "Add Vendor".

<img src="https://mintcdn.com/aihubmix/nDfXW_uQnlv66zYd/public/en/cc-1.jpg?fit=max&auto=format&n=nDfXW_uQnlv66zYd&q=85&s=3820dc907ce471235e6f4614f27326cc" alt="Pagina inicial do CC Switch com a entrada Add Vendor" width="2072" height="1366" data-path="public/en/cc-1.jpg" />

2. Selecione "AiHubMix" na lista de presets. Confirme que voce esta configurando o Provider do Claude Code.

<img src="https://mintcdn.com/aihubmix/nDfXW_uQnlv66zYd/public/en/cc-2.jpg?fit=max&auto=format&n=nDfXW_uQnlv66zYd&q=85&s=ed00ce20c63ecdca0b46ac17541717b9" alt="Lista de providers do CC Switch com AiHubMix selecionado" width="2066" height="1372" data-path="public/en/cc-2.jpg" />

3. Insira sua chave real no campo "API Key".

<img src="https://mintlify.s3.us-west-1.amazonaws.com/aihubmix/public/en/cc-3.jpg" alt="Formulario de configuracao da AIHubMix no CC Switch com campo API Key" className="hidden dark:block" />

<img src="https://mintcdn.com/aihubmix/nDfXW_uQnlv66zYd/public/en/cc-3.png?fit=max&auto=format&n=nDfXW_uQnlv66zYd&q=85&s=b765a38f94a800d44ab3035aab2d7249" alt="Formulario de configuracao da AIHubMix no CC Switch com campo API Key" className="dark:hidden" width="2064" height="1372" data-path="public/en/cc-3.png" />

4. Depois de concluir a configuracao, use primeiro `claude-sonnet-4-5` como ID do modelo e clique em "Add" para salvar. Depois que o health check passar, voce pode mudar para outros modelos Claude no Claude Code com `/models` ou `/model`.

<img src="https://mintcdn.com/aihubmix/nDfXW_uQnlv66zYd/public/en/cc-4.png?fit=max&auto=format&n=nDfXW_uQnlv66zYd&q=85&s=9cbf56912396982bb4d356b7217e0a59" alt="Exemplo de configuracao de modelo no CC Switch" className="dark:hidden" width="2070" height="1370" data-path="public/en/cc-4.png" />

5. Volte para a pagina inicial, selecione "AiHubMix" na lista de providers e clique em "Start".

<img src="https://mintcdn.com/aihubmix/nDfXW_uQnlv66zYd/public/en/cc-5.jpg?fit=max&auto=format&n=nDfXW_uQnlv66zYd&q=85&s=a6426cbd5a83543f73d150c8dfa33e8f" alt="Pagina inicial do CC Switch com AiHubMix selecionado e iniciado" width="2070" height="1368" data-path="public/en/cc-5.jpg" />

<Warning>
  Se o CC Switch mostrar conflito de variaveis de ambiente do sistema, trate primeiro `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL` e `ANTHROPIC_MODEL`. Essas variaveis globais podem sobrescrever a configuracao atual do Provider. Valores placeholder como `ANTHROPIC_AUTH_TOKEN=AIHUBMIX_API_KEY` causam falha direta de autenticacao. Depois de confirmar que voce nao precisa mais das variaveis globais, exclua os itens conflitantes no CC Switch ou remova manualmente as variaveis de sistema/usuario e reinicie o terminal.
</Warning>

## Como configurar pelo plugin do VS Code?

1. Execute o VS Code e instale o plugin.

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.44.03.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=7fd42add3df2e072c3d8d85eb19c785d" alt="Visualizacao Extensions do VS Code instalando o plugin Claude Code" width="1958" height="724" data-path="images/iShot_2026-03-25_11.44.03.jpg" />
</Frame>

2. Pressione `Ctrl + Shift + P` ou `Cmd + Shift + P`, e digite `Settings`.

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.47.48.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=c7b448a36e1886a4a1cdc9103f3844f6" alt="Paleta de comandos do VS Code abrindo Settings" width="1772" height="976" data-path="images/iShot_2026-03-25_11.47.48.jpg" />
</Frame>

3. Pesquise `Claude Code` e abra `Claude Code: Environment Variable` -> `Edit in settings.json`.

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.49.37.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=3f5a87bc619bcb552eb4ed78da6527b6" alt="Busca de variaveis de ambiente do Claude Code no VS Code" width="1940" height="1248" data-path="images/iShot_2026-03-25_11.49.37.jpg" />
</Frame>

4. Preencha as informacoes da AIHubMix em `claudeCode.environmentVariables`.

<Frame>
  <img src="https://mintcdn.com/aihubmix/XPAbnoWWzjetSWAU/images/iShot_2026-03-25_11.53.07.jpg?fit=max&auto=format&n=XPAbnoWWzjetSWAU&q=85&s=9a1355dac10acd90f0834f2f091ac3a7" alt="Exemplo de settings.json do VS Code para variaveis do Claude Code" width="1156" height="304" data-path="images/iShot_2026-03-25_11.53.07.jpg" />
</Frame>

## [Wechat-Agent-SDK](https://github.com/AIhubmix/wechat-agent-sdk)

Com chamadas simples de API, integre agentes de IA como Claude Code, Codex e Kimi ao WeChat. O SDK suporta o protocolo ACP, roda localmente sem servidor ou banco de dados e inclui retomada e reconexao automatica.

> Link de instalacao: [https://github.com/AIhubmix/wechat-agent-sdk](https://github.com/AIhubmix/wechat-agent-sdk)

## FAQ

### P: O que fazer se aparecer um erro de autenticacao `401`?

`401` significa que a requisicao nao passou na autenticacao, mas a causa exata depende da mensagem completa:

* `No token provided`: nenhuma chave foi enviada. Abra o Claude Code, digite `/config`, encontre `Use custom API key` e confira o token.
* `invalid key: AIHUBMIX_API_KEY`: provavelmente o placeholder do exemplo foi copiado sem alteracao. Copie novamente sua chave real no console da AIHubMix e atualize `ANTHROPIC_AUTH_TOKEN`.
* `this key is not enabled`: a requisicao chegou a AIHubMix, mas a chave atual nao esta habilitada ou nao tem permissao. Verifique no [console da AIHubMix](https://console.aihubmix.com/token) se a chave esta ativa, nao expirou, tem cota e pode chamar o modelo Claude selecionado.

<img src="https://mintcdn.com/aihubmix/xEVowd6r7MS_NCso/public/en/cc-6.png?fit=max&auto=format&n=xEVowd6r7MS_NCso&q=85&s=48a535276ef104833be9d71a428b0cd9" alt="Tela de configuracao do Claude Code para verificar a chave API personalizada" width="1220" height="760" data-path="public/en/cc-6.png" />

No Windows, confira tambem se valores antigos ficaram em variaveis de usuario ou de sistema:

```powershell theme={null}
[Environment]::GetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL", "User")
[Environment]::GetEnvironmentVariable("ANTHROPIC_MODEL", "User")
```

Se voce usa CC Switch, remova essas variaveis globais `ANTHROPIC_*` para que o Provider atual do CC Switch assuma a configuracao.

Observacao: `/v1/models` pode retornar uma lista de modelos mesmo sem uma chave valida, portanto nao use isso para decidir se a chave funciona. Use a requisicao minima da secao "Verificar a configuracao". Se ela retornar `200` e `2`, a chave e o modelo estao utilizaveis. Em seguida, reinicie o Claude Code ou inicie-o pelo CC Switch.

### P: O que fazer com `400 Incorrect model ID` ou `Bad request (400)`?

Normalmente isso significa que a requisicao chegou ao provedor, mas o ID do modelo esta incorreto, o nome do modelo nao corresponde a interface ou a chave atual nao tem permissao para chamar esse modelo. Copie novamente o ID completo na [lista de modelos da AIHubMix](https://aihubmix.com/models) e confira ortografia, maiusculas/minusculas e familia do modelo.

Se voce configura pelo CC Switch, volte ao Provider correspondente, atualize o ID do modelo, salve e reinicie o Claude Code. Se o erro continuar, use primeiro um modelo Claude confirmado como disponivel na lista para concluir o health check e depois troque para o modelo desejado.

### P: Depois de instalar no macOS, aparece `zsh: command not found: claude`

A CLI do Claude esta instalada, mas o diretorio executavel nao foi adicionado ao `PATH`.

1. Confira o caminho de instalacao. O script oficial normalmente instala em um destes diretorios:

* `~/.claude/bin`
* `~/.local/bin`

```bash theme={null}
ls -l ~/.claude/bin
or
ls -l ~/.local/bin | grep claude
```

2. Adicione o diretorio ao `PATH`.

#### Caso A: instalado em `~/.claude/bin`

```shellscript theme={null}
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

#### Caso B: instalado em `~/.local/bin`

```shellscript theme={null}
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

3. Verifique:

```shellscript theme={null}
which claude
claude -v
```

Se o caminho e a versao de `claude` aparecerem, a instalacao esta correta.

### P: O Claude Code nao consegue se conectar aos servicos Anthropic

Depois de atualizar o Claude Code, falhas de conexao ou autenticacao geralmente estao relacionadas a mudanca do nome do header de autenticacao. Versoes novas esperam `ANTHROPIC_AUTH_TOKEN` em vez de `ANTHROPIC_API_KEY`. O valor da chave nao muda; atualize apenas o nome da variavel e recarregue a configuracao.

## Mais recursos

* [Github](https://github.com/inferera/aihubmix/blob/main/packages/claude-code/README.md)
* [Pacote npm](https://www.npmjs.com/package/@aihubmix/claude-code)
* [Melhores praticas oficiais](https://www.anthropic.com/engineering/claude-code-best-practices)
* [Guia oficial de configuracao](https://docs.anthropic.com/en/docs/claude-code/settings#settings-files)

Bom desenvolvimento!

Last updated: 2026-06-10