OpenClaw in Russia: Secure Gateway and API Setup

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.

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. BetterToken API Endpoint is available from Russia without 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"
  }
}
Show more

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

Send a minimal request without any actions on files:

Ответь только JSON: {"agent":"openclaw","sum":4}. Не используй tools и не изменяй файлы.

The first launch is confirmed if:

• TUI returned valid JSON;
• openclaw models status shows 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.

For the first check, leave tools.profile set to minimal, Gateway set to loopback, and channels unconfigured. Do not install community skills or plugins before checking the source and permissions. Before expanding access, do:

openclaw security audit --deep

If you connect a channel later, 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

This way the check is not mixed with the old context. If the new session still uses a different provider, match agents.defaults.model.primary, models.providers.bettertoken.models and the output of openclaw models 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.

OpenClaw or Hermes Agent

This instruction responds only to the installation prompt. If you are still choosing an architecture, a separate article Hermes Agent or OpenClaw: how to choose compares the local agent runtime, the Gateway approach and operational complexity without repeating the configuration from here.

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.