DEV Community

BetterToken.ai profile image Adela
Adela for BetterToken.ai

Posted on Edited on Originally published at bettertoken.ai

Configure OpenClaw with a Secure Gateway and API

#ai #programming #productivity #tutorial

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
Enter fullscreen mode Exit fullscreen mode

Windows PowerShell 

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

Check the CLI:

openclaw --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Before editing, create a separate workspace:

mkdir -p ~/openclaw-first-check
Enter fullscreen mode Exit fullscreen mode

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
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

If audit finds plaintext, use interactive migration:

openclaw secrets configure --apply
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

openclaw gateway status --require-rpc
openclaw status
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

In the open session, first check the actual route:

/status
/model status
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Send a minimal request without any actions on files:

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Originally published on the BetterToken blog.

BetterToken provides pay-as-you-go access to AI model APIs through
OpenAI-compatible and Anthropic-compatible endpoints — useful if you are wiring
Claude Code, Codex, or your own tooling to a custom base URL.
See the docs to get started.

Top comments (0)