Skip to main content

​
Config API

Manage per-user agent configuration with automatic versioned backups. Configuration is persisted in the database and survives server restarts. The system keeps the last 10 configuration backups and allows restoring to any previous version.
All Config API endpoints require authentication. Include a valid session cookie or auth token with every request. Unauthenticated requests receive a 401 Unauthorized response.

​
Get current configuration

GET /api/config
Returns the authenticated user’s current agent configuration and a list of available backups. If no custom configuration has been saved, the default configuration from the provisioning template is returned.

​
Response

{
  "config": {
    "logging": { "level": "info" },
    "agents": {
      "defaults": {
        "workspace": "/home/node/.openclaw/workspace",
        "model": { "primary": "openrouter/xiaomi/mimo-v2-pro" },
        "heartbeat": { "every": "30m", "lightContext": true, "isolatedSession": true }
      }
    },
    "tools": {
      "profile": "coding",
      "exec": { "backgroundMs": 10000, "timeoutSec": 1800 },
      "web": {
        "search": { "enabled": true },
        "fetch": { "enabled": true, "maxChars": 50000 }
      }
    },
    "gateway": {
      "bind": "lan",
      "auth": { "mode": "token" }
    },
    "channels": {
      "telegram": { "enabled": false, "dmPolicy": "pairing" },
      "discord": { "enabled": false, "dmPolicy": "pairing" },
      "whatsapp": { "enabled": false, "dmPolicy": "pairing" },
      "webchat": { "enabled": true }
    },
    "cron": { "enabled": true, "maxConcurrentRuns": 2, "sessionRetention": "24h" },
    "session": {
      "scope": "per-sender",
      "reset": { "mode": "daily", "atHour": 4 },
      "maintenance": { "mode": "warn", "pruneAfter": "30d", "maxEntries": 500 }
    },
    "skills": {
      "install": { "nodeManager": "npm" }
    }
  },
  "backups": [
    {
      "id": "bkp_initial",
      "timestamp": "2026-03-27T10:00:00Z"
    }
  ]
}
FieldTypeDescription
configobjectThe current agent configuration
config.logging.levelstringLog level (e.g. "info", "debug", "warn")
config.agents.defaults.workspacestringPath to the agent’s workspace directory
config.agents.defaults.model.primarystringDefault AI model identifier
config.agents.defaults.heartbeat.everystringHeartbeat interval (e.g. "30m")
config.agents.defaults.heartbeat.lightContextbooleanUse lightweight context during heartbeat checks
config.agents.defaults.heartbeat.isolatedSessionbooleanRun heartbeat checks in an isolated session
config.tools.profilestringTool profile ("coding" for collective+ plans, "messaging" for solo)
config.tools.exec.backgroundMsnumberMaximum time in milliseconds for background execution tasks
config.tools.exec.timeoutSecnumberMaximum execution timeout in seconds
config.tools.web.search.enabledbooleanWhether web search is available to the agent
config.tools.web.fetch.enabledbooleanWhether web fetch is available to the agent
config.tools.web.fetch.maxCharsnumberMaximum characters returned from a web fetch
config.gateway.bindstringGateway bind address (e.g. "lan" for all interfaces)
config.gateway.auth.modestringGateway authentication mode (e.g. "token")
config.channelsobjectChannel-specific settings
config.channels.telegram.enabledbooleanWhether the Telegram channel is active
config.channels.telegram.dmPolicystringDM policy for Telegram ("pairing" or "allowlist")
config.channels.discord.enabledbooleanWhether the Discord channel is active
config.channels.discord.dmPolicystringDM policy for Discord ("pairing" or "allowlist")
config.channels.whatsapp.enabledbooleanWhether the WhatsApp channel is active
config.channels.whatsapp.dmPolicystringDM policy for WhatsApp ("pairing" or "allowlist")
config.channels.webchat.enabledbooleanWhether the webchat channel is active
config.cron.enabledbooleanWhether the cron scheduler is active
config.cron.maxConcurrentRunsnumberMaximum concurrent cron job executions
config.cron.sessionRetentionstringHow long cron session data is retained
config.session.scopestringSession scope (e.g. "per-sender")
config.session.reset.modestringSession reset mode (e.g. "daily")
config.session.reset.atHournumberHour of day when daily session reset occurs (0-23)
config.session.maintenance.modestringMaintenance mode ("warn" or "silent")
config.session.maintenance.pruneAfterstringAge after which sessions are eligible for pruning
config.session.maintenance.maxEntriesnumberMaximum number of session entries retained
config.skills.install.nodeManagerstringNode package manager used for skill installation (e.g. "npm")
backupsarrayList of available backups (id and timestamp only)
backups[].idstringUnique backup identifier
backups[].timestampstringISO 8601 timestamp when the backup was created

​
Errors

CodeDescription
401Unauthorized — no valid session

​
Save configuration

POST /api/config
Saves a new configuration for the authenticated user. The current configuration is automatically backed up before the new one is applied. The system retains the 10 most recent backups.

​
Request body

FieldTypeRequiredDescription
configobjectYesThe new configuration object to save. Must be a valid JSON object.

​
Response

{
  "success": true,
  "config": { ... },
  "backupId": "bkp_1711540800000",
  "backups": [
    { "id": "bkp_1711540800000", "timestamp": "2026-03-27T12:00:00Z" },
    { "id": "bkp_initial", "timestamp": "2026-03-27T10:00:00Z" }
  ]
}
FieldTypeDescription
successbooleantrue when the configuration was saved
configobjectThe newly saved configuration
backupIdstringIdentifier of the backup created from the previous configuration
backupsarrayUpdated list of available backups (id and timestamp only)

​
Errors

CodeDescription
400Invalid config object — the config field is missing or is not an object
400Config is not valid JSON — the config object cannot be serialized as valid JSON
400Invalid request body — the request body is not valid JSON
401Unauthorized — no valid session

​
Restore a backup

PUT /api/config
Restores a previous configuration from a backup for the authenticated user. The current configuration is automatically backed up before the restore is applied.

​
Request body

FieldTypeRequiredDescription
backupIdstringYesThe identifier of the backup to restore

​
Response

{
  "success": true,
  "config": { ... },
  "restoredFrom": "bkp_initial",
  "backups": [
    { "id": "bkp_1711540800001", "timestamp": "2026-03-27T12:05:00Z" },
    { "id": "bkp_initial", "timestamp": "2026-03-27T10:00:00Z" }
  ]
}
FieldTypeDescription
successbooleantrue when the configuration was restored
configobjectThe restored configuration
restoredFromstringIdentifier of the backup that was restored
backupsarrayUpdated list of available backups (id and timestamp only)

​
Errors

CodeDescription
400Missing backupId — the backupId field is missing from the request body
400Invalid request body — the request body is not valid JSON
401Unauthorized — no valid session
404Backup not found — no backup exists with the given identifier

​
Example: save and restore

# Save a new configuration (requires authentication)
curl -X POST https://agentbot.raveculture.xyz/api/config \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{
    "config": {
      "logging": { "level": "debug" },
      "agents": {
        "defaults": {
          "workspace": "/home/node/.openclaw/workspace",
          "model": { "primary": "openrouter/xiaomi/mimo-v2-pro" },
          "heartbeat": { "every": "30m", "lightContext": true, "isolatedSession": true }
        }
      },
      "tools": {
        "profile": "coding",
        "exec": { "backgroundMs": 10000, "timeoutSec": 1800 },
        "web": { "search": { "enabled": true }, "fetch": { "enabled": true, "maxChars": 50000 } }
      },
      "gateway": {
        "bind": "lan",
        "auth": { "mode": "token" }
      },
      "channels": {
        "telegram": { "enabled": true, "dmPolicy": "pairing" },
        "discord": { "enabled": false, "dmPolicy": "pairing" },
        "whatsapp": { "enabled": false, "dmPolicy": "pairing" },
        "webchat": { "enabled": true }
      },
      "cron": { "enabled": true, "maxConcurrentRuns": 2, "sessionRetention": "24h" },
      "session": {
        "scope": "per-sender",
        "reset": { "mode": "daily", "atHour": 4 },
        "maintenance": { "mode": "warn", "pruneAfter": "30d", "maxEntries": 500 }
      },
      "skills": {
        "install": { "nodeManager": "npm" }
      }
    }
  }'

# Restore from a backup (requires authentication)
curl -X PUT https://agentbot.raveculture.xyz/api/config \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{ "backupId": "bkp_initial" }'