🚨 故障排查指南

# 方案 1: 释放被占用的端口
# 找到占用进程的 PID
PID=$(lsof -t -i:8080)
# 终止该进程
kill -9 $PID

# 方案 2: 修改 OpenClaw 配置使用其他端口
# 编辑配置文件
nano ~/.openclaw/config.yaml
# 修改 port 配置项
port: 8081

# 方案 3: 重启 OpenClaw 服务
systemctl stop openclaw
systemctl start openclaw
systemctl status openclaw

# 方案 4: 检查防火墙规则
ufw allow 8080/tcp
# 或
firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload

# 方案 1: 重新设置 API Key
# 登录 https://console.anthropic.com 获取新的 API Key
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 永久添加到 shell 配置文件
echo 'export ANTHROPIC_API_KEY="sk-ant-..." >> ~/.bashrc
source ~/.bashrc

# 方案 2: 使用 claude login 重新认证
claude logout
claude login
# 按提示完成 OAuth 认证流程

# 方案 3: 重置 Claude Code 配置
rm -rf ~/.claude
rm -rf ~/.config/claude-code
claude

# 方案 4: 配置网络代理（如需要）
export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

# 方案 5: 检查账户状态
# 登录 Anthropic Console 查看额度和订阅状态
# 如额度不足，升级套餐或等待下月重置

# 1. 检查数据库服务状态
# PostgreSQL 示例
systemctl status postgresql
# MySQL 示例
systemctl status mysql

# 2. 重启数据库服务
systemctl restart postgresql

# 3. 验证连接配置
# 检查应用配置文件中的数据库连接字符串
cat ~/.openclaw/config.yaml | grep -A 5 database

# 4. 测试数据库连接
psql -h localhost -U openclaw -d openclaw_db
# 或
mysql -h localhost -u openclaw -p openclaw_db

# 5. 检查磁盘空间
df -h
# 如磁盘满，清理空间
journalctl --vacuum-time=7d
docker system prune -af

# 6. 检查连接数
# PostgreSQL
psql -c "SELECT count(*) FROM pg_stat_activity;"
# 如接近 max_connections，需增加限制或优化连接池

# 方案 1: 取消并重新提交任务
# 取消当前卡住的任务
curl -X POST https://api.openclaw-cocode.system/v2/agents/activations/{activationId}/cancel \
  -H "Authorization: Bearer ..."

# 将大任务拆分为多个小任务重新提交
# 例如：将"生成完整 PRD"拆分为"生成用户故事"、"生成功能清单"等

# 方案 2: 调整 Agent 配置
# 编辑 Agent 配置文件，增加超时时间
nano ~/.openclaw/agents/{agentType}.yaml
# timeout: 3600  # 从 1800 秒增加到 3600 秒
# max_iterations: 50  # 增加最大迭代次数

# 方案 3: 切换 AI 模型
# 使用更快但可能质量略低的模型
# model: claude-haiku-4  # 替代 claude-sonnet-4

# 方案 4: 释放系统资源
# 终止不必要的进程
kill $(pgrep -f "non-essential-process")

# 清理 Docker 容器
docker prune

# 方案 5: 启用断点续传
# 对于支持的任务类型，启用中间结果保存
# 这样即使超时也可以从断点继续

# 方案 1: 优化输入需求
# 提供更详细、结构化的输入
# 包含：背景、目标用户、核心功能、约束条件、示例参考

# 方案 2: 调整 Prompt 模板
# 编辑 Agent 的 System Prompt
nano ~/.openclaw/agents/prompts/{agentType}_system.txt

# 添加明确的输出格式要求
# 例如："请严格按照以下 Markdown 结构生成 PRD 文档：..."

# 方案 3: 降低 temperature 参数
# 在 Agent 配置中降低随机性
# temperature: 0.3  # 从 0.7 降低到 0.3，输出更稳定

# 方案 4: 提供 Few-Shot 示例
# 在 Prompt 中加入高质量示例
# "以下是优秀的 PRD 示例：[示例内容]"

# 方案 5: 启用人工审核节点
# 在关键节点暂停，等待人工确认后再继续
# config:
#   human_in_the_loop: true
#   review_points: ["prd_complete", "architecture_approved"]

# 方案 6: 切换更强的 AI 模型
# model: claude-opus-4  # 用于复杂任务
# model: claude-sonnet-4  # 用于常规任务

# 1. 检查消息队列状态
rabbitmqctl list_queues name messages_ready consumers

# 2. 查看未消费的消息
rabbitmqadmin get queue=agent_outputs count=5

# 3. 验证输出格式
# 检查上游 Agent 的输出是否符合下游期望的 Schema
curl -X GET https://api.openclaw-cocode.system/v2/agents/activations/{activationId}/result \
  | jq '.output'

# 4. 手动触发下游 Agent
# 使用上游输出作为输入，手动激活下游
curl -X POST https://api.openclaw-cocode.system/v2/agents/architecture/activate \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prdDocument": "...",  # 复制上游输出
      "projectId": "prj_xxx"
    }
  }'

# 5. 修复 Schema 不匹配
# 更新 Agent 配置文件中的输入输出 Schema 定义
nano ~/.openclaw/agents/{agentType}/schema.yaml

# 6. 重启消息队列消费者
systemctl restart openclaw-agent-consumer

# 1. 检查 Token 是否有效
# Token 可能已过期（默认有效期 1 小时）
curl -X POST https://api.openclaw-cocode.system/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'

# 2. 验证 Authorization 头格式
# 正确格式：Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
# 常见错误：
# - 缺少 "Bearer " 前缀
# - Bearer 和 Token 之间缺少空格
# - Token 被截断或包含多余字符

# 3. 检查 Token 权限范围（scope）
# 某些 API 需要特定 scope，如 admin、write 等
# 在获取 Token 时请求所需 scope
curl -X POST https://api.openclaw-cocode.system/v2/auth/token \
  -d '{"grant_type": "client_credentials", "scope": "read write admin"}'

# 4. 清除本地缓存的旧 Token
rm ~/.openclaw/token_cache.json
# 重新认证获取新 Token

# 1. 检查限流响应头
# API 响应中会包含限流相关信息
X-RateLimit-Limit: 300        # 每分钟上限
X-RateLimit-Remaining: 0      # 剩余请求数
X-RateLimit-Reset: 1710411600 # 重置时间戳
Retry-After: 45               # 建议重试时间（秒）

# 2. 实现指数退避重试
# 在代码中添加智能重试逻辑
import time
import random

def api_request_with_retry(url, max_retries=5):
    for i in range(max_retries):
        response = requests.get(url)
        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            jitter = random.uniform(0, 10)
            wait_time = retry_after + jitter
            print(f"Rate limited. Waiting {wait_time:.1f}s...")
            time.sleep(wait_time)
        else:
            return response
    raise Exception("Max retries exceeded")

# 3. 降低请求频率
# 使用批量 API 减少请求次数
# 例如：批量创建任务而非逐个创建

# 4. 升级到更高配额套餐
# Free: 60 请求/分钟
# Pro: 300 请求/分钟
# Enterprise: 1000 请求/分钟

# 5. 使用 Webhooks 替代轮询
# 订阅事件通知，避免频繁查询状态

# 1. 记录 requestId 用于追踪
# 500 错误响应中会包含 requestId
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "...",
    "requestId": "req_abc123xyz"  # 重要！
  }
}

# 2. 查看服务器日志
# 根据 requestId 搜索相关日志
grep "req_abc123xyz" /var/log/openclaw/api.log

# 3. 检查依赖服务状态
systemctl status postgresql
systemctl status redis
systemctl status rabbitmq
kubectl get pods -n openclaw

# 4. 检查磁盘空间和内存
df -h
free -h

# 5. 重启 API 服务
systemctl restart openclaw-api

# 6. 回滚到上一个稳定版本
# 如是新版本引入的 bug
git checkout previous-stable-tag
./deploy.sh

# 7. 联系技术支持
# 发送 requestId 和错误详情到 support@openclaw-cocode.system

# 常见失败原因及解决方法：

# 1. 代码编译错误
# 查看具体编译错误信息
# 修复代码后重新触发构建
git commit -m "fix: 修复编译错误"
git push

# 2. 单元测试失败
# 查看测试报告
# 访问 Jenkins 构建页面的 Test Result
# 修复失败的测试用例

# 3. 依赖下载失败
# 检查网络连接
# 配置国内镜像源
# Maven: 配置阿里云镜像
# npm: npm config set registry https://registry.npmmirror.com

# 4. Docker 构建失败
# 检查 Dockerfile 语法
# 验证基础镜像是否存在
# 检查磁盘空间
docker system df
docker system prune -af

# 5. 资源不足
# 增加 Jenkins Executor 数量
# 清理 workspace 释放空间
# 考虑使用 Kubernetes 动态 Agent

# 6. 凭证问题
# 检查 Jenkins Credentials 是否过期
# 验证 Git、Docker Registry、K8S 等凭证

# 7. 重新运行失败的 Stage
# Jenkins 支持从失败的 Stage 继续
# 点击 "Replay" 或 "Restart from Stage"

# 场景 1: ImagePullBackOff - 镜像拉取失败
# 检查镜像名称和标签是否正确
# 验证 Docker Registry 凭证
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass \
  -n {namespace}

# 在 Deployment 中引用 imagePullSecrets
# imagePullSecrets:
#   - name: regcred

# 场景 2: CrashLoopBackOff - 应用启动后崩溃
# 查看应用日志定位错误
kubectl logs {pod-name} --previous
# 常见原因：
# - 配置文件缺失或错误
# - 数据库连接失败
# - 端口冲突
# - 缺少必需的环境变量

# 场景 3: OOMKilled - 内存超限
# 增加内存限制
# resources:
#   limits:
#     memory: "1Gi"  # 从 512Mi 增加到 1Gi
#   requests:
#     memory: "512Mi"

# 场景 4: Liveness Probe 失败
# 调整探针参数
# livenessProbe:
#   initialDelaySeconds: 60  # 增加启动宽限期
#   periodSeconds: 30        # 降低检查频率
#   failureThreshold: 5      # 增加失败容忍次数

# 场景 5: 滚动更新卡住
# 查看卡住的 Pod
kubectl rollout status deployment/{name} -n {namespace}
# 回滚到上一版本
kubectl rollout undo deployment/{name} -n {namespace}
# 或回滚到特定版本
kubectl rollout undo deployment/{name} -n {namespace} --to-revision=2

# 场景 6: 资源不足
# 检查集群资源
kubectl top nodes
kubectl top pods
# 扩容集群或优化资源请求

# 1. 查看容器日志
docker logs {container-id}
docker logs --tail 100 {container-id}

# 2. 检查容器状态
docker ps -a | grep {container-name}

# 3. 以交互模式调试
docker run -it --entrypoint /bin/sh {image-name}
# 在容器内手动启动应用排查问题

# 4. 检查端口占用
docker run -p 8080:8080 ...
# 如端口被占用，更换宿主机端口
docker run -p 8081:8080 ...

# 5. 验证挂载卷
docker run -v /host/path:/container/path ...
# 确保宿主机路径存在且有正确权限
ls -la /host/path
chmod 755 /host/path

# 6. 检查环境变量
docker run -e ENV_VAR=value ...
# 验证所有必需的环境变量已设置

# 7. 资源限制
docker run --memory="512m" --cpus="1.0" ...
# 如资源不足，增加限制或优化应用

# 1. 检查 KubeSphere 组件状态
kubectl get pods -n kubesphere-system
kubectl get pods -n kubesphere-controls-system
kubectl get pods -n kubesphere-monitoring-system

# 2. 查看 ks-apiserver 日志
kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-apiserver -o jsonpath='{.items[0].metadata.name}')

# 3. 检查 Ingress 配置
kubectl get ingress -n kubesphere-system
kubectl describe ingress ks-console -n kubesphere-system

# 4. 验证 NodePort 服务
kubectl get svc -n kubesphere-system ks-console
# 通过 NodeIP:NodePort 访问

# 5. 重置 admin 密码
kubectl exec -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-account -o jsonpath='{.items[0].metadata.name}') -- /opt/kubesphere/reset_admin_password.sh

# 6. 检查证书
# 如使用 HTTPS，验证证书是否过期
openssl x509 -in /path/to/cert.pem -text -noout | grep "Not After"

# 7. 重启 KubeSphere
kubectl rollout restart deployment -n kubesphere-system

# 1. 优化数据库查询
# 添加缺失的索引
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_tasks_status ON tasks(status);

# 分析并优化慢查询
EXPLAIN ANALYZE SELECT * FROM tasks WHERE status = 'open';

# 2. 增加缓存
# 启用 Redis 缓存
# 配置缓存策略
# cache:
#   enabled: true
#   ttl: 3600
#   prefix: "openclaw:"

# 3. 水平扩展
# 增加 API 服务实例
kubectl scale deployment openclaw-api --replicas=5

# 4. 优化 JVM/Node.js 参数
# Java: -Xms2g -Xmx4g -XX:+UseG1GC
# Node: --max-old-space-size=4096

# 5. 清理历史数据
# 归档旧的构建记录、日志等
DELETE FROM builds WHERE created_at < NOW() - INTERVAL '90 days';

# 6. 启用 CDN
# 静态资源走 CDN 加速

# 7. 数据库读写分离
# 配置主从复制，读操作走从库

# 1. 查找大文件和目录
du -ah / | sort -rh | head -20
ncdu /  # 交互式查看

# 2. 清理 Docker 资源
docker system prune -af  # 清理所有未使用的资源
docker builder prune -af  # 清理构建缓存

# 3. 清理日志
# 截断日志文件
> /var/log/openclaw/error.log
> /var/log/syslog

# 配置日志轮转
nano /etc/logrotate.d/openclaw

# 4. 清理旧版本
# 删除旧的 Docker 镜像
docker images | grep "" | awk '{print $3}' | xargs docker rmi

# 删除旧的 K8S 资源
kubectl delete pods --field-selector=status.phase==Succeeded -A

# 5. 清理临时文件
rm -rf /tmp/*
rm -rf ~/.cache/*

# 6. 扩容磁盘
# 云环境：在线扩容
# 物理机：添加新磁盘或替换大容量磁盘

# 7. 配置监控告警
# 当磁盘使用率超过 80% 时告警

# 1. 立即停止写入操作
# 防止数据被覆盖

# 2. 从备份恢复
# 检查最近的备份
ls -lt /backups/postgresql/

# 恢复数据库
pg_restore -U openclaw -d openclaw_db /backups/postgresql/latest.dump

# 3. 使用 WAL 日志恢复（PostgreSQL）
# 恢复到特定时间点
recovery_target_time = '2026-03-14 10:00:00'

# 4. 从 Git 恢复配置和代码
git log --oneline
git checkout 

# 5. 从对象存储恢复文件
aws s3 cp s3://backup-bucket/path/to/file /local/path/

# 6. 验证恢复结果
# 检查数据完整性
# 运行应用测试

# 预防措施：
# - 配置自动备份（每日全量 + 实时增量）
# - 定期演练恢复流程
# - 多地备份（本地 + 云端）
# - 启用数据库 PITR（时间点恢复）