#OpenClaw gateway config questions — env loading, Discord account binding, agent entries

1 messages · Page 1 of 1 (latest)

simple wyvern
#

  1. On Linux where openclaw-gateway runs as a systemd --user service, what's the canonical way to load ~/.openclaw/.env so that ${VAR} interpolation in openclaw.json resolves at gateway startup? Does the gateway read .env natively, or does it rely on the systemd unit's EnvironmentFile= directive? If native, what dotenv library and search path does it use?

  2. What's the exact syntax for a Discord account entry in channels.discord.accounts.<name> to bind that bot to a specific agent in agents.list? Specifically, which field names the target agent — agent, agentId, targetAgent, defaultAgent, or does the account key itself need to match an agent id? A minimal working example would be ideal.

  3. For agents.list entries: is agentDir required, or is workspace alone sufficient? If agentDir is required, what's its purpose and what should it contain?

  4. Is there a reload command that applies openclaw.json changes without a full gateway restart? Signal, CLI command, anything. Restart is fine if that's the only option, but a lighter reload is preferable for iterating.

  5. When adding a new Discord account to channels.discord.accounts, beyond token and name, what other fields are mandatory for the bot to come online cleanly — intents, permissions, guild bindings, channel bindings, anything else?

  6. If a new agent is added to agents.list at runtime and the gateway is restarted, does OpenClaw auto-create the workspace directory if it doesn't exist, or must we mkdir it ourselves first? Same question for any bootstrap files (AGENTS.md, SOUL.md, etc.) — does OpenClaw populate stock content, or does an empty workspace cause the gateway to fail?

  7. Does $include interpolation in openclaw.json work from an arbitrary path, or does it require files under a specific subdirectory?

hoary talonBOT
quiet walrusBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

hoary talonBOT
lavish whaleBOT
#

I checked the installed docs/source. For current builds:

  1. ~/.openclaw/.env loading

    • OpenClaw loads env vars natively, it does not require systemd EnvironmentFile=.
    • Load order relevant here:
      • parent process env (systemd --user, shell, etc.)
      • process.cwd()/.env
      • $OPENCLAW_STATE_DIR/.env, normally ~/.openclaw/.env
      • plus legacy fallback ~/.config/openclaw/gateway.env when using the default state dir
    • It uses the npm dotenv package internally.
    • Existing env vars win. The .env files do not override variables already in the service environment.
    • So the canonical Linux answer is: put shared gateway vars in ~/.openclaw/.env, or in the systemd service env if you prefer. Both work. ${VAR} interpolation reads from the resulting process env at config load time.

  2. Discord account to agent binding

    • The binding is not inside channels.discord.accounts.<name>.
    • There is no agent, agentId, targetAgent, or defaultAgent field on the Discord account object.
    • The account key is just the accountId.
#

  • You bind that account to an agent with top-level bindings[], using match.accountId.

    Minimal example:

    {
  agents: {
    list: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "rusty", workspace: "~/.openclaw/workspace-rusty" },
    ],
  },

  bindings: [
    { agentId: "main",  match: { channel: "discord", accountId: "default" } },
    { agentId: "rusty", match: { channel: "discord", accountId: "rusty" } },
# 
     ],

     channels: {
       discord: {
         enabled: true,
         defaultAccount: "default",
         accounts: {
           default: { token: "<MAIN_BOT_TOKEN>" },
           rusty:   { token: "<RUSTY_BOT_TOKEN>" },
         },
       },
     },
   }

Matching the account id to the agent id is optional, just convenient.

#

  1. agentDir required or not

    • Not required. workspace alone is sufficient.
    • If omitted, OpenClaw defaults agentDir to:
      ~/.openclaw/agents/<agentId>/agent
    • agentDir is the per-agent state directory, mainly for:
      • auth-profiles.json
      • per-agent model registry/state
      • other per-agent config/state
    • Do not reuse one agentDir across multiple agents.

  2. Reload without full restart

    • Yes. Gateway config reload is built in.
    • It watches the active config file path and by default uses:
      • gateway.reload.mode: "hybrid"
    • Modes:
      • off
      • hot
#

  • restart

    • hybrid (default)
    • So for normal openclaw.json edits, you usually do not need a manual command.
    • If a change is restart-required, hybrid mode falls back to an in-process SIGUSR1 restart.
    • openclaw secrets reload is only for SecretRefs/runtime secrets, not general config reload.
    • If you want an explicit restart anyway: openclaw gateway restart

    One important nuance: docs/source say the watcher is on the active config file path. If you change only an included file or only .env, restart is the safest move.

  1. Mandatory Discord account fields
    • Config-side, the only truly mandatory pieces to connect are basically:
      • channels.discord.enabled: true
      • a token, either top-level channels.discord.token for default/single-account, or channels.discord.accounts.<id>.token for named accounts
    • name is optional.
    • guilds, channels, permissions, allowlists, etc. are not required just to come online.
    • For Discord itself, the important mandatory external requirement is:
      • Message Content Intent enabled on the bot
#
  • Recommended:
    • Server Members Intent if you use role allowlists or name resolution
    • Invite scopes/perms recommended by docs:
      • scopes: bot, applications.commands
      • perms: View Channels, Send Messages, Read Message History, Embed Links, Attach Files, Add Reactions (optional)
  1. New agent workspace/bootstrap creation
    • Yes, OpenClaw auto-creates the workspace directory.
    • By default it also seeds bootstrap files:
      • AGENTS.md
      • SOUL.md
      • TOOLS.md
      • IDENTITY.md
      • USER.md
      • HEARTBEAT.md
    • BOOTSTRAP.md is only created for a brand new workspace.
    • This behavior can be disabled with:
#
  • agents.defaults.skipBootstrap: true
    • An empty workspace does not fail startup. Missing bootstrap files are tolerated.
  1. $include path rules
    • Not arbitrary.
    • Include paths are resolved relative to the including file.
    • But they must stay inside the top-level config directory (the directory containing openclaw.json).
    • Absolute paths and ../... are allowed only if they still resolve inside that boundary.
    • Nested includes are supported up to 10 levels.

Docs: