Configuration

The main config file lives at ~/.clawmagic/config.json. It is created during onboarding and can be edited directly or through the portal Settings page.

~/.clawmagic/
├── config.json          # Main config (gateway, agent, plugins, etc.)
├── auth.json            # Google OAuth tokens (if connected)
└── workspace/           # Default agent workspace

Runtime settings that can change without restart are stored separately at state/config/runtime_settings.json inside the project directory.

The web portal at localhost:5173 provides a full Settings UI for editing configuration without touching JSON files. Settings are organized into tabs:

• General: rate limits, AI logging, marketplace connection, response cache, retention, local tools, multi-agent mode
• Agent: safe mode, approval gates, tool profile, developer override, execution thresholds
• Advanced: AI provider API keys, GitHub token, marketplace credentials

Security-critical fields (remote access, API token, approval gates) cannot be changed via the portal API — they require direct config file or environment variable changes.

All agent defaults can be overridden per-agent in the Agents page (/app/agents). Environment variable overrides use the pattern CLAWMAGIC_AGENTS_DEFAULTS_<FIELD>.

ClawMagic uses BYOK (Bring Your Own Key). Set provider API keys via environment variables or through the portal Advanced Settings tab.

# Environment variables for AI providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=AIza...

# Or set via portal: Settings → Advanced → AI Provider Secrets

Provider keys are stored encrypted using AES-256-GCM. No plaintext secrets on disk. The onboarding wizard handles initial provider setup.

// ~/.clawmagic/config.json → plugins section
{
  "plugins": {
    "enabled": true,           // Master switch
    "allow": [],               // Allowlist: only these slugs can load
    "deny": [],                // Denylist: block specific slugs
    "load": { "paths": [] },   // Additional plugin directories
    "compat": {
      "openclawStrict": false,         // Enforce OpenClaw manifest compat
      "requireSignatures": false,      // Require signed packages
      "openclawInstallSecurity": "permissive"  // strict|balanced|permissive
    },
    "slots": {
      "memory": null           // Optional: plugin slug for memory backend
    }
  }
}

Memory configuration is stored at state/config/memory_settings.json and controls the search, embedding, and cost guardrail behavior.

Env overrides: CLAWMAGIC_STORAGE_BACKEND, CLAWMAGIC_SEARCH_MODE, CLAWMAGIC_EMBEDDING_PROVIDER, CLAWMAGIC_EMBEDDING_ENABLED.

// Runtime settings → heartbeat
{
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 30,
    "keepaliveOnInbound": true,
    "adaptiveCadence": true,
    "activeHours": {
      "enabled": true,
      "startHour": 8,
      "startMinute": 0,
      "endHour": 22,
      "endMinute": 0,
      "timezone": "America/New_York"
    }
  }
}

The heartbeat keeps your agent proactive during active hours. Set via the portal or during onboarding.

All config keys can be overridden via environment variables using the pattern CLAWMAGIC_<SECTION>_<KEY>. The .env.example file in the ClawMagic repo lists all available variables with documentation.

# Key environment variables
CLAWMAGIC_GATEWAY_PORT=18790
CLAWMAGIC_GATEWAY_API_TOKEN=your-token-here
CLAWMAGIC_PORTAL_PASSWORD=your-password
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=AIza...
CLAWMAGIC_AGENT_MAX_ITERATIONS=6
CLAWMAGIC_PLUGINS_ENABLED=true
CLAWMAGIC_GATEWAY_ALLOW_REMOTE=false

Environment variables always override config file values. This is useful for Docker deployments and CI/CD where you inject config via env.

• /docs/environment — feature flags, marketplace connection, and provider setup.
• /docs/security — 50 security controls and how to configure them.
• /docs/deployment — remote access, Docker, and production deployment.
• /docs/power-workstation — built-in tools: thought chains, tickets, email, and more.