OpenClaw in Russia: Gateway, API, and Safe First Run

Want to test OpenClaw safely with your own API key? Create a BetterToken account and API key, then open the OpenClaw setup guide and configure the provider through SecretRef. Run the Gateway in the foreground on loopback and perform the first test in a separate workspace and a new session, without channels, community skills, or dangerous tools.

What OpenClaw Actually Runs

OpenClaw has several layers. A failure in one layer often looks like a problem in another, so separate their roles before setup.

Layer What it does What to check
Provider API Sends requests to the selected model Base URL, API key, protocol, Model ID
Gateway Runs the local control plane and client connections bind, auth, process, and RPC status
Agent workspace Limits the agent's working directory path, visible files, and tool permissions
Session Keeps current conversation context and state create a new session after a model change
Channels Connect Telegram, Discord, and other external inputs not required for the first run

BetterToken handles only the provider API in this workflow. It does not provide access to the OpenClaw site, installer, channels, community skills, or third-party services. The BetterToken API Endpoint is reachable from Russia without a VPN; this does not cover OpenClaw downloads or external integrations.

Install OpenClaw Without a Persistent Gateway

For the first check, use the official installer with --no-onboard. This installs the CLI without starting the setup wizard or creating a persistent service before the provider is verified.

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 checks for a supported Node.js version and installs it when needed. Do not pin an old Node release from a third-party guide; current requirements are on the OpenClaw installation page.

Configure the BetterToken Provider Without a Plaintext Key

The main OpenClaw configuration file is ~/.openclaw/openclaw.json. Create a separate workspace before editing it:

mkdir -p ~/openclaw-first-check

For the first run, choose a current Model ID from the BetterToken GPT group. The configuration below uses openai-responses. For another provider, do not infer the protocol from the model name; verify openai-completions or another option in 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"
  }
}

YOUR_MODEL_ID is a placeholder. Replace it with the full identifier from the model catalog or the Setup panel for your key. Keep the Base URL free of /responses or /chat/completions.

The apiKey field uses an OpenClaw SecretRef. BETTERTOKEN_API_KEY must exist in a protected environment visible to the Gateway process; the key itself is not stored in openclaw.json. OpenClaw officially supports SecretRef for models.providers.*.apiKey.

Check for plaintext credentials in configuration and old generated files:

openclaw secrets audit --check

If the audit finds plaintext, use the interactive migration:

openclaw secrets configure --apply

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

Verify Configuration, Gateway, and Model

1. Validate JSON Before Startup

openclaw config validate

This validates the active schema without starting the Gateway. Fix the reported field, quote, or bracket before proceeding.

2. Check the Provider and Selected Model

openclaw models list --provider bettertoken
openclaw models status

The list should contain bettertoken/YOUR_MODEL_ID, and status should resolve it as the default. models list is read-only and does not prove that an API call works, so a short request is still required.

3. Run the Gateway in the Foreground

In a separate terminal, run:

openclaw gateway --force

Leave it open. In the first terminal, check:

openclaw gateway status --require-rpc
openclaw status

For a local test, the Gateway should listen on loopback, require authentication, and pass the RPC probe. Do not change bind to lan, tailnet, or 0.0.0.0 for the first run.

4. Open a New Session

openclaw tui --session first-check

Send a minimal prompt that requests no file actions:

Return only JSON: {"agent":"openclaw","sum":4}. Do not use tools or modify files.

The first run is verified when:

  • the TUI returns valid JSON;
  • openclaw models status shows bettertoken/YOUR_MODEL_ID;
  • BetterToken Dashboard records the expected model, status, and token usage;
  • the workspace contains no unexpected changes.

Stop the foreground Gateway with Ctrl+C. Only then decide whether a persistent service is needed.

5. Install a Service Only After Verification

If the Gateway must continue after the terminal closes:

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

Use openclaw gateway restart for restarts. The official runbook advises against replacing it with a stop and start chain.

Why the First Run Needs Minimal Permissions

A Gateway is designed around one trusted boundary by default. A tool-enabled agent can read or change files, run commands, and access the network. Prompt injection can arrive through a page, document, attachment, or log even when no public chat is connected.

Keep tools.profile set to minimal, the Gateway on loopback, and channels unconfigured for the first check. Do not install community skills or plugins before reviewing their source and permissions. Before expanding access, run:

openclaw security audit --deep

When a channel is added later, start with pairing or an allowlist and a separate session scope. One shared Gateway is not a supported isolation boundary for mutually untrusted users.

Why an Old Session May Keep the Previous Model

Changing agents.defaults.model.primary does not reset an already open conversation. Validate configuration, restart the Gateway, and create a new session key:

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

This keeps the check separate from old context. If the new session still selects another provider, compare agents.defaults.model.primary, models.providers.bettertoken.models, and openclaw models status.

Common Errors

config validate Fails

Check JSON structure and supported api values. Do not run the Gateway with known-invalid configuration; direct editor writes are treated as untrusted until validation succeeds.

Gateway Startup or RPC Probe Fails

Run openclaw gateway status. EADDRINUSE indicates a port conflict or second Gateway process. An auth error indicates a mismatch between Gateway and client credentials. Do not disable auth or expose the bind address to bypass it.

401, 404, or Protocol Error

For 401, confirm that the SecretRef resolves in the Gateway environment. For the GPT group, use openai-responses with Base URL https://www.bettertoken.ai/v1. For another provider, use the exact protocol from current Docs and do not append an endpoint manually.

The Model Is in JSON but Not Listed

Match the ID in models.providers.bettertoken.models to agents.defaults.model.primary, then run openclaw config validate, openclaw models list --provider bettertoken, and openclaw models status.

OpenClaw or Hermes Agent

This guide handles installation only. If you are still choosing an architecture, Hermes Agent vs OpenClaw: How to Choose compares a local agent runtime, the Gateway approach, and operational complexity without repeating this configuration.

FAQ

Should I Connect Telegram or Discord Immediately?

No. Verify the local provider, Gateway, model, and new session first. Channels expand the access surface and need a separate pairing or allowlist policy.

Can I Put the API Key Directly in openclaw.json?

Plaintext is technically supported, but a safe setup should use SecretRef. A plaintext key remains readable to any process or agent tool that can access the file.

How Do I Check the Gateway Without a Successful Model Request?

openclaw gateway status --require-rpc checks RPC, while openclaw models status checks model and credential resolution. The end-to-end test finishes only after a short response in a new session and a matching BetterToken Dashboard entry.