# Configurar um modelo personalizado no WorkBuddy > Configure um modelo personalizado no WorkBuddy em três etapas: escolha Personalizado, informe o URL da API OmniaKey, a chave e o ID do modelo e salve. - Canonical HTML: https://omniakey.com/pt-BR/blog/workbuddy-custom-model-setup - Markdown: https://omniakey.com/pt-BR/blog/workbuddy-custom-model-setup.md - Published: 2026-08-20 (updated 2026-09-21) - Author: Kiki, COO at OmniaKey - Language: pt-BR - Category: API setup - Reading time: 8 min - All posts: https://omniakey.com/blog/llms.txt --- Este guia usa a interface atual do modelo personalizado WorkBuddy. Prepare uma chave OmniaKey API e um ID de modelo exato antes de abrir WorkBuddy. > **O formulário finalizado:** escolha **Personalizado**, insira `https://api.omniakey.com/v1`, cole sua chave OmniaKey API e use um ID de modelo exato, como `deepseek-v4-flash`. O formulário, os detalhes do modelo salvo e o seletor de modelo foram verificados no aplicativo macOS executando WorkBuddy `v5.3.14`. As instruções oficiais da Tencent Cloud exigem pelo menos `v4.22.15` para este recurso. |Campo WorkBuddy|Valor| |-|-| |Provedor|`Custom` no grupo **Outro**| |Endereço de interface|`https://api.omniakey.com/v1`| |Chave API|Uma chave criada em OmniaKey| |Nome do modelo|Por exemplo, `deepseek-v4-flash`| ## Antes de começar, prepare dois itens ### Uma chave OmniaKey API Faça login em OmniaKey e abra a [página Chaves API](https://omniakey.com/pt-BR/dashboard/tokens): 1. Selecione **Criar chave**. 2. Nomeie-o como `WorkBuddy` e defina um limite e uma expiração adequados. 3. Crie-o e copie imediatamente a nova chave. Mantenha a caixa de diálogo chave aberta até colar a credencial em WorkBuddy. Não coloque a chave em capturas de tela, mensagens de bate-papo ou arquivos públicos. A conta também precisa de saldo disponível ou crédito de teste. Criar uma chave cria apenas uma credencial; isso não garante que a conta possa financiar uma solicitação. A mesma chave funciona em outras ferramentas; consulte os guias de [configuração da API do Cherry Studio](https://omniakey.com/pt-BR/blog/cherry-studio-api-setup), [chave API personalizada do Cline](https://omniakey.com/pt-BR/blog/cline-custom-api-key) e [configuração do Claude Code](https://omniakey.com/pt-BR/blog/claude-code-setup). ### Um ID exato do modelo Abra o [catálogo de modelos OmniaKey](https://omniakey.com/pt-BR/models), escolha um modelo atualmente disponível e copie o ID do modelo mostrado na página. Para um primeiro teste, use: ```text deepseek-v4-flash ``` O ID deve corresponder exatamente. Não insira o nome de exibição `DeepSeek V4 Flash`, remova hífens ou invente um alias mais curto. ## Etapa 1: Abra Adicionar modelo Inicie WorkBuddy e abra: ```text System Settings → Models → + Add model ``` Na página Modelos, selecione **+ Adicionar modelo** no canto superior direito. ![Página de configurações de modelos WorkBuddy com o botão Adicionar modelo no canto superior direito](https://omniakey.com/_img/blog/workbuddy-custom-model-setup/01-open-model-settings.2eba6570.1000.webp) _Etapa 1: Configurações do sistema → Modelos → + Adicionar modelo._ Você também pode entrar na parte inferior de uma nova tarefa: ```text Model picker → + Configure custom model ``` Se nenhuma entrada estiver disponível, atualize WorkBuddy para a versão `v4.22.15` ou posterior. As instruções atuais da Tencent Cloud exigem pelo menos esta versão para a interface. ## Etapa 2: Escolha Personalizado e preencha quatro campos Preencha o formulário de cima para baixo. ### 1. Escolha o provedor personalizado Abra o menu Provedor e selecione: ```text Custom ``` Em `v5.3.14`, ele aparece no grupo **Outro**. Não escolha o OpenAI integrado, o Tencent Cloud Token Plan ou outro provedor porque esses perfis não usam o endereço de interface OmniaKey. ![Opção de provedor personalizado na parte inferior do menu Provedor WorkBuddy](https://omniakey.com/_img/blog/workbuddy-custom-model-setup/02-choose-custom-provider.fabcb941.560.webp) _Etapa 2: vá até a parte inferior do menu Provedor e escolha Personalizado em Outro._ ### 2. Insira o endereço através de `/v1` Em **Endereço de interface** ou **Base URL**, insira exatamente: ```text https://api.omniakey.com/v1 ``` > **Não copie o espaço reservado cinza.** Ele mostra um exemplo que termina em `/v1/chat/completions`, mas OmniaKey usa Base URL `https://api.omniakey.com/v1` neste campo. ### 3. Cole a chave API Cole a chave que você copiou de OmniaKey em **API Key**. Não adicione aspas, espaços em branco ou a palavra `Bearer`; insira apenas o valor da chave. ### 4. Insira o nome do modelo Em **Nome do modelo** ou **Model ID**, insira o ID exato do catálogo: ```text deepseek-v4-flash ``` O formulário principal agora deve ser: ```text Provider: Custom Interface address: https://api.omniakey.com/v1 API Key: [your OmniaKey API key] Model name: deepseek-v4-flash ``` ![Formulário de modelo personalizado WorkBuddy preenchido com o endereço da interface OmniaKey e o nome do modelo deepseek-v4-flash](https://omniakey.com/_img/blog/workbuddy-custom-model-setup/03-fill-omniakey-fields.addb54d9.560.webp) _Exemplo concluído. A chave API está intencionalmente em branco na captura de tela; cole sua própria chave OmniaKey ao configurar WorkBuddy._ Para o primeiro teste de conexão, deixe os campos restantes com seus padrões e certifique-se de que **Protocolo personalizado** esteja desativado. Em `v5.3.14`, um novo formulário começa com Tool calling ativado, entrada de imagem desativada, modo de raciocínio desativado, protocolo personalizado desativado e limites de entrada e saída padrão do provedor. Uma predefinição `deepseek-v4-flash` verificada aparece abaixo. ## Etapa 3: Salve, selecione o modelo e teste-o Selecione **Salvar** e retorne para uma nova tarefa. Abra o seletor de modelo na parte inferior, encontre a seção de modelo personalizado e escolha `deepseek-v4-flash`. Envie uma breve mensagem de teste: ```text Reply with exactly: Connection successful ``` Uma resposta normal confirma quatro partes da configuração de uma só vez: 1. WorkBuddy salvou o provedor customizado. 2. O Base URL está correto. 3. A chave API é aceita e possui crédito utilizável. 4. A chave pode acessar o ID do modelo selecionado. Por fim, abra [OmniaKey Usage](https://omniakey.com/pt-BR/dashboard/usage) e confirme se a chamada aparece com o modelo esperado. Isso fecha o ciclo de verificação de WorkBuddy para OmniaKey. Se o modelo salvo não aparecer imediatamente, feche e reabra o seletor. Saia totalmente e reinicie WorkBuddy se ainda não aparecer. ## Configurações avançadas recomendadas para o primeiro teste Não altere vários controles de capacidade antes que o chat básico funcione. Um novo modelo personalizado em WorkBuddy `v5.3.14` começa com: |Opção|Padrão do novo formulário| |-|-| |Tool calling|Ligado| |Entrada de imagem|Desligado| |Modo de raciocínio|Desligado| |Protocolo personalizado|Desligado| |Limites de entrada e saída|Padrões do provedor| Use esses padrões para verificar primeiro o URL, a chave e o nome do modelo. Em seguida, ajuste os recursos do modelo. ### Predefinição `deepseek-v4-flash` verificada O modelo salvo e as respostas locais bem-sucedidas usaram esta configuração: |Opção|Configuração `deepseek-v4-flash`| |-|-| |Tool calling|Desligado| |Entrada de imagem|Desligado| |Modo de raciocínio|**Ativado**| |Apenas raciocínio|Desligado| |Permitir desabilitar o raciocínio|**Ativado**| |Protocolo personalizado|**Desligado**| |Esforço de raciocínio padrão|`Auto (use request-layer default)`| |Esforços de raciocínio apoiados|Deixe Baixo, Médio, Alto, Extra Alto e Máximo desmarcados| |Limites de entrada e saída|Padrões do provedor| WorkBuddy revela apenas o raciocínio, permite desabilitar o raciocínio e controles de esforço após o modo de raciocínio ser ativado. Deixe o esforço em Auto para o primeiro teste. ### Quando ativar a chamada de ferramenta Ative **Tool calling** quando WorkBuddy precisar ler arquivos, usar conectores ou executar tarefas de agente. O modelo também deve suportar chamadas de ferramentas estruturadas. `deepseek-v4-flash` atualmente tem suporte a ferramentas no catálogo OmniaKey, portanto, habilite-o após o bate-papo básico funcionar e comece com uma tarefa somente leitura. Ele pode permanecer desativado para um teste de bate-papo somente com conexão. ### Quando ativar a entrada de imagem Habilite-o apenas para um modelo explicitamente marcado como aceitando imagens. Um switch cliente não pode adicionar capacidade de visão a um modelo somente texto. ### Quando ativar o modo de raciocínio Ative-o quando a documentação do catálogo ou do modelo listar explicitamente o raciocínio, o pensamento ou um modo semelhante. Manter o esforço automático e Permitir desabilitar o raciocínio. Não adicione valores de esforço não suportados e não torne o modo somente raciocínio o padrão para tarefas comuns. ## Adicionando outro modelo personalizado WorkBuddy Não substitua uma entrada de modelo funcional. Abra **Adicionar modelo** novamente, mantenha o mesmo URL OmniaKey e chave API, substitua apenas o ID exato do modelo e salve-o como outro modelo personalizado. Verifique um modelo antes de adicionar o próximo. Quando surge um problema, fica claro qual entrada salva o introduziu. ## Solução de problemas por sintoma ### A configuração do modelo personalizado está ausente Verifique primeiro a versão do WorkBuddy. Atualize para `v4.22.15` ou posterior e procure no seletor de modelo de nova tarefa ou em **Configurações do sistema → Modelos**. ### HTTP 401, Chave API não autorizada ou inválida Copie a chave OmniaKey novamente. Verifique se há espaços em branco e certifique-se de não colar `Bearer` neles. Confirme se a chave está ativada e não expirada e se o saldo da conta e o limite da chave podem ser usados. Alterar o ID do modelo não corrige `401`; a autenticação falhou antes que a seleção do modelo fosse importante. ### HTTP 404 ou endpoint não encontrado O endereço deve ser exatamente: ```text https://api.omniakey.com/v1 ``` Não use o domínio simples, duplique `/v1` ou anexe `/chat/completions`. Certifique-se também de que **Protocolo personalizado** esteja desativado. ### Modelo não encontrado ou `UNKNOWN_MODEL` Copie novamente o ID do [catálogo de modelos ativos](https://omniakey.com/pt-BR/models). Um nome de exibição, um alias adivinhado ou um ID retirado não é um ID de modelo atual válido. ### O bate-papo funciona, mas as ferramentas falham A conexão do modelo básico já está funcionando. Verifique a chave Tool calling do WorkBuddy e a capacidade da ferramenta do modelo. Inserir novamente a chave ou URL API não adicionará suporte à ferramenta. ### Falha na entrada de imagem Ambas as condições devem ser verdadeiras: o modelo suporta imagens e o controle de entrada de imagem do WorkBuddy está habilitado. ### O modelo está faltando após salvar Confirme que você selecionou **Salvar** e reabra o seletor de modelo. Reinicie WorkBuddy se necessário. Se a entrada de configuração não estiver disponível, verifique novamente a versão do cliente. ## Perguntas frequentes ### Qual URL OmniaKey WorkBuddy deve usar? Use apenas `https://api.omniakey.com/v1`. É um Base URL; WorkBuddy anexa o caminho da operação. ### Preciso de um arquivo `models.json`? Não. Este guia segue a interface atual **Configurar modelo personalizado**. As instruções mais antigas do arquivo de configuração local descrevem um caminho de configuração diferente. ### Posso configurar GPT, Claude, Gemini ou outro modelo? Sim, quando o modelo estiver atualmente listado em OmniaKey e suportar a rota compatível com OpenAI. Mantenha o mesmo URL e use o ID exato do modelo de catálogo. ### O MCP está configurado neste formulário? Não. Este formulário configura o modelo API. MCP e conectores são configurações WorkBuddy separadas. Estabeleça uma resposta básica do modelo antes de adicionar essas ferramentas. ## Referências verificadas - [Tencent Cloud: configurar e usar WorkBuddy](https://cloud.tencent.com/document/product/1823/130064) - [Referência OmniaKey OpenAI compatível com API](https://docs.omniakey.com/en/api/openai-compatible) - [Catálogo de modelos vivos OmniaKey](https://omniakey.com/pt-BR/models)