# OpenClaw 安装问题排查指南

> 针对中国大陆地区网络问题的完整解决方案

---

## 问题1：Git SSH 权限拒绝

**错误信息**：
```
npm error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
npm error git@github.com: Permission denied (publickey).
```

**原因**：某些 npm 包依赖 GitHub 仓库，使用 SSH 协议，但没有配置 SSH key

**解决方案**：
```powershell
# 配置 Git 使用 HTTPS 而不是 SSH
git config --global url."https://github.com/".insteadOf ssh://git@github.com/
git config --global url."https://github.com/".insteadOf git@github.com:
```

---

## 问题2：GitHub 连接超时

**错误信息**：
```
npm error fatal: unable to access 'https://github.com/...': 
Failed to connect to github.com port 443 after 21152 ms: Could not connect to server
```

**原因**：中国大陆访问 GitHub 不稳定

### 解决方案A：使用 GitHub 镜像（推荐）⭐⭐⭐

```powershell
# 使用 ghproxy 加速
git config --global url."https://ghproxy.com/https://github.com/".insteadOf https://github.com/

# 或者使用 fastgit
git config --global url."https://hub.fastgit.xyz/".insteadOf https://github.com/

# 然后安装
npm install -g openclaw@latest
```

### 解决方案B：配置代理（如果有）

```powershell
# 假设代理端口是 7890（根据实际代理软件修改）
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 然后安装
npm install -g openclaw@latest
```

### 解决方案C：修改 hosts 文件

```powershell
# 以管理员身份运行 PowerShell，添加 GitHub IP
Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "`n140.82.113.4 github.com"
Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "199.232.69.194 github.global.ssl.fastly.net"
Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "185.199.108.133 raw.githubusercontent.com"

# 刷新 DNS
ipconfig /flushdns

# 然后安装
npm install -g openclaw@latest
```

---

## 完整安装流程（推荐）

```powershell
# 步骤1：配置 Git 使用 HTTPS
git config --global url."https://github.com/".insteadOf ssh://git@github.com/
git config --global url."https://github.com/".insteadOf git@github.com:

# 步骤2：配置 GitHub 镜像加速
git config --global url."https://ghproxy.com/https://github.com/".insteadOf https://github.com/

# 步骤3：安装 OpenClaw
npm install -g openclaw@latest

# 步骤4：验证安装
openclaw --version
```

---

## 清理代理配置（如果之前配置过）

```powershell
# 清理 npm 代理
npm config delete proxy
npm config delete https-proxy

# 清理 git 代理
git config --global --unset http.proxy
git config --global --unset https.proxy
```

---

## 常见问题

### Q: 安装卡住不动？
A: 按 Ctrl+C 取消，然后重试。网络波动很常见。

### Q: 仍然失败？
A: 尝试使用 VPN 或加速器，然后重新安装。

### Q: 如何查看配置？
A: 
```powershell
# 查看 git 配置
git config --global --list

# 查看 npm 配置
npm config list
```

---

## 官方资源

- 官方文档: https://docs.openclaw.ai
- GitHub: https://github.com/openclaw/openclaw
- Discord: https://discord.gg/clawd

---

_创建时间：2026-03-11_