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

​

Модель выполнения

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

​

Подстановка при отправке наружу (маркеры)

• SDK с параметром пользовательской функции получения данных получают защищенную функцию OpenClaw, поэтому SDK сохраняет маркер.
• SDK без параметра пользовательской функции получения данных раскрывают маркер непосредственно перед созданием клиента. Потоки поставщиков, принадлежащие плагинам, и среды выполнения агентов раскрывают его на последнем переходе под управлением ядра, поскольку эти транспорты не используют защищенную функцию получения данных OpenClaw.

​

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

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

​

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

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

​

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

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

​

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

• Ссылки на переменные среды: проверяется имя переменной среды и подтверждается, что во время настройки доступно непустое значение.
• Ссылки поставщика (file или exec): проверяется выбор поставщика, разрешается id и проверяется тип разрешенного значения.
• Процесс быстрой настройки: если gateway.auth.token уже является SecretRef, первоначальная настройка разрешает его перед проверкой и начальной настройкой панели управления (для ссылок env, file и exec) с использованием того же механизма немедленного отказа.

​

Контракт 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: {
      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: секрет из списка разрешённых

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }
}

​

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

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

​

Примеры интеграции Exec

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // требуется для исполняемых файлов Homebrew, доступных через символические ссылки
        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, // требуется для исполняемых файлов Homebrew, доступных через символические ссылки
        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 node
const { 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(`Не удалось разобрать запрос: ${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 завершился с кодом ${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 --check
openclaw secrets audit --allow-exec

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // требуется для исполняемых файлов Homebrew, доступных через символические ссылки
        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

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

​

Материалы аутентификации 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.
• Разрешённые значения записываются во временный каталог со строгими разрешениями файлов (0o600) и используются в создаваемой конфигурации SSH.
• Если фактическим бэкендом песочницы является не ssh (или режим песочницы — off), эти ссылки остаются неактивными и не блокируют запуск.

​

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

​

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

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

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

​

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

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

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

​

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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

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

​

Разрешение в путях команд

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

​

Процесс аудита и настройки

openclaw secrets audit --check

openclaw secrets configure --apply

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

​

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

• Перед режимом записи предварительная проверка должна завершиться успешно.
• Активация среды выполнения проверяется до фиксации.
• При применении файлы обновляются с помощью атомарной замены, а при сбое по возможности восстанавливаются.

​

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

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

​

Примечание о веб-интерфейсе

​

Связанные разделы

• Аутентификация — настройка аутентификации
• CLI: секреты — команды CLI
• SecretRef в Vault — настройка провайдера HashiCorp Vault
• Переменные окружения — приоритет переменных окружения
• Область учётных данных SecretRef — область учётных данных
• Контракт плана применения секретов — подробности контракта плана
• Безопасность — подход к безопасности