文档中心

ArkClaw 企业版

故障处理

ArkClaw运行快速排查手册

说明

本手册仅适用于具备ArkClaw消息发送权限及ArkClaw 终端登录权限的人员。

调试信息

在飞书/WebUI等会话中输入：

命令	用途	示例
/help	显示帮助信息。	/help
/commands	列出所有可用命令。	/commands
/status	当前状态：模型、token用量、provider配额。	/status
/whoami	显示发送者ID（别名：/id）。	/whoami
/context	上下文构成明细。	/context list、/context detail、/context json
/usage	控制每轮token/费用显示。	/usage off、/usage tokens、/usage full、/usage cost
/verbose	详细输出模式。	/verbose on

问题快速排查

快速分类

快速定位问题层级：

排查三板斧

遇到任何问题，执行以下命令获取原因：

90%的问题都能从这三条命令的输出中找到答案。

关键命令速查

命令	用途
openclaw status	整体状态概览。
openclaw status --all	完整诊断报告（可安全分享）。
openclaw status --deep	深度探测（含provider检查）。
openclaw gateway status	服务/进程状态。
openclaw gateway restart	重启Gateway。
openclaw doctor	自动诊断。
openclaw doctor --fix	自动修复。
openclaw doctor --repair	激进修复。
openclaw models status	模型认证状态。
openclaw channels status --probe	渠道连接状态。
openclaw logs --follow	实时日志
openclaw security audit	安全审计。

问题快速处理

飞书收不到消息

排查方向：

DM配对：确认已审批用户配对请求。

openclaw pairing list --channel feishu
openclaw pairing approve <requestId>

群组提及：在群聊中需要@机器人才会响应。

检查requireMention设置是否正确。

权限/Scope：查看日志中是出现403错误码或missing_scope关键字段。

飞书没有流式返回

升级飞书插件到最新版。

npx -y @larksuite/openclaw-lark-tools update

开启流式输出。

openclaw config set channels.feishu.streaming true

确认飞书应用已开通cardkit:card:write权限。

飞书其他问题

运行飞书诊断。

# 在终端执行
npx @larksuite/openclaw-lark-tools doctor

手动修复或者在终端执行以下命令自动修复。

更多信息，请参见：OpenClaw飞书官方使用指南。

# 在终端执行
npx @larksuite/openclaw-lark-tools doctor --fix

不回复或报错

常见问题：

错误	修复
HTTP 429 rate limit	降低请求频率，或升级API额度。
HTTP 401/403	API Key过期或无效，重新配置。

说明

建议切换模型，如果是Coding Plan则在页面修改后3-5分钟生效。

命令无反应/执行很慢

问题

用户发送/new、/reset、/status等命令后无反应。

或等待很长时间才有回复。

排查流程

确认Gateway存活。

openclaw gateway status

确认Runtime状态为running。

确认RPC probe为ok。

核查日志中是否有接收到消息的记录。

# 开启日志，让客户发一条消息
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

定位问题所处环节。

环节	判断方式	修复
消息未到Gateway	日志无任何输出。	重启Gateway。
命令未识别	日志收到消息但无命令处理。	检查commands.text / commands.native。
会话操作卡住	日志显示处理开始但无API调用。	检查会话文件大小，考虑清理。
模型API超时	日志显示API请求已发出。	检查provider状态、网络、API key。
响应生成慢	API返回了但streaming慢。	模型本身慢（Opus等大模型正常）。

常见根因与修复方案。

根因A：Startup prompt过重。

/new会触发startup prompt（如果有BOOTSTRAP.md）。

若system prompt过大，且叠加多个project context文件，会导致首次响应缓慢。

修复方案：精简BOOTSTRAP.md内容，减少不必要的启动检查逻辑。

根因B：会话文件过大。

ls -lhS ~/.openclaw/agents/*/sessions/*.jsonl | head -10
du -sh ~/.openclaw/agents/*/sessions/

判定标准：单个JSONL > 50MB。

修复方案：

手动压缩超大会话文件或重置会话。

重启网关。

openclaw gateway restart

模型认证/API错误

问题

"429 You have exceeded the weekly usage quota. It will reset at 2026-03-23 00:00:00 +0800 CST. We recommend upgrading your plan for more quota, or waiting for the reset"

"401 The API key doesn't exist. "

常见原因与修复

原因A：Coding Plan额度已用完。

原因B：API Key错误。

检查API Key是否正确。

原因C：模型未开通。

前往火山方舟控制台开通管理页开通模型。

消息未触发/收不到回复

问题

发消息给bot没有任何响应。

群聊中@bot没响应。

某些人能触发，某些人不能。

排查流程

常见原因与修复

原因	检查方式	修复
发送者不在白名单。	openclaw status查看AllowFrom。	添加到channels.<provider>.allowFrom。
群聊需要@提及。	检查requireMention设置。	设置requireMention: false 或确保正确@。
dmPolicy设置问题。	检查dmPolicy。	设置为open或allowlist。
群聊未在白名单。	检查groups或guilds配置。	添加群ID到配置。
Telegram bot未收到消息。	检查bot token和webhook。	确认bot token正确。
配对模式等待审批。	openclaw pairing list <channel>	审批或调整dmPolicy。

前往社群

如果您在阅读文档后，仍希望进一步了解 ArkClaw 企业版的使用方法、实践案例或解决思路，欢迎加入ArkClaw 企业版官方交流群。期待与您加入群内交流，一起共享经验、碰撞思路，在互助中收获更多启发。

最近更新时间：2026.04.27 12:01:00

这个页面对您有帮助吗？

有用

无用