📋 目录

1. 网关启动失败：进程已运行
2. HTTP 401 invalid_key 错误
3. 插件重复注册警告
4. 配置文件检查清单
5. 完全卸载 OpenClaw

---

问题 1：网关启动失败（进程已运行）

🔴 错误现象

Gateway failed to start: gateway already running (pid 10304)
lock timeout after 5000ms

📌 原因分析

OpenClaw Gateway 采用单实例运行模式，当检测到已有进程在运行时，会阻止新实例启动以避免端口冲突和资源竞争。

✅ 解决方案

方法一：使用官方命令停止

openclaw gateway stop
openclaw gateway

方法二：强制结束进程

# 结束指定 PID
taskkill /F /PID 10304

# 或结束所有 openclaw 进程
taskkill /F /IM openclaw.exe

方法三：清理计划任务

# 如果是计划任务启动的
schtasks /End /TN "OpenClaw Gateway"
schtasks /Delete /TN "OpenClaw Gateway" /F

💡 预防措施

# 启动前先检查状态
openclaw gateway status

# 设置开机自启时避免重复
openclaw gateway install-service

---

问题 2：HTTP 401 invalid_key 错误

🔴 错误现象

界面显示红色错误条：

HTTP 401 invalid_key: *** API 密钥

📌 原因分析

原因	说明
API Key 格式错误	缺少前缀或包含非法字符
地域不匹配	国内 API Key 使用了国际 Base URL
配置文件问题	Token 包含空格或换行符
Key 已失效	API Key 过期或被撤销

✅ 解决方案

步骤一：运行诊断工具

openclaw doctor --fix
openclaw status --all

步骤二：检查配置文件

code C:\Users\你的用户名\.openclaw\openclaw.json

正确的配置格式：

{
  "api": {
    "baseUrl": "https://api.example.com",
    "apiKey": "sk-ant-api03-xxxxxxxxxxxx",
    "provider": "anthropic"
  },
  "model": "claude-3-5-sonnet-20241022"
}

步骤三：重新配置 API Key

openclaw configure
# 按提示输入新的 API Key
openclaw gateway restart

步骤四：清除缓存

Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw\cache\*"

🎯 API Key 格式参考

提供商	Key 格式前缀	获取地址
Anthropic	sk-ant-api03-	console.anthropic.com
阿里云百炼	sk-	dashscope.console.aliyun.com
MiniMax	sk-	platform.minimaxi.com
OpenAI	sk-proj-	platform.openai.com

---

问题 3：插件重复注册警告

🔴 错误现象

Config warnings:
- plugins.entries.feishu: plugin feishu: duplicate plugin id detected
  later plugin may be overridden

📌 原因分析

插件配置文件中同一插件 ID 被定义了多次，后注册的插件会覆盖先前的配置，可能导致功能异常。

✅ 解决方案

步骤一：检查插件配置

code C:\Users\你的用户名\.openclaw\config.json

步骤二：查找重复项
在配置文件中搜索插件名称（如 feishu），检查是否有：

// ❌ 错误示例
"plugins": {
  "entries": {
    "feishu": { ... },
    "feishu": { ... }  // ← 重复！
  }
}

步骤三：清理并设置白名单

// ✅ 正确示例
"plugins": {
  "allow": ["feishu", "other-trusted-plugin"],
  "entries": {
    "feishu": {
      "app_id": "cli_xxxxxxxxxxxx",
      "app_secret": "xxxxxxxxxxxxxxxx"
    }
  }
}

步骤四：清理插件缓存

Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw\extensions\.openclaw-install-stage-*"
openclaw gateway restart

---

问题 4：配置文件检查清单

📋 完整检查项

# 1. 打开配置目录
explorer "$env:USERPROFILE\.openclaw"

# 2. 检查主要配置文件
code "$env:USERPROFILE\.openclaw\openclaw.json"
code "$env:USERPROFILE\.openclaw\config.json"

✅ 配置验证清单

检查项	验证方法	预期结果
JSON 语法	使用 JSON 校验工具	无语法错误
API Key	无空格/换行	trim() 后长度不变
Base URL	与 API Key 地域匹配	国内/国际一致
插件 ID	无重复定义	每个 ID 唯一
文件权限	当前用户可读写	无权限错误
端口占用	netstat -ano | findstr :端口	端口可用

🔧 配置修复脚本

# 一键修复常见配置问题
openclaw doctor --fix
openclaw config validate
openclaw gateway restart

---

问题 5：完全卸载 OpenClaw

🗑️ 完整卸载步骤

步骤一：停止所有服务

openclaw gateway stop
taskkill /F /IM openclaw.exe 2>$null
schtasks /Delete /TN "OpenClaw Gateway" /F 2>$null

步骤二：删除核心文件

Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\openclaw"
Remove-Item -Recurse -Force "C:\Program Files\openclaw"

步骤三：清理环境变量

$oldPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = ($oldPath -split ';' | Where-Object { $_ -notlike "*openclaw*" }) -join ';'
[Environment]::SetEnvironmentVariable("Path", $newPath, "User")
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", $null, "User")

步骤四：验证卸载
注意：需要重启一下电脑！！！

openclaw --version  # 应返回：命令不存在
Test-Path "$env:USERPROFILE\.openclaw"  # 应返回：False

步骤五：找到 openclaw 命令位置并删除

# 查找命令所在路径
where.exe openclaw
# 或在 PowerShell 中查找
Get-Command openclaw | Select-Object -ExpandProperty Source

⚠️ 备份提醒

如需保留配置，卸载前先备份：

Copy-Item -Recurse "$env:USERPROFILE\.openclaw" "D:\backup\openclaw-config"

---

📊 快速故障排查流程图

启动失败？
├─→ 检查进程是否运行 → taskkill 结束进程
├─→ 检查端口是否占用 → netstat 查看端口
└─→ 检查配置文件 → openclaw doctor --fix

API 401 错误？
├─→ 验证 API Key 格式 → 检查前缀和长度
├─→ 检查 Base URL 匹配 → 国内/国际一致
└─→ 清除缓存重启 → Remove-Item cache

插件冲突？
├─→ 检查 config.json → 搜索重复 ID
├─→ 设置 plugins.allow → 明确白名单
└─→ 清理扩展缓存 → 删除 install-stage 目录

---

💡 最佳实践建议

1. 日常维护

# 每周检查一次状态
openclaw status --all

# 定期清理缓存
openclaw cache clean

2. 配置管理

• 使用版本控制管理配置文件
• 修改前先备份 config.json
• 使用 JSON 格式校验工具

3. 日志监控

# 实时查看日志
Get-Content "$env:USERPROFILE\.openclaw\logs\gateway.log" -Tail 50 -Wait

# 导出日志用于分析
Get-Content "$env:USERPROFILE\.openclaw\logs\gateway.log" > openclaw-log.txt

4. 安全建议

• API Key 不要提交到代码仓库
• 定期轮换 API Key
• 使用环境变量存储敏感信息

---

📞 获取帮助

如果以上方法都无法解决问题：

1. 查看官方文档：访问 OpenClaw 官网文档中心
2. 提交 Issue：在 GitHub 仓库提交详细问题描述
3. 社区支持：加入官方 Discord/Slack 社区
4. 提供日志：附上 gateway.log 完整内容

---

📝 总结

问题类型	核心命令	解决时间
网关启动失败	openclaw gateway stop	1 分钟
API 401 错误	openclaw configure	5 分钟
插件冲突	编辑 config.json	3 分钟
配置问题	openclaw doctor --fix	2 分钟
完全卸载	执行卸载脚本	5 分钟

---

🦞 提示：OpenClaw 是一个强大的 AI 网关工具，正确配置后能极大提升开发效率。遇到问题时，先查看日志，再按本文步骤排查，90% 的问题都能快速解决！

---