【Bug已解决】openclaw: "command not found" / openclaw not installed — OpenClaw CLI 安装失败解决方案

1. 问题描述

安装 OpenClaw 后无法找到命令或运行失败：

# 命令未找到
$ openclaw
zsh: command not found: openclaw

# 或 pip 安装失败
$ pip install openclaw
Error: Could not find a version that satisfies the requirement openclaw

# 或安装后无法运行
$ openclaw --version
Error: ModuleNotFoundError: No module named 'openclaw'

# 或路径问题
$ which openclaw
# 无输出

这个问题在以下场景中特别常见：

• pip 安装路径不在 PATH
• Python 版本不兼容
• 虚拟环境未激活
• 权限不足
• 包名拼写错误
• 依赖缺失

2. 原因分析

原因分类表

原因分类	具体表现	占比
PATH 问题	找不到命令	约 35%
Python 版本	< 3.8	约 20%
虚拟环境	未激活	约 15%
包名错误	openclaw vs open-claw	约 15%
依赖缺失	import 失败	约 10%
权限不足	EACCES	约 5%

3. 解决方案

方案一：修复 PATH（最推荐）

# 步骤 1：找到 pip 安装路径
pip show openclaw | grep Location
# 或
python3 -c "import openclaw; print(openclaw.__file__)"

# 步骤 2：添加到 PATH
export PATH=$(python3 -m site --user-base)/bin:$PATH

# 步骤 3：永久设置
echo 'export PATH=$(python3 -m site --user-base)/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 步骤 4：验证
which openclaw
openclaw --version

方案二：使用虚拟环境

# 步骤 1：创建虚拟环境
python3 -m venv ~/.openclaw-env

# 步骤 2：激活虚拟环境
source ~/.openclaw-env/bin/activate

# 步骤 3：安装
pip install openclaw

# 步骤 4：验证
which openclaw
openclaw --version

方案三：检查 Python 版本

# 步骤 1：检查版本
python3 --version  # 需要 3.8+

# 步骤 2：如果版本低，更新
# 使用 pyenv
curl https://pyenv.run | bash
pyenv install 3.12
pyenv global 3.12

# 步骤 3：或使用 Homebrew（macOS）
brew install python@3.12

# 步骤 4：重新安装
pip install openclaw
openclaw --version

方案四：检查包名

# 步骤 1：搜索正确包名
pip search openclaw
# 或
pip install openclaw  # 如果失败，尝试:
pip install open-claw
pip install OpenClaw

# 步骤 2：从 GitHub 安装
pip install git+https://github.com/anthropics/openclaw.git

# 步骤 3：或从源码安装
git clone https://github.com/anthropics/openclaw.git
cd openclaw
pip install -e .

# 步骤 4：验证
openclaw --version

方案五：安装依赖

# 步骤 1：检查缺失的依赖
python3 -c "import openclaw" 2>&1

# 步骤 2：安装依赖
pip install -r requirements.txt

# 步骤 3：或安装特定依赖
pip install anthropic httpx pydantic

# 步骤 4：验证
python3 -c "import openclaw; print('OK')"
openclaw --version

方案六：使用 pipx

# 步骤 1：安装 pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# 步骤 2：使用 pipx 安装
pipx install openclaw

# 步骤 3：验证
which openclaw
openclaw --version

# 步骤 4：如果需要全局
pipx ensurepath
source ~/.bashrc

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：PATH	找不到	⭐⭐⭐⭐⭐	低
方案二：虚拟环境	隔离	⭐⭐⭐⭐⭐	低
方案三：Python 版本	版本低	⭐⭐⭐⭐⭐	低
方案四：包名	名称	⭐⭐⭐⭐	低
方案五：依赖	import 失败	⭐⭐⭐⭐⭐	低
方案六：pipx	全局	⭐⭐⭐⭐⭐	低

5. 常见问题 FAQ

5.1 如何检查 OpenClaw 是否安装

which openclaw
openclaw --version

5.2 pip 安装路径在哪

pip show openclaw | grep Location

5.3 如何修复 PATH

export PATH=$(python3 -m site --user-base)/bin:$PATH

5.4 Python 需要什么版本

Python 3.8 或更高。

5.5 如何使用虚拟环境

python3 -m venv myenv
source myenv/bin/activate
pip install openclaw

5.6 ModuleNotFoundError

检查包名，安装依赖，使用虚拟环境。

5.7 如何从 GitHub 安装

pip install git+https://github.com/anthropics/openclaw.git

5.8 pipx 是什么

Python CLI 工具安装器，自动创建隔离环境。

5.9 权限不足怎么办

使用 pip install --user openclaw 或虚拟环境。

5.10 排查清单速查表

□ 1. which openclaw 检查
□ 2. pip show openclaw | grep Location
□ 3. export PATH 添加到 ~/.bashrc
□ 4. python3 --version 检查 3.8+
□ 5. python3 -m venv 虚拟环境
□ 6. source venv/bin/activate
□ 7. pip install openclaw
□ 8. pip install git+github 源码安装
□ 9. pipx install openclaw
□ 10. pip install --user openclaw

6. 总结

1. 根本原因：安装失败最常见原因是 PATH 问题（35%）和 Python 版本不兼容（20%）
2. 最佳实践：使用虚拟环境安装，pip install openclaw
3. PATH 修复：export PATH=$(python3 -m site --user-base)/bin:$PATH
4. 虚拟环境：python3 -m venv + source activate + pip install
5. 最佳实践建议：使用 pipx 全局安装 CLI 工具，使用虚拟环境管理依赖

故障排查流程图

flowchart TD
    A[command not found] --> B[which openclaw 检查]
    B --> C{找到?}
    C -->|否| D[pip show openclaw | grep Location]
    D --> E[export PATH 添加]
    E --> F[openclaw --version 验证]
    C -->|是| F
    F --> G{成功?}
    G -->|是| H[✅ 问题解决]
    G -->|否| I[python3 --version]
    I --> j{Python 3.8+?}
    j -->|否| K[pyenv install 3.12]
    j -->|是| L[检查包名]
    K --> M[pip install openclaw]
    L --> N{包名正确?}
    N -->|否| O[pip install open-claw 或 GitHub]
    N -->|是| P[检查依赖]
    O --> M
    P --> Q[python3 -c "import openclaw"]
    Q --> R{导入成功?}
    R -->|否| S[pip install 依赖]
    R -->|是| T[使用虚拟环境]
    S --> M
    T --> U[python3 -m venv + activate]
    U --> M
    M --> V{成功?}
    V -->|是| H
    V -->|否| W[使用 pipx]
    W --> X[pipx install openclaw]
    X --> H
    H --> Y[长期: venv + pip + PATH]
    Y --> Z[✅ 长期方案]