OpenClaw

OpenClaw is an open-source AI assistant running on personal devices. It centrally manages models, sessions, tools, and messaging channels through Gateway, and provides terminal TUI and browser Control UI. After adding AGTCloud as a Custom Provider, OpenClaw can call models available with the current API Key through the OpenAI Chat Completions compatible entry.

This tutorial only completes local installation, model integration, Gateway startup, and basic validation. Messaging channels, remote Gateway, ClawHub plugins, Skills, MCP, scheduled tasks, and multi-proxy features are not covered on this page.

First verify the normal dialogue, then enable the tool's capabilities

OpenClaw can read files, run shell commands, and call other tools. A successful basic text reply does not mean the target model is compatible with all tool structures. For the first test, use isolated directories, maintain manual approval, and check each operation to be executed.

Preparation

Before you start, please confirm that you have:

Prepare a macOS, Linux, WSL2, or Windows device supported by OpenClaw;
Create the AGTCloud API Key on the API Keys page;
Copy the model ID from the Model Marketplace which is available to the current API Key and supports Chat Completions;
Prepare a test directory that does not include production credentials or sensitive source code.

MODEL_ID is a placeholder that must be replaced. To test tool calling, select a model that is available to the current API Key and explicitly supports tool calls.

Install OpenClaw

The official OpenClaw installer can prepare a supported Node.js runtime environment when needed. Customers who already manage their own Node.js can also use npm for installation.

Using the official installation script:

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

After installation, check the version and operating environment:

openclaw --version
openclaw doctor

If the installer automatically opens the setup wizard, you can exit the model configuration step first, complete the AGTCloud Provider configuration below, and then run openclaw onboard --install-daemon. This way, the setup wizard can retain the verified default model configuration.

Securely store API Keys

OpenClaw reads ~/.openclaw/.env as a global fallback environment file. Create the file, then add the AGTCloud API Key:

User-level file path:

~/.openclaw/.env

File content:

AGTCLOUD_API_KEY=your-api-key

This file contains real credentials. Do not commit it to a code repository, upload it to cloud storage, or send it as a troubleshooting attachment.

Add AGTCloud Custom Provider

OpenClaw stores Custom Providers under models.providers. The command below merges the agtcloud Provider into the existing configuration without overwriting other settings in openclaw.json.

openclaw config set models.providers.agtcloud \
  '{"baseUrl":"https://api.agtcloud.cn/v1","apiKey":"${AGTCLOUD_API_KEY}","api":"openai-completions","auth":"api-key","authHeader":true,"models":[{"id":"MODEL_ID","name":"MODEL_ID","input":["text"]}]}' \
  --strict-json \
  --merge

The key fields in the configuration are as follows:

Field	Value	Purpose
Provider ID	`agtcloud`	Forms the model reference `agtcloud/MODEL_ID`
`baseUrl`	`https://api.agtcloud.cn/v1`	AGTCloud OpenAI-compatible API address; it must include `/v1`
`apiKey`	`${AGTCLOUD_API_KEY}`	Read credentials from OpenClaw environment files
`api`	`openai-completions`	Use the Chat Completions request adapter
`auth`	`api-key`	Authenticate using API Key
`authHeader`	`true`	Send credentials via the Authorization Header
`models`	`MODEL_ID`	Explicit registration allows OpenClaw to use the model

The base URL needs to include /v1

Use https://api.agtcloud.cn/v1 exactly as shown. Do not enter only the API Origin or append the full /chat/completions path. The openai-completions adapter adds the endpoint path automatically.

The tutorial only declares the model as text input, without filling in unconfirmed context length, maximum output, price, inference, or image capability. Once you understand the true capabilities of the target model, you can supplement metadata according to the official OpenClaw model field descriptions.

Set up the model and check the configuration

Set the newly registered model as the default:

openclaw models set agtcloud/MODEL_ID

Check the configuration file, Provider model, and current default model in order:

openclaw config validate
openclaw models list --provider agtcloud
openclaw models status

If config validate reports invalid fields, fix the configuration before starting the Gateway. If agtcloud/MODEL_ID is missing from the model list, confirm that the model was added to models.providers.agtcloud.models.

When you need to perform a real connection probe, you can run:

openclaw models status --probe

Connection probe sends a real request

--probe connects to the model service and may consume a small amount of tokens. It only runs after confirming the base URL, API key, and model ID are correct.

Complete local booting and start Gateway

After the Provider configuration is approved, run the local boot and install the Gateway daemon:

openclaw onboard --install-daemon

If the wizard asks about model configuration, keep the existing model settings. You can skip messaging channels, Web Search, Skills, and other extensions for now. For the initial setup, keep the Gateway bound to the local machine and leave access authentication enabled.

After completion, restart and check the Gateway:

openclaw gateway restart
openclaw gateway status

If the Gateway does not start, run openclaw config validate and openclaw doctor first. Do not work around the problem by exposing the Gateway publicly or disabling authentication.

Start and verify the connection

Open Control UI or Terminal TUI

Using the browser Control UI:

openclaw dashboard

Or connect to the local Gateway in the terminal:

openclaw tui

Verify basic text responses

For the first test, enter:

Please only reply: AGTCloud Connection successful. Do not use any tools.

If OpenClaw returns the requested text, the Gateway, AGTCloud Provider, API Key, and model ID have established a basic connection.

Optional: Verify read-only tool capabilities

After confirming that a basic conversation works, enter the following in a safe test project:

Read the README.md and summarize the project's purpose in three points. Do not modify any files, nor execute other commands.

Check each operation proposed by OpenClaw and only approve permissions needed to read the target file. A normal conversation that succeeds but the step fails usually means the target model or current compatible entry does not fully support the required tool call structure.

Add or switch models

OpenClaw's model reference format is provider/model, so the AGTCloud model writes:

agtcloud/MODEL_ID

The Custom Provider does not guarantee that every model returned by AGTCloud /v1/models will be imported automatically. When adding a model, merge its object into models.providers.agtcloud.models, then switch models with the following command:

openclaw models set agtcloud/MODEL_ID
openclaw gateway restart

After changing the model, confirm that it is available to the current API Key and supports the required protocol. Otherwise, OpenClaw may report that the model does not exist or is not permitted.

Frequently Asked Questions

Issue	What to check	Resolution
Cannot find the `openclaw` command	Installation, terminal session, and `PATH`	Reopen the terminal and run `openclaw --version`; if it is still unavailable, rerun the official installation process
Configuration verification failed	JSON, field names, and command quotes	Run `openclaw config validate`, correct the error path so it does not overwrite the entire configuration file
Gateway cannot start	Whether `gateway.mode` is active and the daemon is installed	Run local onboarding again, then check `openclaw doctor` and `openclaw gateway status`
Returns `401`	API Key and `authHeader`	Use a valid API Key and confirm that `authHeader` is `true`
Returns `403`	API Key permissions, account balance, and model access	Confirm that the current API Key can call the selected model and check the account status
Returns `404`	Base URL, protocol, and model ID	Use `https://api.agtcloud.cn/v1`; do not append another `/v1` or enter a full endpoint
The model is not shown	Provider `models[]`	Add the full `MODEL_ID` to `models.providers.agtcloud.models` and check again
The model is not permitted	Model policy and registered model catalog	Confirm that the model reference is `agtcloud/MODEL_ID` and review the active model restrictions
The conversation is normal, but the tool fails	Model tool calls compatibility	First, disable tool tasks and switch to models that clearly support tool calls for specialized validation
Still using the old model	Gateway and current session	Restart the Gateway and create a new session to recheck the current model

If you cannot identify the cause of an issue, record the OpenClaw version, request time, API Base URL, Provider, model ID, HTTP status, and sanitized error messages, then review Errors and troubleshooting. Do not submit .env, full configuration backups, or any API Keys.

Safety advice

OpenClaw is designed for a single trusted operator, avoiding exposing unprotected Gateways to the public network;
The first test uses only isolated directories and reviews file, command, network, and tool permissions item by item;
Do not save API keys in repositories, screenshots, session exports, logs, or shared configurations;
Before accessing messaging channels, other users, or automated tasks, read the official OpenClaw security and sandbox documentation.