Gerenciamento de segredos

OpenClaw é compatível com SecretRefs aditivos, para que credenciais compatíveis não precisem ser armazenadas como texto simples na configuração.

# Objetivos e modelo de runtime

Segredos são resolvidos em um snapshot de runtime em memória.

• A resolução é antecipada durante a ativação, não preguiçosa nos caminhos de solicitação.
• A inicialização falha rapidamente quando uma SecretRef efetivamente ativa não pode ser resolvida.
• O recarregamento usa troca atômica: sucesso completo, ou mantém o último snapshot bom conhecido.
• Violações de política de SecretRef (por exemplo, perfis de autenticação em modo OAuth combinados com entrada SecretRef) falham a ativação antes da troca de runtime.
• Solicitações de runtime leem apenas do snapshot ativo em memória.
• Após a primeira ativação/carga de configuração bem-sucedida, os caminhos de código de runtime continuam lendo esse snapshot ativo em memória até que um recarregamento bem-sucedido o substitua.
• Caminhos de entrega de saída também leem desse snapshot ativo (por exemplo, entrega de resposta/thread do Discord e envios de ação do Telegram); eles não resolvem SecretRefs novamente a cada envio.

Isso mantém indisponibilidades do provedor de segredos fora dos caminhos quentes de solicitação.

# Filtragem de superfície ativa

SecretRefs são validadas apenas em superfícies efetivamente ativas.

• Superfícies habilitadas: refs não resolvidas bloqueiam inicialização/recarregamento.
• Superfícies inativas: refs não resolvidas não bloqueiam inicialização/recarregamento.
• Refs inativas emitem diagnósticos não fatais com o código SECRETS_REF_IGNORED_INACTIVE_SURFACE.

# Diagnósticos da superfície de autenticação do Gateway

Quando uma SecretRef está configurada em gateway.auth.token, gateway.auth.password, gateway.remote.token ou gateway.remote.password, a inicialização/recarregamento do Gateway registra explicitamente o estado da superfície:

• active: a SecretRef faz parte da superfície de autenticação efetiva e precisa ser resolvida.
• inactive: a SecretRef é ignorada para este runtime porque outra superfície de autenticação vence, ou porque a autenticação remota está desabilitada/não ativa.

Essas entradas são registradas com SECRETS_GATEWAY_AUTH_SURFACE e incluem o motivo usado pela política de superfície ativa, para que você possa ver por que uma credencial foi tratada como ativa ou inativa.

# Pré-verificação de referência no onboarding

Quando o onboarding é executado em modo interativo e você escolhe armazenamento SecretRef, o OpenClaw executa validação prévia antes de salvar:

• Refs de env: valida o nome da variável de env e confirma que um valor não vazio está visível durante a configuração.
• Refs de provedor (file ou exec): valida a seleção do provedor, resolve id e verifica o tipo do valor resolvido.
• Caminho de reutilização do Quickstart: quando gateway.auth.token já é uma SecretRef, o onboarding a resolve antes do bootstrap de probe/dashboard (para refs env, file e exec) usando a mesma barreira de falha rápida.

Se a validação falhar, o onboarding mostra o erro e permite tentar novamente.

# Contrato SecretRef

Use um único formato de objeto em todos os lugares:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

# Configuração do provedor

Defina provedores em secrets.providers:

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

# Exemplos de integração exec

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

# Variáveis de ambiente do servidor MCP

Variáveis de env do servidor MCP configuradas via plugins.entries.acpx.config.mcpServers aceitam SecretInput. Isso mantém chaves de API e tokens fora da configuração em texto simples:

{
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT",
                },
              },
            },
          },
        },
      },
    },
  },
}

Valores de string em texto simples ainda funcionam. Refs de template de env como ${MCP_SERVER_API_KEY} e objetos SecretRef são resolvidos durante a ativação do Gateway antes que o processo do servidor MCP seja iniciado. Como em outras superfícies SecretRef, refs não resolvidas só bloqueiam a ativação quando o Plugin acpx está efetivamente ativo.

# Material de autenticação SSH de sandbox

O backend de sandbox ssh do core também oferece suporte a SecretRefs para material de autenticação SSH:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

Comportamento de runtime:

• O OpenClaw resolve essas refs durante a ativação do sandbox, não de forma preguiçosa durante cada chamada SSH.
• Os valores resolvidos são gravados em arquivos temporários com permissões restritivas e usados na configuração SSH gerada.
• Se o backend de sandbox efetivo não for ssh, essas refs permanecem inativas e não bloqueiam a inicialização.

# Superfície de credenciais compatível

As credenciais canônicas compatíveis e incompatíveis estão listadas em:

• Superfície de credenciais SecretRef

# Comportamento obrigatório e precedência

• Campo sem uma ref: inalterado.
• Campo com uma ref: obrigatório em superfícies ativas durante a ativação.
• Se texto simples e ref estiverem presentes, a ref terá precedência nos caminhos de precedência compatíveis.
• O sentinela de redação __OPENCLAW_REDACTED__ é reservado para redação/restauração interna de configuração e é rejeitado como dados literais de configuração enviados.

Sinais de aviso e auditoria:

• SECRETS_REF_OVERRIDES_PLAINTEXT (aviso de tempo de execução)
• REF_SHADOWED (achado de auditoria quando as credenciais de auth-profiles.json têm precedência sobre refs de openclaw.json)

Comportamento de compatibilidade do Google Chat:

• serviceAccountRef tem precedência sobre serviceAccount em texto simples.
• O valor em texto simples é ignorado quando a ref irmã está definida.

# Acionadores de ativação

A ativação de segredos é executada em:

• Inicialização (pré-verificação mais ativação final)
• Caminho de aplicação a quente do recarregamento de configuração
• Caminho de verificação de reinício do recarregamento de configuração
• Recarregamento manual via secrets.reload
• Pré-verificação RPC de gravação de configuração do Gateway (config.set / config.apply / config.patch) para resolubilidade de SecretRef em superfícies ativas dentro da carga de configuração enviada antes de persistir edições

Contrato de ativação:

• O sucesso troca o snapshot atomicamente.
• Falha na inicialização aborta a inicialização do gateway.
• Falha no recarregamento em tempo de execução mantém o último snapshot válido conhecido.
• Falha na pré-verificação de RPC de gravação rejeita a configuração enviada e mantém inalterados tanto a configuração em disco quanto o snapshot ativo em tempo de execução.
• Fornecer um token de canal explícito por chamada a uma chamada de helper/ferramenta de saída não aciona a ativação de SecretRef; os pontos de ativação continuam sendo inicialização, recarregamento e secrets.reload explícito.

# Sinais de degradação e recuperação

Quando a ativação no momento do recarregamento falha após um estado saudável, o OpenClaw entra em estado de segredos degradado.

Códigos de evento de sistema de disparo único e de log:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamento:

• Degradado: o tempo de execução mantém o último snapshot válido conhecido.
• Recuperado: emitido uma vez após a próxima ativação bem-sucedida.
• Falhas repetidas enquanto já está degradado registram avisos, mas não disparam eventos em excesso.
• Falha rápida na inicialização não emite eventos degradados porque o tempo de execução nunca ficou ativo.

# Resolução de caminhos de comando

Caminhos de comando podem optar pela resolução SecretRef compatível via RPC de snapshot do Gateway.

Há dois comportamentos amplos:

Outras observações:

• A atualização do snapshot após rotação de segredo no backend é tratada por openclaw secrets reload.
• Método RPC do Gateway usado por esses caminhos de comando: secrets.resolve.

# Fluxo de auditoria e configuração

Fluxo padrão do operador:

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

# Política de segurança unidirecional

Modelo de segurança:

• a pré-verificação deve ser bem-sucedida antes do modo de gravação
• a ativação em tempo de execução é validada antes do commit
• a aplicação atualiza arquivos usando substituição atômica de arquivo e restauração de melhor esforço em caso de falha

# Observações de compatibilidade de autenticação legada

Para credenciais estáticas, o tempo de execução não depende mais do armazenamento legado de autenticação em texto simples.

• A fonte de credenciais em tempo de execução é o snapshot resolvido em memória.
• Entradas api_key estáticas legadas são limpas quando descobertas.
• O comportamento de compatibilidade relacionado ao OAuth permanece separado.

# Observação sobre Web UI

Algumas uniões SecretInput são mais fáceis de configurar no modo editor bruto do que no modo formulário.

# Relacionado

• Autenticação — configuração de autenticação
• CLI: secrets — comandos da CLI
• Variáveis de ambiente — precedência de ambiente
• Superfície de credenciais SecretRef — superfície de credenciais
• Contrato de plano de aplicação de segredos — detalhes do contrato do plano
• Segurança — postura de segurança