Управление секретами

OpenClaw поддерживает аддитивные SecretRefs, поэтому поддерживаемые учетные данные не нужно хранить в конфигурации в виде открытого текста.

Цели и модель runtime

Секреты разрешаются в снимок runtime в памяти.

• Разрешение выполняется заранее во время активации, а не лениво на путях запросов.
• Запуск быстро завершается с ошибкой, когда фактически активный SecretRef не может быть разрешен.
• Перезагрузка использует атомарную замену: полный успех или сохранение последнего заведомо исправного снимка.
• Нарушения политики SecretRef (например, профили авторизации в режиме OAuth в сочетании с входными данными SecretRef) приводят к ошибке активации до замены runtime.
• Runtime-запросы читают только из активного снимка в памяти.
• После первой успешной активации/загрузки конфигурации пути кода runtime продолжают читать этот активный снимок в памяти, пока успешная перезагрузка не заменит его.
• Пути исходящей доставки также читают из этого активного снимка (например, доставка ответов/тредов Discord и отправка действий Telegram); они не разрешают SecretRefs заново при каждой отправке.

Это не допускает сбоев поставщика секретов на горячие пути запросов.

Граница доступа агента

SecretRefs защищают учетные данные от сохранения в поддерживаемой конфигурации и сгенерированных модельных поверхностях, но они не являются границей изоляции процесса. Если учетные данные в открытом тексте остаются на диске в пути, который агент может читать, агент может обойти редактирование на уровне API, используя файловые или shell-инструменты для просмотра этого файла.

Для production-развертываний, где файлы, доступные агенту, входят в область риска, считайте миграцию SecretRef завершенной только когда выполнены все условия:

• поддерживаемые учетные данные используют SecretRefs вместо значений в открытом тексте
• устаревшие остатки открытого текста удалены из openclaw.json, auth-profiles.json, .env и сгенерированных файлов models.json
• openclaw secrets audit --check проходит без замечаний после миграции
• все оставшиеся неподдерживаемые или ротируемые учетные данные защищены изоляцией операционной системы, изоляцией контейнера или внешним прокси учетных данных

Поэтому рабочий процесс audit/configure/apply является контрольной точкой миграции безопасности, а не просто удобным помощником.

Фильтрация активных поверхностей

SecretRefs проверяются только на фактически активных поверхностях.

• Включенные поверхности: неразрешенные ссылки блокируют запуск/перезагрузку.
• Неактивные поверхности: неразрешенные ссылки не блокируют запуск/перезагрузку.
• Неактивные ссылки выдают нефатальные диагностические сообщения с кодом SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Диагностика поверхности авторизации Gateway

Когда SecretRef настроен в gateway.auth.token, gateway.auth.password, gateway.remote.token или gateway.remote.password, запуск/перезагрузка Gateway явно логирует состояние поверхности:

• active: SecretRef является частью эффективной поверхности авторизации и должен разрешаться.
• inactive: SecretRef игнорируется для этого runtime, потому что побеждает другая поверхность авторизации или потому что удаленная авторизация отключена/неактивна.

Эти записи логируются с SECRETS_GATEWAY_AUTH_SURFACE и включают причину, использованную политикой активных поверхностей, чтобы вы могли видеть, почему учетные данные были признаны активными или неактивными.

Предварительная проверка ссылок при onboarding

Когда onboarding выполняется в интерактивном режиме и вы выбираете хранилище SecretRef, OpenClaw выполняет предварительную проверку перед сохранением:

• Env-ссылки: проверяет имя env var и подтверждает, что непустое значение видно во время настройки.
• Ссылки поставщиков (file или exec): проверяет выбор поставщика, разрешает id и проверяет тип разрешенного значения.
• Путь повторного использования quickstart: когда gateway.auth.token уже является SecretRef, onboarding разрешает его перед probe/bootstrap dashboard (для ссылок env, file и exec), используя тот же fail-fast gate.

Если проверка не проходит, onboarding показывает ошибку и позволяет повторить попытку.

Контракт SecretRef

Используйте одну форму объекта везде:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

Конфигурация поставщика

Определяйте поставщиков в 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,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    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" } }}

API-ключи на базе файлов

Не помещайте строки file:... в блок конфигурации env. Блок env литеральный и не переопределяющий, поэтому file:... не разрешается.

Вместо этого используйте файловый SecretRef в поддерживаемом поле учетных данных:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Для mode: "singleValue" SecretRef id равен "value". Для mode: "json" используйте абсолютный JSON pointer, например "/providers/xai/apiKey".

См. поверхность учетных данных SecretRef, чтобы узнать, какие поля конфигурации принимают SecretRefs.

Примеры 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: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  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" },      },    },  },}

Переменные среды MCP-сервера

Переменные среды MCP-сервера, настроенные через plugins.entries.acpx.config.mcpServers, поддерживают SecretInput. Это не позволяет API-ключам и токенам попадать в конфигурацию в открытом виде:

{  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",                },              },            },          },        },      },    },  },}

Строковые значения в открытом виде по-прежнему работают. Ссылки-шаблоны среды, такие как ${MCP_SERVER_API_KEY}, и объекты SecretRef разрешаются во время активации Gateway до запуска процесса MCP-сервера. Как и на других поверхностях SecretRef, неразрешенные ссылки блокируют активацию только тогда, когда Plugin acpx фактически активен.

Материалы SSH-аутентификации песочницы

Базовый бэкенд песочницы ssh также поддерживает SecretRef для материалов 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" },        },      },    },  },}

Поведение во время выполнения:

• OpenClaw разрешает эти ссылки при активации песочницы, а не отложенно при каждом SSH-вызове.
• Разрешенные значения записываются во временные файлы с ограничительными правами и используются в сгенерированной SSH-конфигурации.
• Если эффективный бэкенд песочницы не ssh, эти ссылки остаются неактивными и не блокируют запуск.

Поддерживаемая поверхность учетных данных

Канонические поддерживаемые и неподдерживаемые учетные данные перечислены здесь:

• Поверхность учетных данных SecretRef

Обязательное поведение и приоритет

• Поле без ссылки: без изменений.
• Поле со ссылкой: обязательно на активных поверхностях во время активации.
• Если присутствуют и значение в открытом виде, и ссылка, ссылка имеет приоритет на поддерживаемых путях приоритета.
• Маркер редактирования __OPENCLAW_REDACTED__ зарезервирован для внутреннего редактирования/восстановления конфигурации и отклоняется как буквальные отправленные данные конфигурации.

Сигналы предупреждений и аудита:

• SECRETS_REF_OVERRIDES_PLAINTEXT (предупреждение времени выполнения)
• REF_SHADOWED (результат аудита, когда учетные данные auth-profiles.json имеют приоритет над ссылками openclaw.json)

Поведение совместимости Google Chat:

• serviceAccountRef имеет приоритет над serviceAccount в открытом виде.
• Значение в открытом виде игнорируется, когда соседняя ссылка задана.

Триггеры активации

Активация секретов запускается при:

• Запуске (предварительная проверка плюс финальная активация)
• Горячем применении перезагрузки конфигурации
• Проверке перезапуска при перезагрузке конфигурации
• Ручной перезагрузке через secrets.reload
• Предварительной проверке Gateway config write RPC (config.set / config.apply / config.patch) на разрешимость SecretRef активной поверхности в отправленной конфигурационной нагрузке до сохранения изменений

Контракт активации:

• Успех атомарно заменяет снимок.
• Ошибка запуска прерывает запуск Gateway.
• Ошибка перезагрузки во время выполнения сохраняет последний заведомо исправный снимок.
• Ошибка предварительной проверки write-RPC отклоняет отправленную конфигурацию и оставляет как конфигурацию на диске, так и активный снимок времени выполнения без изменений.
• Передача явного токена канала для отдельного вызова outbound helper/tool не запускает активацию SecretRef; точками активации остаются запуск, перезагрузка и явный secrets.reload.

Сигналы ухудшения и восстановления

Когда активация во время перезагрузки завершается неудачей после исправного состояния, OpenClaw входит в ухудшенное состояние секретов.

Однократное системное событие и коды журналов:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Поведение:

• Ухудшенное состояние: среда выполнения сохраняет последний заведомо исправный снимок.
• Восстановлено: отправляется один раз после следующей успешной активации.
• Повторные ошибки, когда система уже в ухудшенном состоянии, записывают предупреждения, но не создают поток событий.
• Быстрое завершение при ошибке запуска не отправляет события ухудшенного состояния, потому что среда выполнения так и не стала активной.

Разрешение путей команд

Пути команд могут включить поддерживаемое разрешение SecretRef через RPC снимка Gateway.

Существует два общих варианта поведения:

Другие примечания:

• Обновление снимка после ротации секрета в backend выполняется командой openclaw secrets reload.
• Метод Gateway RPC, используемый этими путями команд: secrets.resolve.

Рабочий процесс аудита и настройки

Стандартный поток оператора:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Не считайте миграцию завершенной, пока повторный аудит не пройдет без замечаний. Если аудит все еще сообщает о значениях в открытом виде в состоянии покоя, риск доступа агента сохраняется, даже когда runtime API возвращают отредактированные значения.

Если вы сохраняете план вместо применения во время configure, примените этот сохраненный план с помощью openclaw secrets apply --from <plan-path> перед повторным аудитом.

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

Односторонняя политика безопасности

Модель безопасности:

• предварительная проверка должна пройти успешно до режима записи
• активация runtime проверяется перед commit
• apply обновляет файлы с помощью атомарной замены файлов и best-effort восстановления при сбое

Примечания о совместимости устаревшей auth

Для статических учетных данных runtime больше не зависит от устаревшего хранилища auth в открытом виде.

• Источник учетных данных runtime — разрешенный снимок в памяти.
• Устаревшие статические записи api_key очищаются при обнаружении.
• Поведение совместимости, связанное с OAuth, остается отдельным.

Примечание о Web UI

Некоторые объединения SecretInput проще настраивать в режиме raw editor, чем в режиме формы.

Связанные материалы

• Authentication — настройка auth
• CLI: secrets — команды CLI
• Environment Variables — приоритет environment
• SecretRef Credential Surface — поверхность учетных данных
• Secrets Apply Plan Contract — подробности контракта плана
• Security — состояние безопасности