Secret-Safe: Secure Credential Handling for Agent Skills

Why this skill exists: Snyk researchers found that 7.1% of all ClawHub skills instruct agents to handle API keys through the LLM context — making every secret an active exfiltration channel. This skill teaches the correct pattern.

The Core Rule

A secret must never appear in:

• The LLM prompt or system context
• Claude's response or reasoning
• Logs, session exports, or .jsonl history files
• File artifacts created by the agent
• Error messages echoed back to the user

A secret must only flow through:

• process.env (injected by OpenClaw before the agent turn)
• The shell environment of a subprocess the agent spawns
• A secrets manager CLI (read at subprocess level, not piped back into context)

Pattern 1: Environment Injection (Preferred)

This is OpenClaw's native, secure path. Use it for any skill that needs an API key.

In SKILL.md frontmatter

---
name: my-service-skill
description: Interact with MyService API.
metadata: {"openclaw": {"requires": {"env": ["MY_SERVICE_API_KEY"]}, "primaryEnv": "MY_SERVICE_API_KEY"}}
---

The requires.env gate ensures the skill will not load if the key isn't present — no silent failures, no prompting the user to paste a key mid-conversation.

The primaryEnv field links to skills.entries.<n>.apiKey in openclaw.json, so the user configures it once in their config file, never in chat.

In skill instructions

## Authentication
The API key is available as `$MY_SERVICE_API_KEY` in the shell environment.
Pass it to CLI tools or curl as an environment variable — never echo it or
include it in any output returned to the user.

Example safe curl invocation (instruct the agent to do this)

# CORRECT — key stays in environment, never in command string visible to LLM
MY_SERVICE_API_KEY="$MY_SERVICE_API_KEY" curl -s \
  -H "Authorization: Bearer $MY_SERVICE_API_KEY" \
  https://api.myservice.com/v1/data

Never instruct the agent to do this:

# WRONG — key is visible in LLM context, command history, and logs
curl -H "Authorization: Bearer sk-abc123realkeyhere" https://api.myservice.com/

Pattern 2: Secrets Manager Integration

For production setups or team environments, read secrets from a manager at subprocess level.

Supported managers

Safe shell wrapper pattern

Create a scripts/run-with-secret.sh in your skill: