OpenClaw 故障排除手册:常见问题快速解决
使用 OpenClaw 时遇到问题?本手册汇总了最常见的问题和解决方案,帮助你快速诊断和修复问题。从安装问题到运行时错误,覆盖全方位故障排除。
一、快速诊断流程
1.1 诊断命令
快速状态检查
openclaw status
详细报告
openclaw status --all
深度检查
openclaw status --deep
运行医生
openclaw doctor
1.2 诊断流程图
遇到问题
↓
openclaw status
↓
Gateway 运行?
├─ 否 → openclaw gateway start
└─ 是 → 继续
↓
通道连接?
├─ 否 → 重新认证通道
└─ 是 → 继续
↓
模型可用?
├─ 否 → 检查 API Key
└─ 是 → 查看日志
二、安装问题
2.1 Node.js 版本过低
错误信息:
Error: Node.js version 22 or higher is required
解决方案:
使用 nvm 安装
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh bash
nvm install 22
nvm use 22
2.2 权限错误
错误信息:
Error: EACCES: permission denied
解决方案:
修复 npm 权限
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
2.3 安装卡住
解决方案:
使用 verbose 模式
curl -fsSL https://openclaw.ai/install.sh
bash -s -- --verbose
清理后重试
rm -rf ~/.openclaw
curl -fsSL https://openclaw.ai/install.sh bash
三、Gateway 问题
3.1 Gateway 无法启动
诊断:
openclaw gateway status
openclaw logs --follow
常见原因:
原因 解决方案 端口占用
修改配置使用其他端口
配置错误
openclaw doctor --fix
认证失败
检查 API Key
3.2 端口被占用
错误信息:
Error: Port 18789 is already in use
解决方案:
查找占用进程
lsof -i :18789
杀死进程
kill -9
或修改配置
# ~/.openclaw/openclaw.json
{ gateway: { port: 18790 } }
3.3 认证失败
错误信息:
unauthorized: gateway token mismatch
解决方案:
生成新 token
openclaw doctor --generate-gateway-token
更新配置
# ~/.openclaw/openclaw.json
{
gateway: {
auth: { token: "new-token" }
}
}
重启
openclaw gateway restart
四、通道问题
4.1 WhatsApp 断开
症状:
无法接收/发送消息
解决方案:
重新扫码
rm -rf ~/.openclaw/credentials/whatsapp/
openclaw channels login whatsapp
4.2 Telegram 无响应
症状:
Bot 不回复消息
检查清单:
- [ ] Bot Token 是否正确
- [ ] 用户是否在 allowFrom 中
- [ ] Bot 隐私模式是否关闭
解决方案:
在 Telegram 中
@BotFather → /setprivacy → 选择 Bot → Disable
4.3 Discord 离线
症状:
Bot 显示离线
解决方案:
1. 检查 Bot Token
2. 重新邀请 Bot 到服务器
3. 检查服务器权限
五、模型问题
5.1 认证失败
错误信息:
No credentials found for profile "anthropic:default"
解决方案:
重新认证
openclaw models auth paste-token --provider anthropic
5.2 速率限制
错误信息:
HTTP 429: rate_limit_error
解决方案:
1. 等待配额重置
2. 升级订阅
3. 配置故障转移
{
models: {
defaults: {
primary: "anthropic/claude-sonnet-4-5-20260514",
fallbacks: ["openai/gpt-4o"]
}
}
}
5.3 模型不可用
错误信息:
Unknown model: xxx
解决方案:
查看可用模型
openclaw models list
设置有效模型
openclaw models set-default anthropic/claude-sonnet-4-5-20260514
六、会话问题
6.1 上下文丢失
症状:
AI 不记得之前的对话
原因:
- 会话已重置
- 历史限制太小
解决方案:
{
channels: {
telegram: {
dmHistoryLimit: 50 // 增加历史限制
}
}
}
6.2 上下文过大
错误信息:
Context too large
解决方案:
开始新会话
/new
或减少历史限制
七、性能问题
7.1 响应慢
可能原因:
原因 解决方案 网络延迟
使用更近的服务器
模型负载
切换到更快的模型
资源不足
升级服务器配置
7.2 内存不足
症状:
Gateway 崩溃
解决方案:
增加 Swap
fallocate -l 2G /swapfile
mkswap /swapfile
swapon /swapfile
或减少历史限制
八、日志分析
8.1 查看日志
实时查看
openclaw logs --follow
查看错误
openclaw logs --level error
查看特定时间
grep "2026-03-23" /tmp/openclaw/openclaw-.log
8.2 常见错误模式
错误模式
含义
解决方案
connection refused
服务未运行 | 启动服务 |
| timeout
| 网络问题 | 检查网络 |
| unauthorized
| 认证失败 | 检查 Token |
九、获取帮助
9.1 官方资源
- [文档](https://docs.openclaw.ai)
- [GitHub](https://github.com/openclaw/openclaw)
- [Discord](https://discord.com/invite/clawd)
9.2 提交问题
提供以下信息:
1. OpenClaw 版本
2. 操作系统
3. 错误日志
4. 复现步骤
十、总结
故障排除检查清单:
- [ ] 运行
openclaw status
- [ ] 检查 Gateway 状态
- [ ] 检查通道连接
- [ ] 检查模型认证
- [ ] 查看日志
- [ ] 运行
openclaw doctor
关键要点:
- 从简单诊断开始
- 查看日志找线索
- 定期运行医生检查
- 社区是宝贵资源
下一篇预告:《OpenClaw 高级配置与最佳实践:从入门到精通》
/* 基础样式 */
.article-container {
max-width: 100%;
margin: 0 auto;
padding: 15px;
font-family: -apple-system, BlinkMacSystemFont, “Segoe UI”, “PingFang SC”, “Hiragino Sans GB”, “Microsoft YaHei”, sans-serif;
line-height: 1.8;
color: #333;
background: #fff;
}
/* 文章头部 */
.article-header {
border-bottom: 3px solid #4a90e2;
padding-bottom: 20px;
margin-bottom: 25px;
}
.main-title {
font-size: 1.8em;
color: #1a1a1a;
margin-bottom: 12px;
font-weight: 700;
line-height: 1.3;
}
.article-meta {
display: flex;
gap: 12px;
flex-wrap: wrap;
align-items: center;
}
.category-badge {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: #fff;
padding: 4px 12px;
border-radius: 16px;
font-size: 0.85em;
font-weight: 500;
}
.read-time {
color: #666;
font-size: 0.85em;
}
/* 导读框 */
.intro-box {
background: linear-gradient(135deg, #f0f4ff 0%, #e8f0fe 100%);
border-left: 4px solid #4a90e2;
padding: 18px;
margin: 20px 0;
border-radius: 0 8px 8px 0;
display: flex;
gap: 12px;
align-items: flex-start;
}
.intro-icon {
font-size: 1.8em;
flex-shrink: 0;
}
.intro-text {
margin: 0;
color: #444;
font-size: 1em;
line-height: 1.6;
}
/* 目录 */
.toc-container {
background: #f8f9fa;
border: 1px solid #e9ecef;
border-radius: 8px;
padding: 15px;
margin: 25px 0;
}
.toc-title {
font-size: 1.2em;
color: #333;
margin-bottom: 12px;
font-weight: 600;
}
.toc-list {
list-style: none;
padding: 0;
margin: 0;
}
.toc-list li {
margin: 6px 0;
}
.toc-list a {
color: #4a90e2;
text-decoration: none;
display: block;
padding: 6px 10px;
border-radius: 4px;
font-size: 0.95em;
transition: all 0.2s;
}
.toc-list a:hover {
background: #4a90e2;
color: #fff;
}
/* 文章内容 */
.article-content {
font-size: 1em;
}
.article-title {
font-size: 1.6em;
color: #1a1a1a;
margin: 35px 0 18px;
padding-bottom: 8px;
border-bottom: 2px solid #4a90e2;
}
.section-title {
font-size: 1.4em;
color: #2c3e50;
margin: 30px 0 12px;
padding-left: 12px;
border-left: 4px solid #4a90e2;
}
.subsection-title {
font-size: 1.2em;
color: #34495e;
margin: 22px 0 10px;
}
.subsubsection-title {
font-size: 1.05em;
color: #666;
margin: 18px 0 8px;
}
/* 代码块 – 支持横向滚动 */
.code-wrapper {
margin: 18px 0;
border-radius: 6px;
overflow: hidden;
}
.code-block {
background: #1e1e1e;
padding: 15px;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
margin: 0;
border-radius: 6px;
}
.code-block code {
color: #d4d4d4;
font-family: “Fira Code”, “Consolas”, “Monaco”, monospace;
font-size: 0.85em;
line-height: 1.6;
white-space: pre;
}
.inline-code {
background: #f5f5f5;
color: #e83e8c;
padding: 2px 6px;
border-radius: 3px;
font-family: “Fira Code”, “Consolas”, monospace;
font-size: 0.9em;
}
/* 表格 – 响应式滚动 */
.table-wrapper {
margin: 20px 0;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
border-radius: 8px;
box-shadow: 0 2px 8px rgba(0,0,0,0.08);
}
.styled-table {
width: 100%;
border-collapse: collapse;
min-width: 600px;
font-size: 0.9em;
}
.styled-table thead {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: #fff;
}
.styled-table th {
padding: 12px 15px;
text-align: left;
font-weight: 600;
white-space: nowrap;
}
.styled-table td {
padding: 12px 15px;
border-bottom: 1px solid #e1e4e8;
vertical-align: top;
}
.styled-table tbody tr {
transition: background 0.2s;
}
.styled-table tbody tr:hover {
background: #f8f9fa;
}
.styled-table tbody tr:nth-child(even) {
background: #fafbfc;
}
.styled-table tbody tr:nth-child(odd) {
background: #fff;
}
/* 列表 */
.styled-list {
list-style: none;
padding: 0;
margin: 15px 0;
}
.list-item {
padding: 6px 0 6px 22px;
position: relative;
color: #333;
}
.list-item::before {
content: “•”;
position: absolute;
left: 0;
color: #4a90e2;
font-weight: bold;
font-size: 1.2em;
}
.checkbox-item {
padding: 6px 0 6px 32px;
position: relative;
color: #333;
}
.checkbox-item.checked {
color: #28a745;
}
/* 信息框 */
.info-box {
background: #e8f4fd;
border-left: 4px solid #4a90e2;
padding: 15px;
margin: 18px 0;
border-radius: 0 6px 6px 0;
color: #2c3e50;
}
/* 分隔线 */
.section-divider {
border: none;
height: 2px;
background: linear-gradient(to right, transparent, #4a90e2, transparent);
margin: 35px 0;
}
/* 文章尾部 */
.article-footer {
margin-top: 40px;
padding-top: 25px;
border-top: 2px solid #e9ecef;
}
.tags-section {
margin-bottom: 20px;
}
.tag-label {
font-weight: 600;
color: #666;
margin-right: 8px;
}
.tag {
display: inline-block;
background: #f0f4ff;
color: #4a90e2;
padding: 4px 10px;
border-radius: 12px;
margin: 3px;
font-size: 0.85em;
text-decoration: none;
transition: all 0.2s;
}
.tag:hover {
background: #4a90e2;
color: #fff;
}
.back-to-top {
text-align: center;
padding: 15px;
background: #f8f9fa;
border-radius: 6px;
}
.back-to-top a {
color: #4a90e2;
text-decoration: none;
font-weight: 500;
}
/* 移动端优化 */
@media (max-width: 768px) {
.article-container {
padding: 12px;
}
.main-title {
font-size: 1.4em;
}
.article-title {
font-size: 1.3em;
}
.section-title {
font-size: 1.2em;
}
.code-block {
padding: 12px;
font-size: 0.8em;
}
.styled-table {
font-size: 0.85em;
min-width: 500px;
}
.styled-table th,
.styled-table td {
padding: 10px 12px;
}
.intro-box {
padding: 15px;
}
.intro-icon {
font-size: 1.5em;
}
}
@media (max-width: 480px) {
.main-title {
font-size: 1.3em;
}
.article-meta {
flex-direction: column;
gap: 8px;
}
.category-badge,
.read-time {
font-size: 0.8em;
}
.code-block {
font-size: 0.75em;
padding: 10px;
}
.styled-table {
min-width: 450px;
font-size: 0.8em;
}
.styled-table th,
.styled-table td {
padding: 8px 10px;
}
}
// 移动端表格提示
document.addEventListener(‘DOMContentLoaded’, function() {
var tables = document.querySelectorAll(‘.table-wrapper’);
tables.forEach(function(table) {
if (!table.querySelector(‘.scroll-hint’)) {
var hint = document.createElement(‘div’);
hint.className = ‘scroll-hint’;
hint.innerHTML = ‘👈 左右滑动查看更多’;
hint.style.cssText = ‘text-align:center;padding:8px;background:#f8f9fa;color:#666;font-size:12px;border-radius:0 0 8px 8px;’;
table.parentNode.insertBefore(hint, table.nextSibling);
}
});
});
赞 (0)