Os tokens de acesso do Codex são credenciais do espaço de trabalho do ChatGPT cujo escopo se limita às permissões do Codex. Eles usam uma identidade do espaço de trabalho do ChatGPT para autenticar fluxos de trabalho locais confiáveis e não interativos, incluindo execuções da CLI do Codex e automações que usam o App Server. Use esses tokens quando um script, uma tarefa agendada ou um executor de CI precisar de acesso local em execuções recorrentes.
Atualmente, os espaços de trabalho do ChatGPT Business e do ChatGPT Enterprise oferecem suporte aos tokens de acesso do Codex.
Crie tokens de acesso pessoais no console de administração do ChatGPT, em Tokens de acesso. Cada token pertence ao usuário que o criou e ao espaço de trabalho desse usuário no ChatGPT. Os tokens funcionam como identidades de agente em fluxos de trabalho programáticos locais. Para saber mais sobre tokens criados na página de detalhes de uma identidade não humana dedicada do espaço de trabalho, consulte Contas de serviço.
Se uma chave de API da plataforma atende às necessidades da sua automação, continue usando a autenticação por chave de API. Use tokens de acesso do Codex quando um fluxo de trabalho local confiável precisar especificamente de acesso ao espaço de trabalho do ChatGPT, de direitos de uso gerenciados pelo espaço de trabalho ou de controles empresariais.
Precisa acionar, pelo seu próprio sistema, um agente publicado no espaço de trabalho do ChatGPT? Esse fluxo exige acesso a Agentes do espaço de trabalho. Um token exclusivo do Codex não pode autenticar chamadas que acionam agentes do espaço de trabalho. Se a caixa de diálogo do token mostrar Escopos, selecione Agentes do espaço de trabalho para acionar um agente e Codex para automações do Codex. Conceda vários escopos somente quando o fluxo de trabalho exigir cada um deles. Consulte Autenticação com tokens de acesso de agentes do espaço de trabalho.
Como funcionam os tokens de acesso
Use um token de acesso quando a CLI do Codex ou um cliente do App Server precisar ser executado sem que um usuário faça login pelo navegador. O token representa o usuário do espaço de trabalho do ChatGPT que o criou. Assim, as execuções podem usar as permissões desse usuário e aparecer nos dados de governança do espaço de trabalho.
O cliente verifica o token no início de cada execução e vincula a execução à identidade correspondente no espaço de trabalho. Trate o token como qualquer outro segredo de automação. Armazene-o em um gerenciador de segredos, evite que apareça nos logs e faça a rotação conforme a política da sua organização.
Use tokens de acesso para:
- Tarefas de
codex execexecutadas por automações confiáveis. - Scripts locais que precisam executar a CLI do Codex repetidamente, sem interação do usuário.
- Automações confiáveis que usam o App Server.
- Fluxos de trabalho empresariais que associam o uso a um usuário do espaço de trabalho do ChatGPT em vez de associá-lo a uma chave de API da organização.
Principais riscos a evitar:
- Vazamento de segredos: qualquer pessoa que tenha o token pode iniciar execuções locais pela CLI do Codex ou por um cliente do App Server usando a identidade de quem criou o token. Armazene os tokens em um gerenciador de segredos, evite que apareçam nos logs e faça a rotação conforme a política da sua organização.
- Executores não confiáveis: ambientes públicos de CI, pull requests de forks ou máquinas compartilhadas podem expor tokens a pessoas de fora do espaço de trabalho. Use tokens de acesso somente em executores confiáveis.
- Identidades compartilhadas: quando equipes sem relação entre si reutilizam o token de uma pessoa, fica mais difícil identificar os responsáveis e rastrear ações em auditorias. Crie tokens para quem é responsável por um fluxo de trabalho específico.
- Credenciais obsoletas: tokens com prazo de validade longo podem continuar ativos depois que o fluxo de trabalho mudar. Prefira tokens com validade limitada e revogue os que deixarem de ser usados.
- Escopo ou tipo de credencial incorreto: as automações do Codex exigem acesso ao Codex, o acionamento de agentes do espaço de trabalho exige acesso a Agentes do espaço de trabalho e as chamadas à API da OpenAI em geral exigem chaves de API da plataforma. Se a opção Escopos aparecer, conceda apenas as permissões necessárias para o fluxo de trabalho.
Habilitar a criação de tokens de acesso
Nas configurações do espaço de trabalho, use a permissão de tokens de acesso para permitir que membros autorizados criem tokens.
A permissão de tokens de acesso controla a criação de tokens. Ela não concede acesso ao aplicativo ChatGPT para desktop, à CLI do Codex ou à extensão para IDE. Também não altera o tipo de licença do membro, sua função predefinida no espaço de trabalho nem seu perfil de permissões de execução local. Os fluxos de trabalho da CLI do Codex e do App Server autenticados por token também exigem que o usuário tenha permissão para usar o Codex localmente.
Para entender a relação entre esses controles, consulte Funções e permissões do espaço de trabalho.
- Peça a um proprietário do espaço de trabalho que abra Configurações do espaço de trabalho > Permissões e funções.
- Se a seção Tokens de acesso aparecer, habilite Permitir que os usuários criem tokens de acesso pessoais. Se essa seção não estiver disponível, habilite Permitir que os membros usem tokens de acesso do Codex em Codex e Work locais ou Codex local.
- Habilite a permissão correspondente de uso local do Codex para o responsável pelo fluxo de trabalho: Permitir que os membros usem o Codex e o Work localmente em Codex e Work locais, ou Permitir que os membros usem o Codex localmente em Codex local. Quando Work local tem uma seção própria, a permissão Usar o Work localmente controla o acesso ao modo Work e não é necessária para os tokens do Codex.
Permita a criação de tokens de acesso apenas por pessoas ou responsáveis por serviços que saibam onde o token será armazenado, em qual automação será usado e quando deverá ser substituído.
Desabilitar a permissão de uso local do Codex suspende os tokens ativos do Codex que pertencem aos membros afetados, sem revogá-los. Restaurar o acesso local ao Codex reativa esses tokens. Revogue os tokens quando for necessário encerrar o acesso de forma permanente.
Definir um prazo máximo de validade para os tokens de acesso
Um proprietário do espaço de trabalho pode definir o prazo máximo de validade que os membros podem escolher para novos tokens de acesso. Abra Configurações do espaço de trabalho > Permissões e funções. Se a seção Tokens de acesso aparecer, defina nela o Prazo máximo de validade dos tokens de acesso. Caso contrário, procure essa configuração em Codex e Work locais ou Codex local.
O limite se aplica aos novos tokens de acesso. Os tokens existentes mantêm o prazo de validade atual.
Criar um token de acesso
Na página Tokens de acesso, dê um nome ao token, confira os escopos de produto disponíveis e escolha um prazo de validade adequado.
- Acesse Tokens de acesso.
- Selecione Criar.
- Insira um nome descritivo, como
release-ciounightly-docs-check.
- Se a caixa de diálogo mostrar Escopos, selecione Codex. Selecione Agentes do espaço de trabalho somente se o mesmo fluxo de trabalho também precisar acionar um agente do espaço de trabalho. Se não houver um seletor de escopo, o token criado será exclusivo do Codex.
- Escolha um prazo de validade limitado, como 7, 30, 60 ou 90 dias. Tokens de acesso pessoais com escopos definidos devem ter data de expiração. Uma versão anterior da caixa de diálogo para tokens exclusivos do Codex pode oferecer a opção Sem expiração. Evite essa opção, a menos que sua organização aprove seu uso e faça a rotação do token conforme um cronograma definido.
- Selecione Criar.
- Copie imediatamente o token de acesso gerado. Depois de fechar a caixa de diálogo, você não poderá visualizá-lo novamente.
- Armazene o token no gerenciador de segredos ou no repositório de segredos do seu ambiente de CI.
O prazo mínimo de validade personalizado é de um dia. Tokens revogados ou expirados não podem iniciar novas execuções autenticadas.
Usar um token de acesso com a CLI do Codex
Se a caixa de diálogo de criação do token indicar uma versão obrigatória da CLI do Codex, atualize a CLI para essa versão ou uma mais recente antes de usar o token.
Para automações efêmeras, armazene o token em CODEX_ACCESS_TOKEN e execute a CLI do Codex normalmente:
export CODEX_ACCESS_TOKEN="<access-token>"
codex exec --json "review this repository and summarize the top risks"Para manter o login local entre execuções, passe o token pela entrada padrão para codex login --with-access-token:
printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token
codex exec "summarize the last release diff"codex login --with-access-token salva uma credencial de identidade de agente no armazenamento de credenciais de autenticação da CLI do Codex. Se preferir não manter credenciais na máquina, use a variável de ambiente CODEX_ACCESS_TOKEN.
codex app-server pode usar a mesma credencial por meio de CODEX_ACCESS_TOKEN ou de um login feito com codex login --with-access-token para autenticar suas solicitações à OpenAI. Essa credencial é independente da autenticação de transporte entre o cliente e o App Server. Para uma conexão WebSocket remota, configure um token separado do tipo bearer ou um token de capacidade, conforme descrito em App Server. Não reutilize o token de acesso do Codex como token de transporte. Consulte Variáveis de ambiente de autenticação e rede.
Fazer a rotação de um token ou revogá-lo
Faça a rotação dos tokens de acesso da mesma forma que a dos demais segredos de automação:
- Crie um token de substituição.
- Atualize o segredo no executor, no agendador ou no gerenciador de segredos.
- Execute um teste básico de funcionamento com o novo token.
- Revogue o token antigo em Tokens de acesso.
Na página Tokens de acesso, proprietários e administradores podem revogar qualquer token do espaço de trabalho. Membros com a permissão de tokens de acesso podem revogar apenas os tokens que criaram.
Modelo de permissões
A permissão de tokens de acesso do espaço de trabalho controla a criação de tokens. Dependendo da organização das configurações do espaço de trabalho, o acesso local ao Codex é controlado por Permitir que os membros usem o Codex e o Work localmente em Codex e Work locais, ou por Permitir que os membros usem o Codex localmente em Codex local. Se Work local tiver uma seção própria, Usar o Work localmente controla o acesso ao modo Work e não concede acesso ao Codex. Para executar fluxos de trabalho do Codex autenticados por token, o membro precisa tanto de acesso local ao Codex quanto da permissão de tokens de acesso. Um membro pode ter acesso local ao Codex sem ter permissão para criar tokens de acesso.
| Ação | Proprietários e administradores do espaço de trabalho | Membro com permissão de tokens de acesso | Membro sem permissão de tokens de acesso |
|---|---|---|---|
| Abrir Tokens de acesso | Sim | Sim | Não |
| Criar tokens de acesso | Sim, para a própria identidade no espaço de trabalho do ChatGPT | Sim, para a própria identidade no espaço de trabalho do ChatGPT | Não |
| Listar tokens de acesso | Todos os tokens do espaço de trabalho, com a identificação de quem criou cada um | Apenas os tokens que criou | Não |
| Revogar tokens de acesso na página Tokens de acesso | Qualquer token do espaço de trabalho | Apenas os tokens que criou | Sem acesso à página |
| Conceder ou remover a permissão de tokens de acesso | Apenas o proprietário do espaço de trabalho | Não | Não |
| Gerenciar outras configurações de clientes locais ou do Codex Cloud | Sim, conforme as permissões de administração do espaço de trabalho | Não, a menos que um proprietário conceda acesso | Não |
Em resumo, proprietários e administradores gerenciam o acesso no nível do espaço de trabalho. Os membros precisam da permissão de tokens de acesso para criar e gerenciar seus próprios tokens. Essa permissão não concede direitos de administração nem acesso aos tokens de outros membros.
Solução de problemas
A página Tokens de acesso retorna o erro 404 ou informa que o acesso foi negado
Peça a um proprietário do espaço de trabalho que confirme se a sua função inclui Permitir que os usuários criem tokens de acesso pessoais ou Permitir que os membros usem tokens de acesso do Codex, conforme a interface disponível. Para um fluxo de trabalho do Codex autenticado por token, confirme também se está habilitada a opção Permitir que os membros usem o Codex e o Work localmente ou Permitir que os membros usem o Codex localmente.
codex login --with-access-token falha
Confirme que você copiou o token de acesso gerado, e não um token de sessão do navegador ou uma chave de API da plataforma. Verifique também se o token está ativo, se ainda está dentro do prazo de validade e se pertence a um usuário com a permissão necessária para usar o Codex localmente.