Configuration

Configuration

OpenSoul reads an optional JSON5 config from ~/.opensoul/opensoul.json (comments and trailing commas allowed).

If the file is missing, OpenSoul uses safe defaults: embedded agent + per-sender sessions + workspace at ~/.opensoul/workspace.

Environment Variables

Place these in .env or ~/.opensoul/.env:

# Model provider API keys
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
GEMINI_API_KEY=
MINIMAX_API_KEY=
OPENCODE_API_KEY=
ZAI_API_KEY=

# Gateway
OPENSOUL_GATEWAY_TOKEN=       # Required for gateway startup
OPENSOUL_SKIP_CHANNELS=1      # Skip channel loading for local dev

Key Notes

• OPENSOUL_GATEWAY_TOKEN (or gateway.auth.token) is required for gateway startup. Without it, the process exits immediately.
• Use OPENSOUL_SKIP_CHANNELS=1 for local development unless channel credentials are configured.
• Config supports JSON5, file includes, and ${ENV} variable substitution.

Common Configuration Scenarios

Restrict Who Can Message the Bot

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
    telegram: {
      allowFrom: ["username1"],
    },
  },
}

Customize Agent Workspace

{
  agents: {
    defaults: {
      workspace: "~/.opensoul/workspace",
    },
  },
}

Set Agent Identity

{
  agents: {
    list: [
      {
        name: "main",
        identity: {
          displayName: "Soul",
          description: "Your AI companion",
        },
        workspace: "~/.opensoul/workspace",
      },
    ],
  },
}

Group Chat Mention Rules

{
  messages: {
    groupChat: {
      mentionPatterns: ["@opensoul"],
    },
  },
}

Strict Validation

OpenSoul only accepts configurations that fully match the schema. Invalid config prevents the Gateway from starting.

When validation fails:

• The Gateway does not boot
• Run opensoul doctor to see issues
• Run opensoul doctor --fix to apply repairs

Config Management via RPC

Full Replace (config.apply)

Validates, writes the full config, and restarts the Gateway:

opensoul gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.opensoul/workspace\" } } }",
  "baseHash": "<hash-from-config.get>"
}'

Partial Update (config.patch)

Merges a partial update without clobbering unrelated keys:

opensoul gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash-from-config.get>"
}'

Schema + UI

The Gateway exposes a JSON Schema via config.schema. The Control UI renders a form from this schema with a Raw JSON editor as fallback.

Related Pages

• Getting Started — Quick setup guide
• Channels — Channel-specific configuration
• Troubleshooting — Common config issues