개요

OpenClaw 게이트웨이는 세 가지 소스에서 시크릿(API 키, 인증 정보 등)을 로드한다. 활성화 시점에 즉시 해석(eager resolution)하고, 리로드 시 원자적 교체(atomic swap)를 수행하여 안전한 시크릿 관리를 제공한다.

시크릿 소스

1. 환경 변수 (Environment Variables)

가장 일반적인 방식. .env 파일 또는 시스템 환경 변수에서 로드한다.

{
  "secrets": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "TELEGRAM_TOKEN": "${TELEGRAM_BOT_TOKEN}"
  }
}

2. 파일 JSON 포인터 (File Pointers)

JSON/YAML 파일 내 특정 경로의 값을 시크릿으로 사용한다.

{
  "secrets": {
    "DB_PASSWORD": {
      "file": "/etc/openclaw/secrets.json",
      "pointer": "/database/password"
    }
  }
}

3. 실행 명령 (Executable Commands)

외부 시크릿 매니저(Vault, AWS Secrets Manager 등)에서 값을 조회하는 명령을 실행한다.

{
  "secrets": {
    "VAULT_TOKEN": {
      "exec": "vault kv get -field=token secret/openclaw"
    }
  }
}

즉시 해석 (Eager Resolution)

시크릿은 게이트웨이 활성화 시점에 즉시 해석된다. 런타임 중 지연 로딩(lazy loading)하지 않는다.

게이트웨이 시작
    │
    ▼
모든 시크릿 소스 해석
    │
    ▼
런타임 스냅샷 생성
    │
    ▼
에이전트가 스냅샷에서 시크릿 참조

원자적 교체 (Atomic Swap)

설정 리로드 시 새로운 시크릿 세트를 구성한 후, 기존 세트와 원자적으로 교체한다.

  • 리로드 중에도 기존 시크릿이 유효
  • 새 시크릿 해석 완료 후 한 번에 전환
  • 부분 업데이트 없음 (all-or-nothing)

활성 표면 필터링 (Active-Surface Filtering)

비활성화된 채널의 시크릿은 로드하지 않는다.

{
  "channels": {
    "telegram": { "enabled": false },
    "discord": { "enabled": true }
  }
}

위 설정에서 Telegram 관련 시크릿(TELEGRAM_BOT_TOKEN 등)은 해석되지 않는다. 불필요한 시크릿 노출을 방지하고 시작 시간을 단축한다.

런타임 스냅샷

해석된 시크릿은 런타임 스냅샷으로 메모리에 보관된다. 에이전트의 핫 패스(hot-path)에서 빠르게 접근할 수 있다.

  • 파일 시스템이나 외부 서비스 재조회 없음
  • 메모리 내 읽기 전용 접근
  • 프로세스 종료 시 메모리에서 제거

관리 워크플로우

시크릿 변경은 감사 → 설정 → 적용 3단계로 진행한다.

1. 감사 (Audit)

현재 시크릿 상태를 확인한다. 값은 마스킹되어 표시된다.

openclaw secrets list

Name              | Source  | Status
------------------|---------|--------
OPENAI_API_KEY    | env     | active
TELEGRAM_TOKEN    | env     | active
DB_PASSWORD       | file    | active
VAULT_TOKEN       | exec    | error

2. 설정 (Configure)

시크릿을 추가하거나 수정한다.

openclaw configure --section secrets

3. 적용 (Apply)

변경사항을 게이트웨이에 적용한다.

openclaw reload

원자적 교체가 수행되어 새로운 시크릿이 즉시 활성화된다.

안전 정책

단방향 안전 (One-Way Safety)

시크릿 변경은 항상 전진(forward-only)한다. 롤백 백업을 생성하지 않는다.

  • 이전 시크릿 값은 메모리에서 즉시 제거
  • 파일 시스템에 이전 값을 저장하지 않음
  • 롤백이 필요하면 원본 소스(환경 변수, Vault 등)에서 복원

이 정책은 시크릿이 불필요하게 디스크에 남아 노출되는 위험을 방지한다.