OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

故障排查

故障排查

clawhub login 打开浏览器但始终无法完成

CLI 在浏览器登录期间会启动一个短期运行的本地回调服务器。

  • 确保浏览器可以访问 http://127.0.0.1:<port>/callback。
  • 如果始终未收到回调，请检查本地防火墙、VPN 和代理规则。
  • 在无头环境中，请在 ClawHub Web UI 中创建 API 令牌，然后运行：
bash
clawhub login --token clh_...

whoami 或 publish 返回 Unauthorized (401)

  • 使用 clawhub login 重新登录。
  • 如果使用自定义配置路径，请确认 CLAWHUB_CONFIG_PATH 指向 包含当前令牌的文件。
  • 如果使用 API 令牌，请确认该令牌未在 Web UI 中被撤销。

搜索或安装返回 Rate limit exceeded (429)

请阅读响应中的重试信息：

  • Retry-After：重试前需要等待的秒数。
  • RateLimit-Limit：应用于此请求的限制。
  • RateLimit-Remaining：存在该响应头时，你确切的剩余配额。在 429 上，其值为 0。
  • RateLimit-Reset 或 X-RateLimit-Reset：重置时间。

如果许多用户共享同一个出口 IP，即使每个人只发送少量请求，也可能触及匿名 IP 限制。请尽可能登录，并在报告的延迟时间后重试。

通过代理时搜索或安装失败

CLI 遵循标准代理变量：

bash
export HTTPS_PROXY=http://proxy.example.com:3128clawhub search "my query"

支持的名称包括 HTTPS_PROXY、HTTP_PROXY、https_proxy 和 http_proxy。

某个技能未出现在搜索结果中

  • 如果知道确切的 slug 或所有者页面，请检查它们。
  • 确认该发布版本为公开状态，并且未因扫描或审核而被暂缓。
  • 如果你是该技能的所有者，请登录并检查它：
bash
clawhub inspect @openclaw/demo

仅所有者可见的诊断信息可能会说明扫描、上传门禁或审核状态。

发布因缺少必需的元数据而失败

对于技能，请检查 SKILL.md frontmatter。应声明必需的环境变量和 工具，以便用户和扫描程序了解该软件包。

对于插件，请检查 package.json 兼容性元数据。代码插件发布 需要 OpenClaw 兼容性字段，例如 openclaw.compat.pluginApi 和 openclaw.build.openclawVersion。

请先预览发布负载：

bash
clawhub package publish <source> --family code-plugin --dry-run

发布因 GitHub 所有者或来源错误而失败

ClawHub 使用 GitHub 身份和来源归属将软件包与其 发布者关联起来。

  • 确保使用拥有该软件包或有权发布该软件包的 GitHub 账户登录。
  • 检查源 URL 是否公开或 ClawHub 是否可以访问。
  • 对于 GitHub 来源，请使用 owner/repo、owner/repo@ref 或完整的 GitHub URL。

发布因命名空间已被占用或保留而失败

如果发布因所有者用户名、组织命名空间、软件包作用域、技能 slug 或软件包名称已被占用或保留而失败，请先确认用于发布的 所有者与该命名空间匹配。对于插件软件包， @example-org/example-plugin 之类的限定作用域名称必须由 匹配的 example-org 所有者发布。

如果你认为你的组织、项目或品牌是该命名空间的合法所有者，但 无法管理当前的 ClawHub 所有者，请创建 组织/命名空间认领问题， 并提供公开且不敏感的证明。有关证据指南以及不应在公开问题中 包含的内容，请参阅 组织和命名空间认领。

sync 提示未找到技能

sync 会查找包含 SKILL.md 或 skill.md 的文件夹。

请将其指向要扫描的根目录：

bash
clawhub sync --root /path/to/skills

如果不确定将发布哪些内容，请先预览：

bash
clawhub sync --all --dry-run --no-input

update 因存在本地更改而拒绝执行

本地文件与 ClawHub 已知的任何版本都不匹配。请选择以下一种方式：

  • 保留本地编辑并跳过更新。
  • 使用已发布版本覆盖：
bash
clawhub update @openclaw/demo --force
  • 将编辑后的副本以新的 slug 或分支发布。

在 OpenClaw 中安装插件失败

  • 使用明确的 ClawHub 来源：
bash
openclaw plugins install clawhub:<package>
  • 检查软件包详情页面中的扫描状态和兼容性元数据。
  • 确认你的 OpenClaw 版本满足该软件包声明的 兼容性范围。
  • 如果软件包处于隐藏、暂缓或阻止状态，则在 所有者解决问题之前可能无法安装。

公共 API 请求失败

  • 遵循 429 重试响应头，并缓存公开列表/搜索响应。
  • 将用户链接回规范的 ClawHub 列表页面。
  • 不要在公共 API 范围之外镜像隐藏、私有、暂缓或被审核阻止的内容。

有关端点详情，请参阅 HTTP API。

Was this useful?
On this page

On this page