OpenClaw configuration preset manager.
apex 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.
- Clone the repository:
git clone https://github.com/minpeter/apex.git
cd apex-
Copy the contents of
setup.mdand paste it directly into your preferred AI coding agent:- Claude Code
- OpenCode
- Codex
- Or any other coding agent
The agent will handle dependency installation, building, and initial configuration automatically.
# Example: using Claude Code
cat setup.md | claudeNote: Bun is required as a prerequisite. Make sure it's installed before running setup.
- List available presets:
apex list - Diff a preset against your current config:
apex diff apex - Apply the preset:
apex apply apex - Install apex quickly:
apex install - Export your current setup as a new preset:
apex export my-custom-setup - Apply a preset from GitHub:
apex apply minpeter/demo-researcher
Lists all built-in and user-defined presets.
apex listExample Output:
Available presets:
apex [builtin]
All-in-one power assistant with full capabilities (all-in-one, power, assistant)
v1.0.0
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, and installs any bundled skills to ~/.agents/skills/. The <preset> argument can be a local preset name, a GitHub shorthand (owner/repo), or a full GitHub URL (https://github.com/owner/repo).
apex 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.
Installs the apex preset (shortcut for apply apex).
apex 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.
Saves your current openclaw.json and workspace markdown files as a new reusable preset.
apex 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.
Shows a structural comparison between your current configuration and a specific preset.
apex diff <preset> [options]- Flags:
--json: Output the diff in JSON format.
| Name | Description | Use Case |
|---|---|---|
| apex | All-in-one power assistant with full capabilities | The single built-in preset with 100% of all capabilities. |
When applying a preset, apex 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.
To prevent accidental exposure of secrets, certain fields are filtered during exports and diffs. These include:
auth,env,metagateway.authhooks.tokenmodels.providers.*.apiKeychannels.*.botToken,channels.*.token
Before applying changes, apex creates timestamped backups in ~/.openclaw/apex/backups/ (for openclaw.json, plus workspace backups when workspace files are replaced).
Presets are stored in ~/.openclaw/apex/. You can create them manually by making a directory with a preset.json5 file and any accompanying markdown files (AGENTS.md, SOUL.md, etc.).
{
name: "my-preset",
description: "My custom configuration",
version: "1.0.0",
config: {
identity: {
name: "CustomBot",
emoji: "🤖"
}
},
workspaceFiles: ["AGENTS.md"]
}You can apply presets directly from public GitHub repositories without any local setup.
# Apply by shorthand (owner/repo)
apex apply minpeter/demo-researcher
# Apply by full GitHub URL
apex apply https://github.com/minpeter/demo-researcher
# Force re-download (ignores local cache)
apex apply minpeter/demo-researcher --forceRemote presets are automatically cached as user presets at ~/.openclaw/apex/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.
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.
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.
--forceflag: Overwrites existing skills without prompting.
{
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.
- 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
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.
MIT