OpenClaw Exec Provider Protocol (agentsecrets exec)

If you are looking to run terminal commands, servers, or Docker containers with injected environment variables, seeagentsecrets env. The agentsecrets exec command is a dedicated machine-to-machine JSON protocol provider designed for automated agent orchestrators like OpenClaw.

Protocol Overview

The agentsecrets exec command implements a machine-facing JSON interface over standard I/O:

• It reads an ExecRequest JSON payload from stdin (bounded to a maximum of 10MB).
• It authenticates against the local keychain-auth daemon.
• It resolves the requested secret IDs from the OS Keychain for the active project and environment.
• It writes an ExecResponse JSON payload to stdout.

Because it is designed for automated tooling:

• All interactive terminal spinners, update banners, and human-facing logs are suppressed.
• Human-readable error messages are emitted exclusively to stderr in structured formats.
• The process exits with code 0 on success or code 1 on protocol failure.

Wire Specification (Protocol Version 1)

1Request Payload ()

{
  "protocolVersion": 1,
  "provider": "agentsecrets",
  "ids": [
    "STRIPE_SECRET_KEY",
    "OPENAI_API_KEY",
    "DATABASE_URL"
  ]
}

2Response Payload ()

{
  "protocolVersion": 1,
  "values": {
    "STRIPE_SECRET_KEY": "sk_live_51ABC...",
    "OPENAI_API_KEY": "sk-proj-xyz..."
  },
  "errors": {
    "DATABASE_URL": {
      "message": "secret not found in keychain"
    }
  }
}

Command Invocation Examples

Testing via Command Line

You can test the protocol directly using shell piping:

echo '{"protocolVersion": 1, "provider": "agentsecrets", "ids": ["STRIPE_KEY"]}' | agentsecrets exec

Programmatic Invocation (Node.js Child Process)

import { spawn } from "child_process";

async function resolveSecrets(keys: string[]): Promise<Record<string, string>> {
  return new Promise((resolve, reject) => {
    const child = spawn("agentsecrets", ["exec"]);
    let stdout = "";
    let stderr = "";

    child.stdout.on("data", (chunk) => { stdout += chunk; });
    child.stderr.on("data", (chunk) => { stderr += chunk; });

    child.on("close", (code) => {
      if (code !== 0) {
        return reject(new Error(`Exec provider failed (${code}): ${stderr}`));
      }
      try {
        const response = JSON.parse(stdout);
        resolve(response.values);
      } catch (err) {
        reject(new Error(`Invalid JSON response: ${stdout}`));
      }
    });

    const payload = JSON.stringify({
      protocolVersion: 1,
      provider: "agentsecrets",
      ids: keys,
    });

    child.stdin.write(payload);
    child.stdin.end();
  });
}

Security Guarantees

• Binary Attestation: keychain-auth validates that the binary calling the OS Keychain is the genuine agentsecrets executable before returning values.
• Bounded Stdin Reader: To prevent memory exhaustion attacks, agentsecrets exec limits stdin reading to 10MB (MaxExecInputSize).
• Connection Lifecycle: The keychain-auth socket connection is strictly closed on exit via deferred cleanup.