Configure OpenClaw with a Secure Gateway and API

For a BetterToken connection, open the OpenClaw instructions and configure the provider through SecretRef. Run Gateway in foreground on loopback and make the first test in a separate workspace and new session — without channels, community skills, or dangerous tools.

Start with a separate key for the first check. Create a BetterToken account

What OpenClaw runs

OpenClaw consists of several layers. A problem on one layer often looks like a problem on another, so it’s helpful to separate their functions before tuning.

Layer	What it does	What to check
Provider API	Sends a request to the selected model	Base URL, API Key, Protocol, Model ID
Gateway	Manages local control plane and client connections	bind, auth, process and RPC status
Agent workspace	Limits the agent’s working directory	path, available files, permissions tools
Session	Stores the current conversation context and state	new session after model change
Channels	Connect Telegram, Discord and other external inputs	not needed at first launch

BetterToken in this scheme is responsible only for the provider API. It does not ensure the availability of the OpenClaw website, installer, channels, community skills or third party services.

Regional availability note

From Russia, the BetterToken API endpoint can be reached without a VPN. This does not apply to OpenClaw downloads and external integrations.

How to install OpenClaw without a permanent Gateway

For the first check, use the official installer with the --no-onboard flag. So the installation does not launch the setup wizard and does not create a permanent service until the provider is checked.

macOS, Linux or WSL2

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows PowerShell

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Check the CLI:

openclaw --version

The official installer itself checks the supported version of Node.js and installs it if necessary. Do not commit to an old Node from a third party guide: current requirements are published on the OpenClaw installation page.

How to configure BetterToken provider without public API Key

The main OpenClaw file is located at:

~/.openclaw/openclaw.json

Before editing, create a separate workspace:

mkdir -p ~/openclaw-first-check

For the first launch, select the current Model ID from the BetterToken GPT group. The following configuration uses openai-responses; for another provider, you cannot guess the protocol by the model name - check openai-completions or another option with the current BetterToken documentation.

{
  "models": {
    "mode": "merge",
    "providers": {
      "bettertoken": {
        "baseUrl": "https://www.bettertoken.ai/v1",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "BETTERTOKEN_API_KEY"
        },
        "api": "openai-responses",
        "models": [
          {
            "id": "YOUR_MODEL_ID",
            "name": "YOUR_MODEL_ID"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/openclaw-first-check",
      "model": {
        "primary": "bettertoken/YOUR_MODEL_ID"
      }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback"
  },
  "tools": {
    "profile": "minimal",
    "deny": ["group:runtime", "exec", "process", "sessions_spawn"],
    "elevated": {
      "enabled": false
    }
  }
}

YOUR_MODEL_ID - placeholder. Replace it with the full ID from the model plaza or Setup window for your key. Leave Base URL without /responses or /chat/completions.

The apiKey field uses OpenClaw SecretRef. The value BETTERTOKEN_API_KEY must be set in a protected environment accessible to the Gateway process; the key itself is not written to openclaw.json. OpenClaw officially supports SecretRef for models.providers.*.apiKey.

Check that there are no open credentials left in the configuration and old generated files:

openclaw secrets audit --check

If audit finds plaintext, use interactive migration:

openclaw secrets configure --apply

Do not copy the key into prompt, log, commit or agent workspace.

How to check configuration, Gateway and model

1. Check JSON before running

openclaw config validate

The command validates the active schema without running Gateway. If there is an error, correct the specified field, quotes, or parentheses and recheck.

2. Check provider and selected model

openclaw models list --provider bettertoken
openclaw models status

bettertoken/YOUR_MODEL_ID should be present in the list, and status should show it as resolved default. models list - read-only command; it does not prove a successful API call, so a separate short request is needed.

3. Launch Gateway in foreground

In a separate terminal, run:

openclaw gateway --force

Leave the process open. In the first terminal, check:

openclaw gateway status --require-rpc
openclaw status

For a local test, the Gateway must listen to the loopback, require auth, and return a working RPC probe. Do not change bind to lan, tailnet or 0.0.0.0 for the first time.

4. Open a new session

openclaw tui --session first-check

In the open session, first check the actual route:

/status
/model status

If a different model is selected, set bettertoken/YOUR_MODEL_ID, then start a clean session and repeat the checks:

/model bettertoken/YOUR_MODEL_ID
/new
/status
/model status

Send a minimal request without any actions on files:

Reply with JSON only: {"agent":"openclaw","sum":4}. Do not use tools or change files.

The first launch is confirmed if:

• TUI returned valid JSON;
• /status and /model status in the current session show bettertoken/YOUR_MODEL_ID;
• a request with the expected model, status and Token consumption appeared in the BetterToken Dashboard;
• there are no unexpected changes in the workspace.

After checking, stop the foreground Gateway with the Ctrl+C combination. Only then decide whether permanent service is needed.

5. Install service only after checking

If Gateway should work after closing the terminal:

openclaw gateway install
openclaw gateway restart
openclaw gateway status --require-rpc

To restart, use openclaw gateway restart. The official runbook does not recommend replacing it with the stop and start chain.

Why the first launch should be with minimal rights

Gateway by default is designed for one trusted circuit. The Tool-enabled agent can read and change files, execute commands, and access the network. Prompt injection is possible not only from public chat: harmful instructions can come from a page, document, attachment or log.

tools.profile: "minimal" is only a base profile, not proof of complete isolation. For the first request, the example also denies runtime/control-plane tools, exec, process, and sessions_spawn, and disables elevated mode. Gateway stays on loopback and channels stay unconfigured. Before the first tool-enabled session, audit global and agents.entries.* overrides: they must not re-enable host exec, elevated mode, filesystem write, or runtime tools. Do not install community skills or plugins before checking their source and permissions. Run:

openclaw security audit --deep
openclaw sandbox explain

If you later need file tools, set sandbox and workspace access for the specific agent first, then repeat both audits. If you connect a channel, start with pairing or allowlist and a separate session scope. A shared Gateway for mutually untrusted users is not a supported isolation boundary.

Why an old session might use the old model

After changing agents.defaults.model.primary, one JSON edit is not enough for an already open conversation. Check the configuration, restart Gateway and create a new session key:

openclaw config validate
openclaw gateway restart
openclaw tui --session after-model-change

In the TUI run /status and /model status. If you change the model through /model, run /new after the selection and check both commands again before sending a request. This keeps the check separate from old context. If the new session still uses a different provider, match agents.defaults.model.primary, models.providers.bettertoken.models, the output of openclaw models status, and the session override shown by /status.

Frequent errors

config validate does not pass

Check the JSON structure and supported api values. Do not launch the Gateway with an invalid config: treat direct editor changes as untrusted until validation succeeds.

Gateway does not start or RPC probe crashes

First run openclaw gateway status. Error EADDRINUSE means a port conflict or a second Gateway process. The auth error indicates a mismatch between the Gateway credential and the client. Do not disable auth or open bind to an external network to work around the error.

401, 404 or protocol error

For 401, check that SecretRef is resolved in the Gateway environment. For GPT group use openai-responses and Base URL https://www.bettertoken.ai/v1. For another provider, take the exact protocol from the Docs; don’t add endpoint manually.

The model is in JSON, but not visible

Check the ID in models.providers.bettertoken.models with agents.defaults.model.primary, then do openclaw config validate, openclaw models list --provider bettertoken, and openclaw models status.

FAQ

Do I need to connect Telegram or Discord right away?

No. First confirm the local provider, Gateway, model and new session. Channels increase the access surface and require a separate pairing or allowlist policy.

Is it possible to write the API Key directly to openclaw.json?

Technically plaintext is supported, but to run it safely use SecretRef. The public key in the config remains accessible to any process or agent tool that can read the file.

How to test Gateway without a successful request to the model?

openclaw gateway status --require-rpc checks RPC, and openclaw models status checks model permission and credential. A full end-to-end test is completed only after a short response in a new session and the request appears in the BetterToken Dashboard.