OpenClaw常见问题文档概述了用户在使用过程中可能遇到的主要问题及其解决方案。 - 轻量应用服务器

镜像更新与重置问题

已购买的轻量应用服务器，如何部署OpenClaw镜像？

登录轻量应用控制台，选择对应实例单击重置系统。
选择重置为其他镜像，选择版本Openclaw 2026.3.13。
重新配置OpenClaw。重置后之前配置的API Key和Token都会失效，需要到应用详情里重新配置API Key。

警告

重置系统操作相当于重装系统，会清空系统盘内的所有数据（包括已保存的配置、日志和数据库）及停止轻量服务器中正在运行的业务程序。在执行操作前，请务必备份重要数据（建议创建快照或将数据导出到本地）。

如何重置当前应用镜像至最新版本？

重要

重置系统操作相当于重装系统，会清空系统盘内的所有数据（包括已保存的配置、日志和数据库）。在执行操作前，请务必备份重要数据（建议创建快照或将数据导出到本地）。

若当前镜像不是Openclaw 2026.3.13版本，希望体验最新OpenClaw能力，可重置系统来更新镜像。

登录轻量应用控制台，选择对应实例单击重置系统。
选择重置当前系统。
重新配置OpenClaw。重置后之前配置的API Key和Token都会失效，需要到应用详情里重新配置API Key。

OpenClaw功能配置问题

OpenClaw报错“API rate limit reached”怎么办？

请按以下顺序排查：

OpenClaw 配置错误。
若 Base URL 或模型提供商配置有误，导致请求未进入 Coding Plan 专属通道，而是被路由到了通用的API 调用，从而触发限流。
- 若使用 Coding Plan 套餐，请核对OpenClaw配置文件中的 models、agents、gateway（含嵌套字段），确保与文档配置一致。例如：模型服务提供商的结构为{ "models": { "providers": { "bailian": {...} } } } 。
- 若当前未使用 Coding Plan 套餐，建议切换至 Coding Plan 以获取专属额度。
超出套餐限额：在Coding Plan页面查看套餐用量情况。
- 若额度已用尽，在该页面查看下一次额度重置的时间。
- 若频繁触达限额，建议升级至 Pro 套餐以获取更多调用次数。
尝试重置 API Key：若完成上述排查后问题仍未解决，请前往Coding Plan页面重置 API Key。

如何查看OpenClaw的端口号？

为了防止恶意扫描与定向攻击，OpenClaw 在初始化时会自动生成一个随机端口。在应用详情 > 基础配置 > 查看端口中单击查看查看OpenClaw的端口号。

部署在轻量应用服务器上的OpenClaw，能否授权控制本地电脑的应用？

不支持。由于轻量应用服务器运行在云端网络环境，与本地电脑网络相互隔离，因此无法直接跨网络控制本地桌面的应用程序。

为什么OpenClaw应用镜像更新至最新版本仍无法使用联网搜索功能？

请前往轻量应用服务器控制台，在镜像信息模块查看并确保已更新至OpenClaw 2026.2.3及以上版本应用镜像，若不是该版本需要参考如何重置当前应用镜像至最新版本？进行更新。该版本应用镜像在所有地域均默认提供基于内置SearXNG联网搜索Skill的联网搜索能力，无需额外配置，不收取额外费用，可直接告诉OpenClaw使用SearXNG的Skill进行联网搜索。若服务器部署在中国香港或海外地域时，可参考OpenClaw如何配置Brave Search联网搜索功能配置Brave Search API以实现联网搜索。

OpenClaw如何配置其他模型服务商？如何更换第三方模型服务？

当前OpenClaw镜像默认已初始化阿里云百炼 (Bailian) Provider，可直接在设置中修改其使用的具体 Model。如需接入 OpenAI、Anthropic、Google Gemini 或其他厂商的模型服务，请参考如下步骤进行配置。

使用 admin 用户登录轻量应用服务器。
更改模型提供商（以OpenRouter为例）。
```
openclaw onboard
```
验证修改。登录网页控制台，与Agents进行对话验证。

如何更改OpenClaw调用的模型？

OpenClaw集成了阿里云百炼平台，在页面切换不同的模型。在应用详情 > 模型配置 > 模型配置中删除默认的模型，然后下拉选择不同的百炼模型。

支持手动输入模型名，模型Code可以在百炼模型广场页面查询。

如何在OpenClaw中安装或添加Skills？

OpenClaw 支持通过对话交互、链接安装以及转存安装三种方式来添加 Skill，具体操作如下：

交互式创建（适用于新建 Skill）。
OpenClaw 内置了 Skill Creator 组件。可直接与 Skill Creator 进行对话聊天，描述需求，让它自动创建一个全新的 Skill。
通过 URL 安装（适用于复用现有 Skill）。
如需安装已经开发好的 Skill，只需将该Skill的URL地址发送给 OpenClaw，系统即可自动完成安装。例如安装anthropics提供的网页搭建工具Web Artifacts Builder，只需在对话中告诉 Agent 安装该 Skill 即可系统自动完成。
中转源安装（适用于网络受限场景）。
如果所在的服务器网络环境无法访问 GitHub 等外部代码库，可以采用转存的方式：
1. 先将文件下载到本地。
2. 将代码上传至可访问的存储空间（例如上传到OSS）。
3. 获取新的下载链接，按照通过 URL 安装的步骤将该链接发送给 OpenClaw 进行安装。

是否支持从自定义文件夹加载 Skills？OpenClaw中Skills加载的优先级是什么？

可以。通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 添加额外目录（最低优先级）。

默认加载Skills的优先级为：<workspace>/skills > ~/.openclaw/skills > 内置> skills.load.extraDirs。

clawhub 默认安装到 ./skills，OpenClaw会将其视为 <workspace>/skills。

安装ClawHub上的Skills

ClawHub是专属的技能市场管理工具，用于搜索、安装和管理第三方技能。

搜索技能（以 weather 为例）：
```
clawhub search weather
```
安装技能：
```
clawhub install weather
```
其他命令详见：
```
clawhub --help
```

支持在镜像内部升级OpenClaw版本吗/支持在线升级OpenClaw版本吗？

目前暂不支持，可以通过重置当前应用镜像至最新版本。

重要

如何重启OpenClaw Gateway 网关服务?

OpenClaw 2026.2.9版本及以上

可以通过控制台页面直接完成重启操作：在应用详情 > 基础配置 > 重启OpenClaw网关中单击重启。

OpenClaw 2026.2.9之前的版本

需要通过命令行终端手动完成重启操作：远程连接至轻量应用服务器，在终端用 Gateway 网关辅助命令：

openclaw gateway restart

轻量服务器里安装的OpenClaw不同配置文件是做什么的？

配置文件目录：/root/.openclaw/
主配置文件：/root/.openclaw/openclaw.json（包含使用的模型）
模型api-key配置文件：/root/.openclaw/agents/main/agent/auth-profiles.json

可以直接修改配置文件，增加模型、增加api-key配置。

如何在OpenClaw中手动配置百炼购买的Coding Plan？

复制并保存Coding Plan的套餐专属 API Key。

将下面代码块中"apiKey": "YOUR_API_KEY"中的YOUR_API_KEY替换为您的套餐专属 API Key。

 "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
      }
    }
  },

在轻量应用服务器控制台-服务器页面，单击部署了OpenClaw的服务器卡片中的实例ID，进入服务器概览页面。
单击应用详情页签，在访问控制页面单击打开网站页面右侧的执行命令后，单击弹窗中的网站地址URL链接可进入OpenClaw对话页面。
单击Config > All Settings > Raw，打开配置文件。复制上述修改完"apiKey"参数的代码块，按照下图所示操作替换您的配置代码中的原"agents"{...}内容后保存修改。

OpenClaw如何配置Brave Search联网搜索功能？

仅中国香港和海外地域轻量应用服务器实例可以配置Brave Search使用联网搜索功能。

OpenClaw 2026.2.3及以上版本应用镜像已默认内置基于SearXNG的联网搜索Skill。

在Brave Search官网创建 Brave Search API 账户，并生成API密钥。
在镜像中配置，进入 OpenClaw 页面，在左侧导航栏单击Config > All Settings > Raw，打开配置文件。将BRAVE_API_KEY更改为Brave Search API密钥，复制下面代码块到配置文件中，并粘贴到如图所示位置。
```
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "BRAVE_API_KEY",
        "maxResults": 5,
        "timeoutSeconds": 30
      }
    }
  },
```

如何在OpenClaw中使用Docker容器运行工具？

OpenClaw 支持在 Docker 容器中运行工具，即降低潜在风险的影响范围。该功能为可选项，当该功能启用时，工具的执行将在隔离的沙箱环境中进行。具体配置操作可参见OpenClaw sandboxing功能介绍。

OpenClaw常用命令行工具（CLI）有哪些？

重要

如果实例创建于 2026年1月30日之前，可能会因版本过旧导致无法使用以下命令。请先参照如何重置当前应用镜像至最新版本？升级镜像，新版镜像已预装所有必要的 CLI 工具。

登录服务器终端，切换到 root 用户执行以下命令。

核心管理工具：OpenClaw
OpenClaw 是系统内置的核心 CLI。查看已安装技能 (Skills)。
```
openclaw skills list
```
插件与通道管理：Plugins
通过 openclaw plugins 命令管理扩展插件。
查看插件命令帮助：获取安装、配置插件的完整指令列表。
```
openclaw plugins -h
```

购买与费用问题

如何配置OpenClaw仅使用百炼新加坡地域免费额度，不产生额外费用？

默认状态下，百炼大模型（新加坡地域）在免费额度消耗完后，继续使用会扣费，若希望不产生超出免费额度外的模型调用费用，可前往百炼平台开启免费额度用完即停。配置完成后，模型免费额度消耗完毕将无法使用，模型免费额度用完后可更换拥有免费额度的模型继续使用。

如何配置百炼模型的免费额度用完即停？

默认状态下，免费额度消耗完后继续使用会扣费。启用免费额度用完即停功能后，免费额度耗尽将无法继续调用（返回错误 code：AllocationQuota.FreeTierOnly），避免产生额外费用。

方式一：在模型用量页面开启

为单个模型开启：

在控制台的模型用量页面，点击免费额度页签。
在页面列表中找到目标模型，在其右侧操作列中打开免费额度用完即停开关（若该模型没有免费额度，则无法开启）。

批量开启：

在控制台的模型用量页面，点击免费额度页签。
点击批量操作免费额度用完即停，在下拉菜单中选择批量开启。
勾选目标模型，点击批量开启。若需为所有支持且未开启的模型启用此功能，可点击一键开启所有模型。
在确认弹窗中，点击开启免费额度用完即停。

方式二：在模型广场页面开启

以 Qwen3-Coder-Plus 为例。前往Qwen3-Coder-Plus 模型详情页（新加坡地域）并开启免费额度用完即停开关。

若模型没有显示开关，说明该模型免费额度已耗尽或过期，或模型本身没有提供免费额度。

购买OpenClaw服务器配置有要求吗，是否所有配置都可以选择OpenClaw镜像？

需选择2核2G及以上配置以保障服务性能。

购买部署OpenClaw应用镜像的轻量应用服务器实例后，使用实例时还会产生其他费用吗？

若为实例中的OpenClaw配置了百炼提供的 API Key进行模型调用，则会基于 token 用量产生费用，具体计费规则遵循百炼平台的模型调用计费说明。

如何查询新加坡地域百炼中模型的免费额度还剩多少？

登录百炼控制台后，在免费额度区域可查看到您账户下该模型的剩余免费额度。

如何查看阿里云百炼的模型调用记录？

模型调用完一小时后，在模型监控（新加坡或北京）页面设置查询条件（例如，选择时间范围、业务空间等），再在模型列表区域找到目标模型并单击操作列的监控，即可查看该模型的调用统计结果。具体请参见模型监控文档。

数据按小时更新，高峰期可能有小时级延迟，请您耐心等待。

百炼的国际（新加坡）、美国（弗吉尼亚）和中国内地（北京）地域有什么区别？

阿里云百炼提供国际（新加坡）、美国（弗吉尼亚）和中国内地（北京）地域的模型服务，选择邻近地域调用可降低网络延迟。不同地域的服务接入点（Endpoint/Base URL）不同，且API Key不通用，支持的模型、平台功能及价格也有所不同，详情请参见模型列表。

故障排查

在OpenClaw的Chat页面对话无返回内容或无响应怎么办？

检查API Key配置是否正确：远程连接至轻量应用服务器中，将配置的API Key及对应地域的Base URL替换进下方代码块，复制并粘贴至终端后测试模型调用。若返回报错信息，可在错误信息文档中搜索报错内容并根据方案处理。不同地域的 Base URL 不通用：
- 华北2（北京）： https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
- 美国（弗吉尼亚）： https://dashscope-us.aliyuncs.com/compatible-mode/v1/chat/completions
- 新加坡： 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_API_KEY_BASE_URL \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3-max-2026-01-23",
    "messages": [
        {
            "role": "user",
            "content": "你是谁？"
        }
    ]
}'
```
检查模型服务是否欠费或限流情况。
1. Coding plan：套餐存在每 5 小时、每周、每月的限额请求次数，您可以在Coding Plan 控制台查看套餐额度消耗情况。当超出限制时会报错hour/week/month allocated quota exceeded。
  解决办法：需等待额度自动恢复或升级至 Pro 套餐。
2. 按Token计费的百炼API Key：
  1. 查看免费额度，登录百炼控制台后，在免费额度区域可查看到账户下该模型的剩余免费额度。
  2. 查看账号欠费，可以访问费用与成本中心，确保账户没有欠费。
排查错误日志：前往OpenClaw Chat页面，在左侧导航栏单击Logs，并勾选WARN、ERROR查看错误日志，并在OpenClaw常见问题文档中搜索对应报错的解决方案。
如果Logs日志无错误输出，可在控制台重启网关。
重置镜像
如果确认服务器里没有重要数据，可以考虑重置轻量应用服务器镜像，重置为最新的openclaw应用镜像，重新配置使用。
重要
重置系统操作相当于重装系统，会清空系统盘内的所有数据（包括已保存的配置、日志和数据库）。在执行操作前，请务必备份重要数据（建议创建快照或将数据导出到本地）。

OpenClaw页面报错 HTTP 401: invalid access token or token expired如何解决？

错误提示Token过期了，需到轻量应用服务器控制台应用详情页面里，重新获取OpenClaw登录地址后，再访问查看。

OpenClaw的Skills安装为什么提示blocked？

OpenClaw管理界面提供了部分skills组件的一键安装能力，但是大部分组件安装依赖brew软件，所以无法一键安装，如果用户需要使用skills，可以给服务器安装brew，然后进行调试。

访问OpenClaw网站报错 "disconnected (1008): unauthorized" 怎么解决？

这是因为您的访问链接中缺少身份验证 Token。OpenClaw 的 Web 控制台不允许直接通过 IP 访问，必须在 URL 中携带正确的 Token 参数。可以在服务器控制台，单击服务器卡片中的实例ID，进入服务器概览页面。单击应用详情页签，在访问控制页面的区域单击执行命令获取正确的token访问地址。

访问OpenClaw网站报错 "disconnected (1008): control ui requires HTTPS or localhost (secure context)" 怎么解决？

这个错误是token没初始化导致的，需要轻量应用服务器控制台的应用详情页面，第二步设置一下apikey ，然后再获取访问链接访问。

访问OpenClaw网站报错 "disconnected (1006): no reason" 怎么解决？

建议按以下步骤排查：

重新生成 token：请登录阿里云轻量应用服务器控制台，找到实例进入应用详情页，重新生成新的 token。
使用新 token 访问：将新 token 拼接到访问地址中，格式为 http://XXX:18789/?token= 新生成的token，并在无痕窗口中打开测试。
确认服务运行状态：通过 SSH 登录服务器，确认OpenClaw服务正在运行。
检查防火墙规则：确保轻量服务器的防火墙已放行监听端口的入方向流量（协议类型为 TCP）。
若服务未正确绑定公网 IP 或反向代理配置错误，也可能导致 WebSocket 连接失败。建议优先通过本地 curl 或 telnet 测试是否可连通。

提示 "Failed to discover Alibaba Cloud models: 401 Unauthorized" 怎么办？

在使用阿里云百炼（Model Studio）模型时，系统报错 Failed to discover Alibaba Cloud models: 401 Unauthorized。

可能原因：出现 401 错误，通常是由于 API Key 填写错误、API Key 所属地域与请求的 Base URL 地域不一致，或者对应业务空间/账号缺乏调用权限导致。

排查与解决方法：

排查一：检查 API Key 与地域配置是否一致

国内账号使用的百炼 API Key 通常属于北京地域，默认对应的也是北京地域的 Base URL。如果地域配置错位，将导致 401 错误。

控制台检查： 在轻量应用服务器控制台配置 API Key 时，请确认选择的百炼地域是否正确。北京地域的 API Key 只能用于北京地域，请勿错误配置为“新加坡”或“美国（弗吉尼亚）”。
配置文件检查： 可登录对应服务器，查看底层配置文件，确认 API Key 被配置到了哪个地域。
执行以下命令查看配置：
```
cat /home/admin/.openclaw/agents/main/agent/auth-profiles.json
```
配置文件字段说明：
- alibaba-cloud：默认北京地域配置（北京地域的 API Key 必须配置在此节点下才能正常使用）。
- alibaba-cloud-international：新加坡地域配置。
- alibaba-cloud-us：美国（弗吉尼亚）地域配置。

排查二：检查业务空间的模型调用权限

如果使用的 API Key 不属于“默认业务空间”，请检查该业务空间是否具备目标模型的调用权限。

登录百炼控制台，查看当前 API Key 所属的业务空间。
非默认业务空间默认不开启模型调用权限。需要进入该业务空间设置内，手动开启对应模型（如 qwen3-max-2026-01-23 等）的调用权限。

排查三：验证 API Key 状态是否正常

如果以上配置均正确，需验证 API Key 本身是否存在填写错误、账号欠费或失效等情况。详情可参考curl。

可在本地终端运行以下 curl 命令进行连通性测试（请将 DASHSCOPE_API_KEY 替换为实际的 API Key）：

获取 API Key 请访问：获取 API Key 文档。以下命令使用的是北京地域的 URL。如果使用的是新加坡地域的模型，请将请求地址替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions。

测试命令：

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": "你是谁？"
        }
    ]
}'

如果该命令同样返回 401 错误，说明您的 API Key 本身无效或账户存在欠费，请前往阿里云百炼控制台重新生成 Key 或检查账户余额。

轻量应用服务器终端中报错显示没有openclaw命令如何解决？

可以添加软连接，执行命令：

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

启用Tailscale 后无法获取Token，该如何处理？

这是由于 Tailscale 修改路由策略导致的。请尝试使用以下替代命令，直接在实例内部读取 Token 信息：

登录OpenClaw服务器终端。

运行以下命令：

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

终端输出的字符串即为 Token。

OpenClaw 端口 18789 监听在 127.0.0.1，外网无法访问怎么办？

OpenClaw 的 18789 端口监听地址显示为 127.0.0.1，导致无法通过外网访问该服务。

可能原因：OpenClaw 配置文件中的 bind 参数被更改。该参数默认配置为 lan（允许公网访问），如果被修改为 loopback 并重启了服务，端口就会仅监听本地回环地址 127.0.0.1。

解决方法：

登录服务器并检查配置。使用 admin 用户登录轻量应用服务器，执行以下命令检查 bind 参数的当前配置：
```
cat /home/admin/.openclaw/openclaw.json | grep bind
```
修改配置文件。查看命令输出结果。如果发现配置为 "bind": "loopback"，请编辑该配置文件，将其修改回默认的 "lan" 模式。
重启 Gateway 服务。修改并保存配置文件后，执行以下命令重启 Gateway 服务，使配置生效：
```
openclaw gateway restart
```
重启完成后，端口将恢复正常的监听状态，即可恢复外网访问。

执行 openclaw gateway restart （重启网关）命令报错，服务重启失败怎么办？

在尝试重启网关服务时，执行 openclaw gateway restart 命令出现报错，导致服务无法成功重启。

解决方法：当常规重启命令执行失败时，可以通过手动结束进程并重新启动服务来恢复。请按照以下步骤进行操作：

登录服务器。使用 admin 用户登录轻量应用服务器。
结束当前进程。执行以下命令，强制结束当前的 OpenClaw Gateway 进程：
```
killall openclaw-gateway
```
重新启动服务。进程结束后，执行以下命令重新启动 Gateway 服务：
```
openclaw gateway start
```
说明： 在执行启动命令时，系统如果输出报错提示，可暂时忽略。
验证服务状态。启动命令执行完成后，执行命令ps aux | grep gate查看openclaw-gateway 进程是否已经成功拉起，并执行netstat -nltp确认相关端口是否已处于正常的监听状态。

轻量应用服务器经常宕机/内存满/OOM Killer触发怎么办？

升级实例配置
建议升级实例配置，将服务器配置升级至 2核2G及以上，以提升 OpenClaw 运行稳定性，降低因资源不足导致的服务器宕机、网站无法访问、内存占满等问题。
检查并补充 Swap 分区
2026年2月26日之后的 OpenClaw 应用镜像已默认配置 Swap 分区；若实例是更早版本镜像，建议手动配置 Swap 分区，或直接重置当前应用镜像至最新版本，可在内存不足时提供缓冲，减少 OOM Killer 触发、服务异常中断等情况。