API Keys

API Key Management

Dual-mode API key storage with native file-based and AWS Secrets Manager backends.

Important

Always use the user_id from the system prompt when calling these tools. Never hardcode or guess a user_id. The system provides it automatically.

Native File Storage (manage_native)

Store API keys in a local JSON file (.openclaw/user-api-keys.json), synced to S3 with KMS encryption at rest.

node {baseDir}/native.js <user_id> <action> [key_name] [key_value]

• user_id (required): The user's namespace (e.g., telegram_12345)
• action (required): set, get, list, or delete
• key_name (required for set/get/delete): Alphanumeric key name
• key_value (required for set): The API key value to store

Examples

node {baseDir}/native.js telegram_12345 set my_api_key sk-abc123
node {baseDir}/native.js telegram_12345 get my_api_key
node {baseDir}/native.js telegram_12345 list
node {baseDir}/native.js telegram_12345 delete my_api_key

Secrets Manager Storage (manage_secret)

Store API keys in AWS Secrets Manager with KMS encryption, audit trail via CloudTrail, and per-user isolation.

node {baseDir}/secret.js <user_id> <action> [key_name] [key_value]

• user_id (required): The user's namespace (e.g., telegram_12345)
• action (required): set, get, list, or delete
• key_name (required for set/get/delete): Alphanumeric key name
• key_value (required for set): The secret value to store

Examples

node {baseDir}/secret.js telegram_12345 set my_api_key sk-abc123
node {baseDir}/secret.js telegram_12345 get my_api_key
node {baseDir}/secret.js telegram_12345 list
node {baseDir}/secret.js telegram_12345 delete my_api_key

Unified Retrieval (retrieve)

Look up a key from either backend — checks Secrets Manager first, falls back to native file.

node {baseDir}/retrieve.js <user_id> <key_name>

Migrate Between Backends

Move a key from native to Secrets Manager or vice versa.

node {baseDir}/migrate.js <user_id> <key_name> <direction>

• direction: native-to-secure or secure-to-native

From Agent Chat

• "Store my OpenAI key securely" -> manage_secret set
• "Save this API key" -> manage_native set (simpler)
• "What API keys do I have?" -> manage_native list + manage_secret list
• "Get my OpenAI key" -> retrieve (checks both backends)
• "Move my key to Secrets Manager" -> migrate native-to-secure
• "Delete my API key" -> manage_native delete or manage_secret delete

Security Notes

• Native mode: Keys stored in .openclaw/user-api-keys.json, synced to S3 with KMS encryption
• Secrets Manager mode: Keys stored at openclaw/user/{namespace}/{key_name}, auditable via CloudTrail
• Per-user isolation via STS session-scoped credentials
• Max 10 secrets per user in Secrets Manager
• Key names: alphanumeric, starting with letter, max 64 chars