English | 简体中文

PaddedCell

OpenClaw plugin for secure secret management, agent identity management, safe command execution, and coordinated agent restart.

⚠️ Security Model

pcexec + pcguard mitigate light model hallucination / misoperation / prompt forgetting. They do not defend against malicious attacks. For stronger security, use sandbox mode instead of this plugin.

Features

1. secret-mgr — Secret Manager (Go)

AES-256-GCM encryption with a build-time secret injected at compile time. Secrets are stored per-agent under pc-pass-store/<agent-id>/<key>.gpg.

Agent commands (require pcguard — must run through pcexec):

secret-mgr list                                     # List keys for current agent
secret-mgr get-secret --key <key>                    # Output secret
secret-mgr get-username --key <key>                  # Output username
secret-mgr set --key <key> --secret <s> [--username <u>]  # Set entry
secret-mgr generate --key <key> [--username <u>]     # Generate random secret
secret-mgr unset --key <key>                         # Delete entry
secret-mgr get <key>                                 # Legacy (maps to get-secret)

Admin commands (human-only — rejected if any AGENT_* env var is set):

secret-mgr admin handoff [file]       # Export build secret to file (default: pc-pass-store.secret)
secret-mgr admin init-from [file]     # Re-encrypt all data from old build secret to current

2. ego-mgr — Agent Identity Manager (Go)

Manages agent personal information (name, email, timezone, etc.) stored in ~/.openclaw/ego.json.

Supports Agent Scope (per-agent values) and Public Scope (shared by all agents).

Commands (require pcguard — must run through pcexec):

ego-mgr add column <name> [--default <val>]          # Add agent-scope field
ego-mgr add public-column <name> [--default <val>]   # Add public-scope field
ego-mgr delete <name>                                 # Delete field and all values
ego-mgr set <name> <value>                            # Set field value
ego-mgr get <name>                                    # Get field value
ego-mgr show                                          # Show all fields and values
ego-mgr list columns                                  # List all field names

3. pcguard — Exec Guard (Go)

Validates that a process is running inside a pcexec context by checking environment sentinels (AGENT_VERIFY, AGENT_ID, AGENT_WORKSPACE). Returns exit code 1 if any check fails.

#!/bin/bash
pcguard || exit 1
# ... rest of script

4. pcexec — Safe Execution Tool (TypeScript)

Drop-in replacement for exec that:

• Resolves $(secret-mgr get-secret --key <key>) and legacy $(pass_mgr get-secret --key <key>) inline
• Sanitizes all resolved passwords from stdout/stderr
• Injects AGENT_VERIFY, AGENT_ID, AGENT_WORKSPACE environment variables
• Appends $(openclaw path)/bin to PATH (making pcguard, secret-mgr, and ego-mgr available)

5. safe-restart — Coordinated Restart (TypeScript)

Agent state management and coordinated gateway restart.

Project Structure

PaddedCell/
├── plugin/              # Plugin source (TypeScript)
│   ├── commands/        #   Slash commands
│   ├── core/            #   Core modules (safe-restart, status, api)
│   ├── hooks/           #   Lifecycle hooks
│   ├── tools/           #   Tool definitions (pcexec)
│   ├── index.ts         #   Plugin entry point
│   ├── openclaw.plugin.json
│   ├── package.json
│   └── tsconfig.json
├── secret-mgr/          # Go secret manager binary
│   └── src/main.go
├── ego-mgr/             # Go agent identity manager binary
│   └── src/main.go
├── pcguard/             # Go exec guard binary
│   └── src/main.go
├── skills/              # Agent skills
│   ├── secret-mgr/SKILL.md
│   └── ego-mgr/SKILL.md
├── dist/padded-cell/    # Build output
├── install.mjs          # Installer
└── README.md

Installation

# Install (default: ~/.openclaw)
node install.mjs

# Install with custom openclaw profile path
node install.mjs --openclaw-profile-path /path/to/.openclaw

# Build only (no install)
node install.mjs --build-only

# Uninstall
node install.mjs --uninstall

The installer automatically generates a random 32-byte build secret (stored in .build-secret, gitignored) and injects it into secret-mgr at compile time. Subsequent builds reuse the same secret.

Install paths

Priority: --openclaw-profile-path → $OPENCLAW_PATH → ~/.openclaw

Binaries → $(openclaw path)/bin/, plugin files → $(openclaw path)/plugins/padded-cell/.

Plugin Update Workflow (admin handoff)

When you rebuild PaddedCell (which generates a new build secret), existing encrypted data needs re-encryption:

# 1. Before updating — export current build secret
~/.openclaw/bin/secret-mgr admin handoff

# 2. Rebuild & reinstall (generates new .build-secret)
rm .build-secret
node install.mjs

# 3. After updating — re-encrypt data with new secret
~/.openclaw/bin/secret-mgr admin init-from

# 4. Restart gateway
openclaw gateway restart

Usage

# Agent sets and gets private passwords (via pcexec)
secret-mgr set --key myservice --secret s3cret --username admin
secret-mgr get-secret --key myservice
secret-mgr get-username --key myservice

# Shared scope (.public)
secret-mgr set --public --key shared-api --secret s3cret
secret-mgr list --public
secret-mgr get-secret --public --key shared-api

# Use in shell commands (pcexec resolves and sanitizes)
curl -u "$(secret-mgr get-username --key myservice):$(secret-mgr get-secret --key myservice)" https://api.example.com

# Agent identity management (via pcexec)
ego-mgr add column name
ego-mgr set name "小智"
ego-mgr add public-column timezone --default UTC
ego-mgr show

License

MIT