OpenClaw и API-ключи: где хранить, чтобы они не утекли

Коротко

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

Сверено с документацией OpenClaw 2026.9.8, 4 октября 2026.

OpenClaw умеет хранить ключи в общем хранилище Gateway и подставлять их через SecretRef. Это опционально: открытый текст в конфиге остаётся рабочим вариантом. Дальше — как перенести ключи в хранилище и проверить, что в конфиге ничего лишнего.

Где OpenClaw хранит ключи

По умолчанию всё, что лежит под ~/.openclaw/ или $OPENCLAW_STATE_DIR/, считается потенциально приватным. Ключи провайдеров моделей, токены каналов, OAuth-токены в state/openclaw.sqlite, профили авторизации моделей в agents/<agentId>/agent/auth-profiles.json — всё это секреты. Если ключ лежит открытым текстом в файле, который агент может открыть как файл (в openclaw.json, в .env, в архивах auth-профилей, в сгенерированных agents/*/agent/models.json), агент его прочитает. SecretRef сокращает риск только после полной миграции, когда openclaw secrets audit --check не находит остатков открытого текста.

SecretRef и общее хранилище

SecretRef — это блок в конфиге вместо строки с ключом. Для провайдеров моделей используется источник store с указанием алиаса провайдера и имени записи. Запись OPENAI_API_KEY в хранилище по умолчанию подставляется так:

{
  models: {
    providers: {
      openai: {
        apiKey: { source: "store", provider: "default", id: "OPENAI_API_KEY" },
      },
    },
  },
}

Значение остаётся в общем хранилище (state/openclaw.sqlite) под правами 0600 на файл и 0700 на каталог. У записи два режима. Защищённый секрет (kind: "secret") после записи только пишется: ни list, ни get, ни Control UI его не показывают. Запись окружения (kind: "env") остаётся читаемой администратору и попадает в среду Gateway-команд открытым текстом.

Если у вас уже есть хранилище снаружи OpenClaw (1Password, Bitwarden, HashiCorp Vault, pass, sops), используйте его как источник через провайдер exec.

Переносим ключи из конфига в хранилище

Запустите аудит и посмотрите, какие креды ещё лежат открытым текстом: openclaw secrets audit --check.
Внесите нужные записи через Control UI или openclaw secrets store.
Если правили значение через CLI напрямую, выполните openclaw secrets reload, чтобы активный снимок в памяти подхватил новое значение.
Перезапустите Gateway, если меняли secrets.egressProxy.enabled: openclaw gateway restart.
Прогоните аудит ещё раз. Если в выводе нет остатков открытого текста, миграция завершена.

Секретный egress-прокси

OpenClaw кладёт в среду процессов маркер-заглушку вида oc-sent-v2...end, а подставляет реальное значение в URL, заголовки и тело запросов отдельный воркер Gateway на локальном прокси (loopback). Подстановка работает только для хостов из списка разрешённых хостов записи.

openclaw secrets store set OPENAI_API_KEY --allow-host api.openai.com
openclaw config set secrets.egressProxy.enabled true --strict-json
openclaw gateway restart

curl -sS https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

На api.openai.com подстановка сработает. Запрос на чужой хост будет отклонён с подсказкой, какой командой привязать хост. Имена хостов сравниваются точно и в нижнем регистре: подстановочные знаки и порты не поддерживаются.

Границы хранилища

Записи kind: "env" попадают в среду Gateway-команд открытым текстом, агент может их прочитать и напечатать. Защищённые записи kind: "secret" через прокси в среду не попадают: вместо значения в окружении лежит анонимный маркер. Codex native shell, sandbox exec и дочерние процессы ACP собирают свою среду сами, и секреты туда не доходят. Если нужен путь через Gateway, используйте gateway_exec в подходящем сеансе Codex app-server.

Частые ошибки

Оставить ключ в openclaw.json или .env «на всякий случай». Агент читает эти файлы как обычные файлы, SecretRef защищает только то, что в него перенесено.
Забыть openclaw secrets reload после правок через CLI. Активный снимок в памяти остаётся со старым значением.
Включить egress-прокси, но не привязать хосты к записям. Без allowedHosts подстановка не работает.