Simple Application Server:OpenClaw FAQ

Deploy an OpenClaw image on an existing server

1. Log in to the Simple Application Server console, select the target instance, and click Server Resetting.

2. Select Reset to Other Image, and then select the OpenClaw 2026.5.19 image.

3. Reconfigure OpenClaw. After you reset the system, the previously configured API key and token are invalid. Go to Application Details to reconfigure the API key.

Reset the application image

If your current application image is not version OpenClaw 2026.5.19, reset the system to update the image and access the latest OpenClaw features.

1. Log in to the Simple Application Server console, select the target instance, and click Server Resetting.

2. Select Reset to Other Image, and then select version OpenClaw 2026.5.19.

3. Reconfigure OpenClaw. Resetting the system invalidates your API key and token. Go to Application Details to reconfigure the API key.

Check the OpenClaw image version

You can check the image version of your OpenClaw instance in two ways:

• From the console: Log in to the Simple Application Server console. Go to the details page of the target OpenClaw instance and navigate to Basic Information > Images to view the instance's current image version.

• Using a terminal command: In the Simple Application Server console, click Remote Connection > Log on Now to open the terminal. Run the following command to check the version:

  openclaw --version

The version numbers from these two methods have different meanings:

• Console image version: This is the version of the image used to create the instance.

• The version returned by openclaw --version: This is the version of the running OpenClaw application, which changes with application updates.

It is normal for these version numbers to differ, as they come from different sources.

Troubleshoot system reset errors

If an error occurs when you reset the system, stop the Simple Application Server instance first. You can reset the system only when the instance is in the stopped state.

1. Log in to the Simple Application Server console. In the instance list, click the target instance.

2. In the upper-right corner of the instance details page, click Stop. Wait until the instance status changes to stopped.

3. When the instance has stopped, Server Resetting again.

OpenClaw firewall command failure

When using the "One-click Firewall Passthrough" feature for an OpenClaw application in the Simple Application Server console, a pop-up may appear with the error "Failed to retrieve the port passthrough command." The pop-up also displays a warning: "Your firewall will open an unspecified port for traffic from source 0.0.0.0/0. Assess the security risks and then click Confirm."

• Cause: A missing OpenClaw port in the configuration file prevents the system from retrieving the port passthrough command.

• Affected versions: This issue affects only OpenClaw versions earlier than 2026.3.28. Version 2026.3.28 and later include the fix.

• Solution: Reset the current application image to the latest version.

Troubleshoot "API rate limit reached" in OpenClaw

To troubleshoot this error, check the following items in order:

1. Incorrect OpenClaw configuration.

   If the base URL or model provider is misconfigured, your requests may be routed to a general API endpoint instead of the dedicated Coding Plan channel, triggering the rate limit.

   • If you are using a Coding Plan, check your OpenClaw configuration file to ensure that the models, agents, and gateway parameters, including any nested fields, are configured correctly. For example, the model provider must be structured as follows: { "models": { "providers": { "Model Studio": {...} } } } .

   • If you are not currently using a Coding Plan, consider switching to one to get a dedicated quota.

2. Plan quota exceeded: Check your plan usage on the Coding Plan page.

3. Try resetting the API key: If the issue persists after the preceding checks, go to the Coding Plan page to reset it.

General troubleshooting for rate limits (applies to all model providers)

If you receive an API rate limit reached error when calling a model, it may also be caused by the following issues:

• Excessive calling frequency: Sending too many requests in a short period can trigger the model provider's rate limit. Reduce the calling frequency and try again after a brief wait.

• Excessive concurrent requests: A large number of concurrent requests sent in a short period can cause this error. Review the maxConcurrent parameter in your application's configuration and consider lowering the concurrency limit.

• Free quota exhausted: If you are using a free quota, this error may indicate that your free quota is exhausted. Some providers return a 403 or a rate limit error when the free quota is exhausted, instead of automatically switching to paid billing.

Third-party model support

Yes. Configuration depends on your OpenClaw image version. Switch between the tabs below to view the supported providers and integration methods for your version.

If you use only Alibaba Cloud Model Studio models, you do not need to configure third-party models. On the Application Details page in the console, the model configuration section displays only Alibaba Cloud Model Studio options, such as Model Studio Coding Plan and Alibaba Cloud Model Studio. This is expected behavior, and no further action is required. Third-party models are integrated by using a separate configuration path and are not added from this drop-down menu.

WebUI issues with third-party models

If you configured a third-party model, such as DeepSeek or MiniMax, but it doesn't appear in the WebUI drop-down menu or if it reverts to the default model (for example, Qwen) after you switch, follow these steps:

• Check configuration integrity: Confirm that you have added the model to models.providers, added a reference to the model in agents.defaults.models in the provider-id/model-id format, and specified the default model in agents.defaults.model.primary. If you only configure models.providers without adding the reference, the WebUI will not recognize the new model.

• Restart the service to apply changes: After you modify the configuration file, run the following command:

  openclaw gateway restart

• Console limitations: The "Application Details" page in the Simple Application Server console only supports displaying and modifying models from Model Studio. It does not support displaying or modifying third-party models. Configuration for third-party models is defined only in the ~/.openclaw/openclaw.json file on the server. Therefore, it is normal for the console to show a Model Studio model even when a third-party model is active.

• Switching models:

  • To switch models in a WebUI chat, send the command: /model provider-id/model-id

  • To switch models from the terminal, run: openclaw models set provider-id/model-id

  • To list available models, run: openclaw models list

  The agents.defaults.models list in the ~/.openclaw/openclaw.json configuration file defines which models are available for switching with the commands above. To add a new switchable model, first add its configuration to models.providers and then add its reference to agents.defaults.models.

  Before switching models, create an instance snapshot or back up the configuration file (cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak). This ensures you can quickly restore your settings if a configuration error occurs.

• Check for fallback model activation: If the configuration is correct but a different model is still being used, check the OpenClaw logs to see if a rate limit or an error has activated the fallback model.

Model switch does not take effect

After switching models in the console, such as from Qwen-Plus to Qwen-Max, conversations may still use the old model even though the configuration is updated. This is because the change only takes effect after you restart the gateway service and refresh the page.

Procedure

1. Verify that the agents.defaults.model.primary field in the configuration file ~/.openclaw/openclaw.json is updated to the target model. This field determines the active model.

2. Run the following command to restart the gateway and apply the new configuration:

   openclaw gateway restart

3. Refresh your browser page or regenerate the access URL, then confirm that the conversation is using the new model.

Feishu stops replying after a model switch

Switching the large model invalidates the Feishu channel configuration, which prevents the Feishu bot from responding to messages. To resolve this, go to the application details page in the Simple Application Server console and re-enter the App ID and App Secret for the Feishu channel.

Procedure

1. Log in to the Simple Application Server console and click the target instance in the server list.

2. Go to the Application Details page and find the Feishu channel configuration.

3. Re-enter the Feishu App ID and App Secret. After you save the changes, the Feishu bot resumes normal operation.

Http 401 errors (Incorrect API key / Invalid access token)

An HTTP 401 error typically indicates an incorrect API Key or a mismatch between the Base URL and the key. Review the following scenarios:

Scenario 1: Alibaba Cloud Model Studio general-purpose models (pay-as-you-go)

• API Key format: Verify that your API Key starts with sk-.

• Region match: Ensure the API Key's region matches the region of the Base URL. For example, a key for the China (Beijing) region requires the corresponding URL.

• Base URL: The standard Base URL is https://dashscope.aliyuncs.com/compatible-mode/v1.

• Note: API Keys for the Coding Plan and pay-as-you-go services are not interchangeable.

Scenario 2: Alibaba Cloud Model Studio Token Plan

• API Key format: Ensure your API Key starts with sk-sp-.

• Base URL: You must use the Base URL https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1.

• Note: The Token Plan does not support one-click setup in the console. You must edit the configuration file manually.

Scenario 3: Third-party models (MiniMax, DeepSeek, Tencent Cloud, etc.)

• Ensure you are using the API Key provided by the third-party platform, not an Alibaba Cloud Model Studio key.

• Check the key for any leading or trailing whitespace or newline characters.

• Verify that the Base URL is correct. For example, the Base URL for DeepSeek is https://api.deepseek.com/v1.

• Some models, such as MiniMax, may require you to select a specific Auth Method, like MiniMax CN or MiniMax Global.

General troubleshooting steps

• Regenerate the API Key in the third-party provider's console and replace the old one in your configuration.

• Check the ~/.openclaw/openclaw.json configuration file to ensure the apiKey field contains the correct value.

• Run openclaw gateway restart to restart the service.

Local model support

Currently, OpenClaw deployed in the cloud (for example, from a Simple Application Server image) does not support calling large models that run on a local machine or in a local area network. OpenClaw requires access to a publicly accessible API endpoint.

To use a local model, you must meet the following conditions:

• Ensure your local model service is exposed to the public network and accessible by the cloud server.

• Configure your public Base URL in ~/.openclaw/openclaw.json under models.providers, as described in the "General Third-Party Model Integration Guide."

Impact of changing the model provider

Changing the model provider for OpenClaw only affects the OpenClaw application itself and typically does not affect other applications deployed on the server, such as Hermes.

If a configuration error occurs, you can roll back using an instance snapshot from the Simple Application Server console. Before each change, create a snapshot or back up the configuration file (cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak).

Multi-model support

Yes. OpenClaw can connect to multiple large models from different providers simultaneously. In the Simple Application Server console, go to the Application Details page for your OpenClaw instance. The Model Configuration section has two modes:

• Model Studio Coding Plan: Supports Alibaba Cloud's Qwen series and models from third-party providers such as MiniMax, GLM, and Kimi.

• Model Studio: Supports the Qwen series, including vision models such as qwen3-vl-plus and qwen3-vl-flash.

Select a provider and a specific model from the drop-down lists, and then click Apply to complete the configuration. Model Studio integrates third-party models, so you do not need to manually enter a base URL or an API key.

View the OpenClaw port number

To prevent malicious scans and targeted attacks, OpenClaw generates a random port number on initialization. To view the port number, go to Application Details > Basic Configuration > View Port and click View.

Controlling local applications with OpenClaw

No. A Simple Application Server instance runs in a cloud network that is isolated from your local network. This isolation prevents OpenClaw from directly controlling applications on your computer.

Why is web search unavailable after an update?

Go to the Simple Application Server console. In the Image Information section, ensure your application image is version OpenClaw 2026.2.3 or later. If you are using an earlier version, update it as described in How to reset the current application image to the latest version?. This application image provides a web search feature by default in all regions through the built-in SearXNG Skill. This feature requires no additional configuration and incurs no extra fees. You can instruct OpenClaw to use the SearXNG Skill to search the web. If your server is in the China (Hong Kong) region or a region outside the Chinese mainland, see How to configure the Brave Search feature for OpenClaw to configure the Brave Search API for web search.

How to change the OpenClaw model?

You can switch between different models for OpenClaw in the console. The procedure varies depending on your image version:

• For OpenClaw 2026.5.19 and later: Go to the application details page. In the Models card, find the configured model and click Switch Model to select a different one, or click Add Model to connect to a new model provider. This version supports multiple providers, including AI coding plan, Alibaba Cloud Model Studio Token Plan, Alibaba Cloud Model Studio, deepseek, Kimi, GLM Coding Plan, and Zhipu.

• For versions earlier than OpenClaw 2026.5.19: Go to Application Details > Model Configuration > Model Configuration, delete the default model, and then select a different Alibaba Cloud Model Studio model from the drop-down list.

Pre-installed skills

By default, application images for OpenClaw 2026.2.3 and later include only the built-in SearXNG web search Skill. To use other Skills, you must install them manually using one of the following methods:

• Install in chat: Tell OpenClaw in chat to install the Skill you need, and it will be installed automatically.

• Install by URL: Send the Skill's URL to OpenClaw, and it will be installed automatically.

• Install from ClawHub: Run the clawhub install <skill-name> command to install a Skill from the skill marketplace.

For detailed installation steps, see How to install or add Skills in OpenClaw.

Add or install skills in OpenClaw

You can add skills to OpenClaw in three ways: interactive creation, installation from a URL, and installation from a mirrored source.

• Interactive creation (for new skills)

  OpenClaw has a built-in Skill Creator component. You can chat with the Skill Creator, describe your requirements, and it will automatically create a new skill.

• Install from a URL (for reusing existing skills)

  To install an existing skill, send its URL to OpenClaw for automatic installation. For example, to install the Web Artifacts Builder from Anthropic, simply tell the agent to install the skill during your conversation.

• Install from a mirrored source (for network-restricted scenarios)

  If your server environment cannot access external code repositories like GitHub due to network restrictions, you can use the mirroring method:

  1. Download the files to a local machine.

  2. Upload the code to an accessible storage space (for example, upload to OSS).

  3. Obtain the new download link and send it to OpenClaw for installation, following the same procedure as installing from a URL.

Custom skill loading and priority

Yes. In ~/.openclaw/openclaw.json, use skills.load.extraDirs to add extra directories with the lowest loading priority.

OpenClaw loads skills in the following order of priority, from highest to lowest: <workspace>/skills > ~/.openclaw/skills > built-in > skills.load.extraDirs.

By default, clawhub installs to ./skills, which OpenClaw treats as <workspace>/skills.

Install skills from ClawHub

ClawHub is a dedicated skill marketplace for searching, installing, and managing third-party skills.

• Search a skill (e.g., weather):

  clawhub search weather

• Install a skill:

  clawhub install weather

• View more commands:

  clawhub --help

ClawHub offers an official China mirror. This mirror provides faster access to reusable agent skills by continuously indexing and accelerating high-quality community skills. For details and usage instructions, see the ClawHub China mirror.

ClawHub China mirror site

ClawHub offers an official China mirror site that curates and mirrors high-quality community Skills. This site provides faster access to reusable Agent Skills for users in the Chinese mainland.

Use cases: If your Simple Application Server is deployed in a Chinese mainland region, you might experience high latency or slow downloads when downloading Skills from the default source. Use the ClawHub China mirror site to accelerate downloads.

Procedure:

1. Go to the ClawHub China mirror site to browse or search for a Skill.

2. Find the desired Skill and copy its installation URL from the mirror site.

3. In an OpenClaw chat, send the installation URL to an Agent. The Agent automatically installs the Skill.

The ClawHub China mirror site contains the same content as the default ClawHub source. The only difference is that its download nodes are located in the Chinese mainland to provide faster network access. Users outside the Chinese mainland can use the default source.

Troubleshoot slow Skill downloads

Installing Skills on a Simple Application Server instance in the Chinese mainland region can be slow or time out. This is because default Skill resources are hosted on overseas nodes, which causes high network latency.

Solutions:

• Use the ClawHub China mirror site: Visit the ClawHub China mirror site to get a Skill's mirror URL and download it faster from a domestic node. For details, see How to use the ClawHub China mirror site.

• Use an intermediate source for installation: If you cannot access external code repositories like GitHub, download the Skill files, upload them to an accessible storage space (such as OSS), and then use the new URL to install the Skill in OpenClaw. For details, see the intermediate source installation section in Add or install Skills.

Restart OpenClaw Gateway

openclaw gateway restart

Configure Brave Search

The Brave Search web search feature is available only for Simple Application Server instances in regions outside the Chinese mainland, including China (Hong Kong).

OpenClaw application images, version 2026.2.3 and later, include the SearXNG-based web search Skill by default.

1. Go to the Brave Search official website to create a Brave Search API account and generate an API key.

2. To configure this in the image, go to the OpenClaw page. In the left navigation pane, click to open the configuration file. Change BRAVE_API_KEY to your Brave Search API key, copy the following code block, and paste it to the tools.web.search configuration location.

     "tools": {
       "web": {
         "search": {
           "provider": "brave",
           "apiKey": "BRAVE_API_KEY",
           "maxResults": 5,
           "timeoutSeconds": 30
         }
       }
     },

   In the left navigation pane, go to Config > All Settings > Raw and paste the code block into the tools.web.search section. Click Save in the upper-right corner.

Search coverage for Chinese platforms

Yes, but search coverage varies depending on the platform.

The web search feature in OpenClaw depends on its underlying search engine. By default, OpenClaw uses SearXNG, an open-source metasearch engine that pulls results from multiple sources. You can also configure Brave Search. The coverage of your search results depends on what content the underlying search engine has indexed:

• Public web content indexed by Baidu: Generally searchable.

• Content within closed platforms, such as WeChat Official Account articles or Zhihu answers: Search engine coverage may be incomplete, and some content might not be directly accessible.

For broader search coverage, you can also configure Brave Search. For instructions, see How to configure the Brave Search web search feature for OpenClaw.

Run tools in a Docker container

OpenClaw lets you run tools in a Docker container to mitigate security risks. This is an optional feature. When enabled, OpenClaw executes tools in an isolated sandbox environment. For configuration instructions, see the OpenClaw sandboxing feature guide.

OpenClaw CLI

Log in to the server terminal and switch to the root user to run the following commands.

Effects of console initialization

No. Initializing in the console or reconfiguring an API key does not clear installed Skills, memory, conversation history, or training data. This operation only resets the model connection configuration.

Data persistence on restart

No. A restart does not cause data loss. Your configurations and skills are stored in the ~/.openclaw directory and remain intact unless you reset the system or delete this directory.

Multiple sessions after integration

Yes, this is expected. Integrating a channel like Lark or DingTalk automatically creates a corresponding session. You can manually delete these sessions from the web UI. However, deleting a session prevents you from receiving messages from that channel.

Cluster deployment

OpenClaw is deployed on Simple Application Server using an application image. Each instance runs as a standalone service and cannot be clustered for centralized management.

To scale your service, you can purchase multiple Simple Application Server instances and deploy OpenClaw on each one. Each instance runs and is managed independently.

Using OpenClaw in Model Studio in Singapore with only the free quota

By default, you are charged for model usage in Model Studio (Singapore) after your free quota is exhausted. To prevent these charges, go to the Model Studio platform and enable Stop when free quota is exhausted. After you enable this feature, the model becomes unavailable once its free quota is depleted. You can then switch to another model that has a free quota.

Configure the Free Quota Only feature

By default, you are charged for any usage that exceeds your free quota. When the Free Quota Only feature is enabled, API calls fail with an AllocationQuota.FreeTierOnly error after the free quota is exhausted, preventing unexpected charges.

Configure a Model Studio Coding Plan

1. Copy and save your API key and base URL from Step 2: Get the plan-exclusive API key and base URL.

2. Replace the YOUR_API_KEY placeholder in the appropriate code block below with the API key you obtained in Step 2: Get the plan-exclusive API key and base URL.

   "models": {"mode": "merge","providers": {"bailian": {"baseUrl": "https://coding.dashscope.aliyuncs.com/v1","apiKey": "YOUR_API_KEY","api": "openai-completions","models": [{"id": "qwen3-max-2026-01-23","name": "qwen3-max-thinking","reasoning": false,"input": ["text"],"cost": {"input": 0,"output": 0,"cacheRead": 0,"cacheWrite": 0},"contextWindow": 262144,"maxTokens": 65536}]}}},"agents": {"defaults": {"model": {"primary": "bailian/qwen3-max-2026-01-23"},"models": {"bailian/qwen3-max-2026-01-23": {"alias": "qwen3-max-thinking"}},"maxConcurrent": 4,"subagents": {"maxConcurrent": 8}}},

   "models": {"mode": "merge","providers": {"bailian": {"baseUrl": "https://coding-intl.dashscope.aliyuncs.com/v1","apiKey": "YOUR_API_KEY","api": "openai-completions","models": [{"id": "qwen3-max-2026-01-23","name": "qwen3-max-thinking","reasoning": false,"input": ["text"],"cost": {"input": 0,"output": 0,"cacheRead": 0,"cacheWrite": 0},"contextWindow": 262144,"maxTokens": 65536}]}}},"agents": {"defaults": {"model": {"primary": "bailian/qwen3-max-2026-01-23"},"models": {"bailian/qwen3-max-2026-01-23": {"alias": "qwen3-max-thinking"}},"maxConcurrent": 4,"subagents": {"maxConcurrent": 8}}},

3. On the Simple Application Server console - Servers page, click the instance ID on the OpenClaw server card to open the Server Overview page.

4. Click the Application Details tab. On the Access Control page, click Run Command next to the website URL. In the pop-up window, click the URL to open the OpenClaw chat page.

5. Click to open the configuration file. Copy the code block with the modified "apiKey" parameter, replace the original "agents"{...} content in your configuration code, and save your changes.

Change the default model to qwen3.6-plus

The Lite plan does not support qwen3.6-plus.

In OpenClaw 2026.4.14 images and later, you can select qwen3.6-plus directly from the model drop-down menu on the application details page in the console. For earlier images, configure the model manually:

1. In the OpenClaw web UI, select Configuration > RAW from the left menu bar.

2. In the models.providers.dashscope-coding.models section, add the following model configuration for qwen3.6-plus:

   {
     "id": "qwen3.6-plus",
     "name": "Qwen3.6-Plus",
     "api": "openai-completions",
     "reasoning": false,
     "input": ["text", "image"],
     "cost": {
       "input": 0,
       "output": 0,
       "cacheRead": 0,
       "cacheWrite": 0
     },
     "contextWindow": 1000000,
     "maxTokens": 65536
   }

3. Change the agents.defaults.model.primary parameter to dashscope-coding/qwen3.6-plus.

4. Click Save and then Update.

Server configuration requirements

To ensure service performance, your server must have at least 2 vCPUs and 2 GB of memory.

Additional fees

If you use a Model Studio API key for model invocation on your instance, you will be charged based on token usage. For billing details, see Model Invocation Billing.

OpenClaw API billing

Simple Application Server uses package-based billing. Your package fee includes compute, storage, and bandwidth resources. Calling Simple Application Server OpenAPI operations, such as querying instance information or managing firewall rules, incurs no additional charges.

Calling a large model, such as one from the Model Studio platform, through OpenClaw incurs model invocation fees. These fees are based on token usage and billed separately from your Simple Application Server package fee.

Check model free quota in Singapore using Model Studio

Log in to the Model Studio console. In the Free Quota section, you can view your model's remaining quota.

Model invocation statistics

What are the differences between the Model Studio Singapore, US (Virginia), and China (Beijing) regions?

Alibaba Cloud Model Studio is available in the Singapore, US (Virginia), and China (Beijing) regions. Choose a nearby region to reduce network latency. Service endpoints (Endpoint/Base URL) and API keys are region-specific. Supported models, platform features, and pricing also vary by region. For details, see Select a model.

Cross-region API usage

Yes. A Simple Application Server in an overseas region can call the Model Studio model service in the China (Beijing) region. However, cross-region network latency will significantly increase response times.

Cross-region use

Yes. A Coding Plan subscription takes effect globally and is not restricted by the region of your Simple Application Server. For example, if you purchase a Coding Plan in the North China region, Simple Application Servers in other regions, such as the United States and Singapore, can use the plan's exclusive API key to call the model. You do not need to repurchase the plan for each server region.

Manage files

When you use OpenClaw, the agent stores generated files—such as code, reports, or images—in the /home/admin/.openclaw/ directory by default.

Finding generated files:

• In the terminal, use the ls command to list the files in the current directory.

• Use the find / -name "filename" command to search the entire instance for a file.

• You can also ask the agent in the OpenClaw chat for the file's path.

Uploading and downloading files:

You can upload and download files using the file management feature in Workbench. For details, see Upload or Download Files via Workbench.

Troubleshoot unresponsive OpenClaw chat

1. Verify your API key configuration: Connect remotely to your Simple Application Server instance. In the following code block, replace the placeholders with your API key and the base URL for your region. Run the command in your terminal to test the API call. If you get an error, find it in the error code documentation and follow the recommended solution. Base URLs are region-specific and cannot be used interchangeably:

   • China (Beijing): https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

   • US (Virginia): https://dashscope-us.aliyuncs.com/compatible-mode/v1/chat/completions

   • Singapore: https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions

   • Coding Plan: https://coding-intl.dashscope.aliyuncs.com/v1/chat/completions

   curl -X POST YOUR_BASE_URL \
   -H "Authorization: Bearer YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
       "model": "qwen3-max-2026-01-23",
       "messages": [
           {
               "role": "user",
               "content": "Who are you?"
           }
       ]
   }'

2. Check for overdue payments or rate limiting.

   1. Coding Plan: This plan has 5-hour, weekly, and monthly request limits. You can check your quota usage in the Coding Plan console. Exceeding a limit triggers an hour/week/month allocated quota exceeded error.

      Solution: Wait for the quota to reset automatically.

   2. For pay-as-you-go Model Studio API keys:

      1. To check your free quota, log in to the Model Studio console. The Free Quota section shows the remaining quota for the model.

      2. To check for overdue payments, visit the Expenses and Costs center and confirm that your account has no outstanding balance.

3. Check the error logs: Go to the OpenClaw Chat page. In the left navigation pane, click Logs, and then select the WARN and ERROR checkboxes to view the error logs. Look up the error in the OpenClaw FAQ for a solution.

   If the logs show no errors, restart the gateway from the console.

4. Reset the image

   If the server contains no important data, you can reset the Simple Application Server image to the latest OpenClaw application image and reconfigure the service.

   Important

   The Reset System operation reinstalls the operating system and erases all data from the system disk, including saved configurations, logs, and databases. Before you proceed, you must back up important data. We recommend creating a snapshot or exporting the data to a local device. To preserve your OpenClaw workspace data, such as memory, identity configuration, and Skills, see Back up and restore data for OpenClaw upgrades.

OpenClaw: HTTP 400 input length error

This error occurs when the accumulated context in a conversation exceeds the model's input limit. To resolve this, run the /new command on the OpenClaw conversation page to start a new conversation.

'openclaw skills list' fails to list installed skills

If running openclaw skills list returns an empty list or fails to list the expected skills, this is usually due to one of the following reasons:

• Current directory is outside the workspace: The openclaw skills list command only scans the skills directory within the current workspace and the ~/.openclaw/skills directory. If you run the command from any other directory, it cannot detect installed skills. Change to the OpenClaw workspace root directory and run the command again.

• Skills installed to a different path: By default, clawhub install installs skills to a ./skills directory within the current directory. If you ran the installation from a directory other than your OpenClaw workspace, openclaw skills list cannot find these skills. Ensure the installation path is your OpenClaw workspace, or copy the skill directories to the ~/.openclaw/skills directory.

• Outdated image version: Instances created before January 30, 2026, may not have the clawhub CLI tool or the openclaw skills subcommand pre-installed. In this case, you must reset the current application image to the latest version.

Verification Steps:

1. Change to the OpenClaw workspace root directory:

   cd ~/.openclaw

2. Verify that the skills directory exists and contains your skills:

   ls skills/

3. Rerun the skills list command:

   openclaw skills list

To install new skills from the skill marketplace, use clawhub search to find new skills and clawhub install to install them. For detailed instructions, see Install skills from ClawHub.

Restart the OpenClaw gateway

If a connection is interrupted or the service becomes unavailable, restart the OpenClaw gateway on the console. Go to Application Details > Basic Configuration > Restart OpenClaw Gateway and click Restart Server.

HTTP 401 error in OpenClaw

This error usually occurs if the initialization steps on the application details page failed, you did not enter an API Key, you entered a third-party (non-Model Studio) API Key, or the region you selected does not match the region of the API Key.

Solution:

1. In the Simple Application Server console, go to the Application Details page for the instance and reconfigure the Model Studio API Key or Coding Plan in the initialization step.

2. Restart the OpenClaw gateway.

3. Access the latest WebUI address and confirm that the error is resolved.

Configuration save failures

If you cannot save changes or see outdated values after modifying an API key or model configuration on the application details page in the console, use the following scenarios to troubleshoot.

Scenario 1: Third-party model configuration shows outdated values in the console

The application details page in the Simple Application Server console can only display and modify models from Alibaba Cloud Model Studio. It does not display or allow changes to third-party models, such as DeepSeek or MiniMax. If you have integrated a third-party model by using the ~/.openclaw/openclaw.json configuration file on the server, this is expected, and the console will continue to display the Model Studio configuration.

To modify the API key for a third-party model, directly edit the configuration file on the server. After saving your changes, run openclaw gateway restart to apply the new configuration.

Scenario 2: Error when saving a Model Studio API key in the console

If an error occurs when you save a Model Studio API key in the console, follow these steps to troubleshoot the issue:

1. Verify the API key format: An API key for Model Studio typically starts with sk-, while a Coding Plan API key starts with sk-sp-. When pasting the key, ensure it has no leading or trailing whitespace or newline characters.

2. Ensure the correct region is selected: The API key must match the selected region. For example, a key for the Beijing region can only be used in Beijing, not in the Singapore or Virginia regions.

3. Check your network connectivity: If you see request timeouts or network errors in your browser developer tools, try refreshing the page and saving the configuration again.

4. Verify that the API key is valid: Go to the Coding Plan page to confirm the key is still valid.

Scenario 3: Changes to the configuration file do not take effect

After modifying the ~/.openclaw/openclaw.json file, you must restart the gateway to apply the changes:

openclaw gateway restart

After the gateway restarts, run the following command to verify that the new configuration is loaded:

openclaw models list

If the list displays the updated model configuration, the changes have been applied successfully.

OpenClaw browser tool issues

The error message is:

error [tools] browser failed: timed out. Restart the OpenClaw gateway (OpenClaw.app menubar, or 'openclaw gateway'). Do NOT retry the browser tool — it will keep failing. Use an alternative approach or inform the user that the browser is currently unavailable.

To resolve this error, restart the OpenClaw gateway.

Blocked skill installation

The OpenClaw management interface provides one-click installation for some skills. However, most skills depend on Homebrew, so they do not support one-click installation. To use these skills, install Homebrew on your server, and then install and configure them.

"Disconnected (1008): unauthorized" error

This error indicates that the authentication token is missing from your access URL. The OpenClaw web console prohibits direct access by IP address and requires a URL that contains a valid authentication token. To get the correct access URL, go to the server console and click the instance ID on the server card to open the server overview page. Click the Application Details tab. On the access control page, click Run Command to retrieve the correct access URL.

Resolve the "control ui requires device identity" error

Log in to the server and modify the dangerouslyDisableDeviceAuth parameter in the OpenClaw configuration file to disable device identity verification.

1. Log in to the Simple Application Server console. On the Servers page, find the target server card and click Remote Connection. In the Connect with One-click on Workbench section, click Log on Now.

2. Run the following command to edit the OpenClaw configuration file.

   vim ~/.openclaw/openclaw.json

3. In the gateway configuration, find "dangerouslyDisableDeviceAuth": false and change false to true. Then, save the file and exit.

4. Run the following command to restart the Gateway service for the changes to take effect.

   openclaw gateway restart

Resolve the "disconnected (1006): no reason" error

Follow these steps to troubleshoot the issue:

1. Regenerate the token: Log in to the Alibaba Cloud Simple Application Server console, find the instance, and navigate to the application details page to regenerate the token.

2. Use the new token to access the application: Append the new token to the access URL in the format http://<public IP address>:<port>/?token=<newly-generated-token> (use the port from the access URL shown in the console), and test the URL in an incognito window.

3. Confirm the service status: Connect to the server using SSH and verify that the OpenClaw service is running.

4. Check the firewall rules: Ensure that the firewall for your Simple Application Server instance allows inbound TCP traffic on the listening port.

   A WebSocket connection can also fail due to an incorrect public IP address binding or a misconfigured reverse proxy. First, test connectivity from your local machine using curl or telnet.

Resolve the "origin not allowed" error

Using a custom domain name instead of an IP address to access the OpenClaw Web UI can cause the following error: origin not allowed (open the Control UI from the gateway host or allow it in gateway.controlUi.allowedOrigins).

Cause: By default, the OpenClaw gateway only allows Web UI access from the server's IP address. When you access the UI using a domain name, the gateway blocks the request because the origin is not on the allowlist.

Log on to the server to modify the OpenClaw configuration file, openclaw.json, and add the domain name to the allowedOrigins parameter.

1. Log on to the Simple Application Server console. In the server list, find the target server and click Remote Connection on its card. In the Connect with One-click on Workbench section, click Log on Now.

2. In the OpenClaw configuration file, find the allowedOrigins field and add your domain name's full access URL.

   "allowedOrigins": [
     "http://47.**.**.59:15386",
     "http://openclaw-us.hewushui.cn:15386"
   ]

   Replace the example address with your actual protocol, domain name or IP address, and port.

3. After saving the file, restart the OpenClaw gateway to apply the changes.

Troubleshoot OpenClaw web UI access

If you cannot access the OpenClaw Web UI, log in to the Simple Application Server console and check the following:

1. Open the port for OpenClaw: In the server list, find the target server and click Manage OpenClaw. In the OpenClaw Usage Steps section, on the Allow Port Access tab, click One-Click Enable.

   If you have reset the image, you must re-initialize the server to obtain a new Web UI URL.

2. Verify the configuration file: Go back to the server list and click Remote Connection on the target server. In the Connect with One-click on Workbench section, click Log on Now. Run the following command:

   openclaw doctor --fix

   This command automatically removes unsupported fields, such as allowlist, from openclaw.json.

3. After the command finishes, restart the OpenClaw gateway to apply the new configuration.

Resolve the "401 Unauthorized" error

When you use a model from Alibaba Cloud Model Studio, you may receive the error: Failed to discover Alibaba Cloud models: 401 Unauthorized.

Possible causes: A 401 error typically results from an incorrect API key, a mismatch between the API key's region and the request's base URL, or insufficient invocation permissions for the workspace or account.

Troubleshooting and solutions:

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \

- H "Authorization: Bearer DASHSCOPE_API_KEY" \

- H "Content-Type: application/json" \

- d '{

    "model": "qwen3-max-2026-01-23",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "Who are you?"
        }
    ]
}'

"openclaw: command not found" error

Run the following command to create a symbolic link:

ln -sf /home/clawdbot/dist/entry.js /usr/bin/openclaw
openclaw --help

Unable to retrieve token after enabling Tailscale

This issue occurs because Tailscale modifies the routing policy. To retrieve the token, run the following command:

1. Log in to the OpenClaw server terminal.

2. Run the following command:

   echo $(sed -z 's/.*"token": "\([^"]*\)".*/\1/' /root/.clawdbot/clawdbot.json | tr -d '\0')

3. The command output is the token.

OpenClaw public network inaccessibility

The OpenClaw service is inaccessible from the public network because port 18789 is listening on 127.0.0.1.

Possible cause: The bind parameter in the OpenClaw configuration file was likely modified. By default, this parameter is set to lan, which allows public network access. If this parameter is changed to loopback and the service is restarted, the port will listen only on the local loopback address 127.0.0.1.

Solution:

1. Log on to the server and check the configuration. Log on to your Simple Application Server as the admin user and run the following command to check the current configuration of the bind parameter:

   cat /home/admin/.openclaw/openclaw.json | grep bind

2. Modify the configuration file. Check the command output. If the result is "bind": "loopback", edit the configuration file and change the parameter back to the default, "lan".

3. Restart the gateway service. After modifying and saving the configuration file, run the following command to restart the gateway service:

   openclaw gateway restart

   After the restart, the service will be accessible from the public network.

Error on openclaw gateway restart

When you try to restart the gateway service, the openclaw gateway restart command reports an error, and the service fails to restart.

Solution: If the restart command fails, you can restore the service by manually stopping the process and then restarting it. Follow these steps:

1. Log in to the server. Use the admin user to log in to the Simple Application Server.

2. Terminate the current process. To terminate the openclaw-gateway process, run the following command:

   killall openclaw-gateway

3. Restart the service. Then, run the following command to restart the gateway service:

   openclaw gateway start

   Note: You can safely ignore any error messages from this command.

4. Verify the service status. After you run the start command, run the ps aux | grep gate command to check if the openclaw-gateway process has started successfully, and run the netstat -nltp command to confirm that the relevant ports are in a listening state.

Frequent downtime, memory exhaustion, or OOM Killer triggers

• Upgrade the instance configuration
  We recommend you upgrade the instance configuration to at least 2 vCPUs and 2 GB of memory to improve OpenClaw stability and reduce issues such as server downtime, website inaccessibility, and memory exhaustion.
  
  
  
  

• Check and add a swap partition
  By default, OpenClaw application images released on or after February 26, 2026, include a swap partition. If your instance uses an earlier application image, you can either configure a swap partition manually or reset the current application image to the latest version. A swap partition acts as a buffer when memory is low, reducing OOM Killer triggers and downtime.
  
  
  
  

Switch from Coding Plan to Token Plan

Steps:

1. Go to the Model Studio console and subscribe to the Token Plan team edition.

2. Follow the instructions in How to integrate the Model Studio Token Plan team edition with OpenClaw to configure your Token Plan.

3. Once the configuration is complete, OpenClaw automatically uses Token Plan models for conversations.

Integrate Model Studio Token Plan (Team) with OpenClaw

The Token Plan Team Edition is a monthly subscription with a shared token quota that lets teams access a variety of models, such as qwen3.7-max, qwen3.6-plus, deepseek-v4-pro, kimi-k2.6, glm-5.1, and MiniMax-M2.5. Once integrated with OpenClaw, you can use these models in conversations.

Procedure

1. Ensure you are subscribed to Token Plan Team Edition.

Modify the configuration file:

Shutting down and chat history

No. Shutting down (stopping) a Simple Application Server instance does not delete the OpenClaw chat history. The chat history is stored on the instance's disk. However, OpenClaw is unavailable while the instance is shut down. You must restart the instance to access OpenClaw and start new conversations.

The following operations will delete the chat history:

• Reset system: Resetting the system is equivalent to reinstalling the operating system. This operation erases all data on the system disk, including the OpenClaw chat history, configuration, and database. To preserve OpenClaw workspace data (such as memory, identity configuration, and Skills), see Back up and restore data for OpenClaw upgrades before you reset the system.

• Release instance: Releasing a Simple Application Server instance permanently deletes the instance and all of its data, including the chat history.

Resource requirements and coexistence

• Resource requirements: To ensure OpenClaw runs stably, your Simple Application Server instance should have at least 2 vCPUs and 2 GB of memory. Insufficient memory in lower-specification instances can trigger the OOM Killer, leading to service interruptions.

• Swap partition: Images released on or after February 26, 2026, include a swap partition by default. To alleviate memory pressure on older images, manually configure a swap partition or reset your instance to the latest image.

• Coexistence risk: We do not recommend deploying OpenClaw and other agents, such as Hermes, on the same low-specification server. This can lead to resource contention, performance degradation, or functional conflicts. We recommend deploying each agent on a separate instance.

Set up OpenClaw for family or friends

Yes. Each OpenClaw instance requires a dedicated Simple Application Server and cannot be shared by multiple users. To set up OpenClaw for family or friends, you'll need to purchase a new Simple Application Server and go through the entire deployment process again.

Follow these steps:

1. Purchase a new Simple Application Server and select the OpenClaw image.

2. Follow the deployment tutorial to complete all steps, including API Key configuration and integration with an IM platform (such as DingTalk, Lark, or WeCom).

3. Each server is configured independently, so changes to one instance do not affect others.