oh-my-openclaw

⚠️ Notice: Development is temporarily paused due to limited availability. The project will remain as-is under the MIT license. Contributions are still welcome, but please expect delays in review and merging.

OpenClaw configuration preset manager.

What is this?

oh-my-openclaw is a CLI utility for managing configuration presets for OpenClaw, a self-hosted AI agent gateway. It allows you to switch between different agent personalities, toolsets, and model configurations with a single command by bundling openclaw.json overrides and workspace markdown files.

Quick Start

Installation

⚠️ IMPORTANT: All installation and setup instructions are in setup.md. This README does not contain installation steps. You must read setup.md to install this project.

👉 Click here to read setup.md | Raw

Basic Workflow

1. List available presets: oh-my-openclaw list
2. Diff a preset against your current config: oh-my-openclaw diff apex
3. Apply the preset: oh-my-openclaw apply apex
4. Install oh-my-openclaw quickly: oh-my-openclaw install
5. Export your current setup as a new preset: oh-my-openclaw export my-custom-setup
6. Apply a preset from GitHub: oh-my-openclaw apply minpeter/demo-researcher

Docker Compose Tips

If you want to force a fresh local Docker build from the current checkout instead of using the published image, reset the stack and rebuild without pulling a remote image:

docker compose down -v && docker compose up --build --pull never

If OpenClaw is running inside the Compose service and you receive a Telegram pairing code, approve it from inside the container:

docker compose exec openclaw openclaw pairing approve telegram <CODE>

For the full Docker setup flow, including .env preparation and gateway startup, see setup.md.

Commands

list

Lists all built-in and user-defined presets.

oh-my-openclaw list

Example Output:

Available presets:

  apex [builtin]
    All-in-one power assistant with full capabilities (all-in-one, power, assistant)
    v1.0.0

apply

Applies a preset to your OpenClaw configuration. It merges the preset's JSON config into your openclaw.json, copies any bundled workspace files (like AGENTS.md) to your .openclaw directory, installs any bundled skills to ~/.agents/skills/, and can bootstrap declared OpenClaw plugins. The <preset> argument can be a local preset name, a GitHub shorthand (owner/repo), or a full GitHub URL (https://github.com/owner/repo).

oh-my-openclaw apply <preset> [options]

• Arguments: <preset> - Name of the preset to apply.
• Flags:
  • --dry-run: Show what would change without making any modifications.
  • --no-backup: Skip creating a backup of your current configuration (default: backups are created).
  • --clean: Remove existing config and workspace files before applying (clean install).
  • --force: Re-download a remote preset even if it's already cached locally.

install

Installs the apex preset (shortcut for apply apex).

oh-my-openclaw install [options]

• Flags:
  • --dry-run: Show what would change without making any modifications.
  • --no-backup: Skip creating a backup.
  • --clean: Remove existing config and workspace files before applying.

export

Saves your current openclaw.json and workspace markdown files as a new reusable preset.

oh-my-openclaw export <name> [options]

• Arguments: <name> - Name for the new preset.
• Flags:
  • --description <desc>: Add a short description.
  • --version <ver>: Specify a version (default: 1.0.0).
  • --force: Overwrite an existing preset with the same name.

diff

Shows a structural comparison between your current configuration and a specific preset.

oh-my-openclaw diff <preset> [options]

• Flags:
  • --json: Output the diff in JSON format.

Built-in Presets

Name	Description	Use Case
apex	All-in-one power assistant with full capabilities	The single built-in preset with 100% of all capabilities.

How It Works

Deep Merge Semantics

When applying a preset, oh-my-openclaw uses a deep merge strategy for openclaw.json:

• Scalars (String, Number, Boolean): Overwrite existing values.
• Objects: Merged recursively.
• Arrays: Entirely replaced by the preset's array.
• Null: Deletes the key from the target configuration.

Sensitive Field Protection

To prevent accidental exposure of secrets, certain fields are filtered during exports and diffs. These include:

• auth, env, meta
• gateway.auth
• hooks.token
• models.providers.*.apiKey
• channels.*.botToken, channels.*.token

Automatic Backups

Before applying changes, oh-my-openclaw creates timestamped backups in ~/.openclaw/oh-my-openclaw/backups/ (for openclaw.json, plus workspace backups when workspace files are replaced).

Creating Custom Presets

Presets are stored in ~/.openclaw/oh-my-openclaw/. You can create them manually by making a directory with a preset.json5 file and any accompanying markdown files (AGENTS.md, SOUL.md, etc.).

Preset Format Example (preset.json5)

{
  name: "my-preset",
  description: "My custom configuration",
  version: "1.0.0",
  config: {
    identity: {
      name: "CustomBot",
      emoji: "🤖"
    }
  },
  workspaceFiles: ["AGENTS.md"]
}

Remote Presets

You can apply presets directly from public GitHub repositories without any local setup.

Usage

# Apply by shorthand (owner/repo)
oh-my-openclaw apply minpeter/demo-researcher

# Apply by full GitHub URL
oh-my-openclaw apply https://github.com/minpeter/demo-researcher

# Force re-download (ignores local cache)
oh-my-openclaw apply minpeter/demo-researcher --force

Remote presets are automatically cached as user presets at ~/.openclaw/oh-my-openclaw/presets/owner--repo/. Subsequent applies reuse the cached version unless --force is specified.

Note: Only public GitHub repositories are supported. Private repos require authentication which is not currently supported.

Skills in Presets

Presets can bundle OpenClaw agent skills. When you apply a preset, any skills listed in its skills field are automatically copied to ~/.agents/skills/, making them available to openclaw skills list.

Collision Handling

If a skill already exists at the target location:

• Interactive (TTY): You will be prompted to confirm overwrite ([y/N]).
• Non-interactive (non-TTY / CI): The existing skill is skipped with a warning.
• --force flag: Overwrites existing skills without prompting.

Preset Format with Skills

{
  name: "my-preset",
  description: "My preset with skills",
  version: "1.0.0",
  skills: ["my-skill"],  // skill directory names under skills/
  config: { ... },
  workspaceFiles: ["AGENTS.md"]
}

Skills are stored in the preset's skills/<name>/ directory and must contain a SKILL.md file.

OpenClaw Plugins in Presets

Presets can also declare OpenClaw plugin packages that should be installed during apply. This is separate from config.plugins.entries, which only writes OpenClaw config.

{
  name: "my-preset",
  description: "My preset with plugin bootstrap",
  version: "1.0.0",
  openclawPlugins: ["openclaw-memory-auto-recall"],
  openclawBootstrap: {
    memoryIndex: true
  }
}

The built-in apex preset uses this to ensure openclaw-memory-auto-recall is installed and to run openclaw memory index during apply.

Development

• Prerequisites: Bun
• Install dependencies: bun install
• Run lint: bun run lint
• Run tests: bun test
• Type check: bun run typecheck
• Build binary: bun run build:compile

Architecture

• src/core/: Core logic including merge strategy, backup system, and sensitive field filtering.
• src/commands/: CLI command implementations (list, apply, export, diff, install).
• src/presets/: Built-in preset templates and manifests.

License

MIT