Semântica das credenciais de autenticação

Essa semântica mantém alinhado o comportamento de autenticação no momento da seleção e durante a execução. Ela é compartilhada por:

• resolveAuthProfileOrder (ordenação de perfis)
• resolveApiKeyForProfile (resolução de credenciais durante a execução)
• openclaw models status --probe
• verificações de autenticação do openclaw doctor (doctor-auth)

Códigos de motivo estáveis da sondagem

Os resultados da sondagem incluem uma categoria de status (ok, auth, rate_limit, billing, timeout, format, unknown, no_model), além de um reasonCode estável quando a sondagem não chegou a realizar uma chamada ao modelo:

As verificações de elegibilidade relatam ok como código de motivo para credenciais utilizáveis.

Credenciais de token

As credenciais de token (type: "token") são compatíveis com token e/ou tokenRef embutidos.

Regras de elegibilidade

1. Um perfil de token é inelegível quando token e tokenRef estão ausentes (missing_credential).
2. expires é opcional. Quando presente, deve ser um número finito de milissegundos desde a época Unix, maior que 0 e não superior ao carimbo de data/hora máximo de Date do JavaScript (8640000000000000).
3. Se expires for inválido (tipo incorreto, NaN, 0, negativo, não finito ou além desse máximo), o perfil será inelegível com invalid_expires.
4. Se expires estiver no passado, o perfil será inelegível com expired.
5. tokenRef não ignora a validação de expires.

Regras de resolução

1. A semântica do resolvedor para expires corresponde à semântica de elegibilidade.
2. Para perfis elegíveis, o conteúdo do token pode ser resolvido a partir do valor embutido ou de tokenRef.
3. Referências que não podem ser resolvidas produzem unresolved_ref na saída de models status --probe.

Portabilidade de cópias de agentes

A herança de autenticação do agente usa leitura transparente. Quando um agente não tem um perfil local, ele resolve os perfis no armazenamento do agente padrão/principal durante a execução, sem copiar conteúdo secreto para seu próprio armazenamento de credenciais (agents/<agentId>/agent/openclaw-agent.sqlite).

Fluxos de cópia explícita, como openclaw agents add, usam esta política de portabilidade:

• Perfis api_key e token são portáveis, exceto quando copyToAgents: false.
• Perfis oauth não são portáveis por padrão, pois tokens de atualização podem ser de uso único ou sensíveis à rotação.
• Fluxos OAuth pertencentes ao provedor podem aceitar a cópia com copyToAgents: true somente quando for comprovadamente seguro copiar o conteúdo de atualização entre agentes; essa aceitação se aplica apenas quando o perfil contém conteúdo embutido de acesso/atualização.

Perfis não portáveis continuam disponíveis por meio da herança com leitura transparente, a menos que o agente de destino inicie uma sessão separadamente e crie seu próprio perfil local.

Rotas de autenticação somente por configuração

As entradas de auth.profiles com mode: "aws-sdk" são metadados de roteamento, não credenciais armazenadas. Elas são válidas quando o provedor de destino usa models.providers.<id>.auth: "aws-sdk", a rota gravada pela configuração do Amazon Bedrock pertencente ao Plugin. Esses IDs de perfil podem aparecer em auth.order e em substituições de sessão, mesmo quando não existe uma entrada correspondente no armazenamento de credenciais.

Não grave type: "aws-sdk" no armazenamento de credenciais; as credenciais armazenadas são apenas api_key, token ou oauth. Se um auth-profiles.json legado contiver esse marcador, openclaw doctor --fix o moverá para auth.profiles e removerá o marcador do armazenamento.

Filtragem explícita da ordem de autenticação

• Quando auth.order.<provider> ou a substituição da ordem no armazenamento de autenticação está definida para um provedor, models status --probe sonda apenas os IDs de perfil que permanecem na ordem de autenticação resolvida para esse provedor. A substituição armazenada prevalece sobre a configuração auth.order.
• Um perfil armazenado para esse provedor que tenha sido omitido da ordem explícita não será tentado silenciosamente depois. A saída da sondagem o relata com reasonCode: excluded_by_auth_order e o detalhe Excluded by auth.order for this provider.

Resolução do destino da sondagem

• Os destinos da sondagem podem vir de perfis de autenticação, credenciais de ambiente ou models.json (source do resultado: profile, env, models.json).
• Se um provedor tiver credenciais, mas o OpenClaw não conseguir resolver um modelo candidato que possa ser sondado para ele, models status --probe relatará status: no_model com reasonCode: no_model.

Descoberta de credenciais de CLI externa

• Credenciais exclusivas de execução pertencentes a CLIs externas (Claude CLI para claude-cli, Codex CLI para openai, MiniMax CLI para minimax-portal) são descobertas somente quando o provedor, o ambiente de execução ou o perfil de autenticação está no escopo da operação atual, ou quando já existe um perfil local armazenado para essa fonte externa.
• Os chamadores do armazenamento de autenticação escolhem um modo explícito de descoberta de CLI externa: none apenas para autenticação persistida/de Plugin, existing para atualizar perfis de CLI externa já armazenados ou scoped para um conjunto concreto de provedores/perfis.
• Os caminhos somente leitura/de status passam allowKeychainPrompt: false; eles usam apenas credenciais de CLI externa armazenadas em arquivos e não leem nem reutilizam resultados do macOS Keychain.

Proteção da política de SecretRef do OAuth

A entrada SecretRef destina-se apenas a credenciais estáticas. As credenciais OAuth são mutáveis durante a execução (os fluxos de atualização persistem tokens rotacionados), portanto, conteúdo OAuth apoiado por SecretRef dividiria o estado mutável entre armazenamentos.

• Se uma credencial de perfil for type: "oauth", objetos SecretRef serão rejeitados em qualquer campo de conteúdo de credencial desse perfil.
• Se auth.profiles.<id>.mode for "oauth", entradas keyRef/tokenRef apoiadas por SecretRef serão rejeitadas para esse perfil.
• As violações são falhas definitivas (erros lançados) nos caminhos de preparação de segredos durante a inicialização/recarga e de resolução de perfis.

Mensagens compatíveis com versões legadas

Para manter a compatibilidade com scripts, os erros da sondagem mantêm esta primeira linha inalterada:

Auth profile credentials are missing or expired.

Detalhes de fácil compreensão e o código de motivo estável aparecem nas linhas seguintes no formato ↳ Auth reason [code]: ....

Relacionado

• Gerenciamento de segredos
• Armazenamento de autenticação