OpenClaw command not found 怎么解决？3 种方案实测，附完整排查流程

昨天刷到 OpenClaw 龙虾梗满天飞，手痒装了一个想玩玩。结果 pip install 跑完，终端敲 openclaw 直接给我一个 command not found，心态当场崩了。折腾了大半天，把 PATH、Python 环境、安装方式全排查了一遍才搞定。把过程记下来，省得你们踩同样的坑。

遇到这个报错，核心原因就三个：pip 安装的脚本目录没加到 PATH 里、Python 环境搞混了（系统 Python 和 conda/venv 打架）、或者包名装错了。按优先级逐个排查。

先说结论

原因	出现概率	解决耗时	难度
PATH 没包含 pip scripts 目录	60%	2 分钟	⭐
Python 多版本/虚拟环境混乱	25%	5 分钟	⭐⭐
包名拼错 / 安装不完整	10%	3 分钟	⭐
系统权限问题	5%	10 分钟	⭐⭐⭐

90% 的情况，前两个方案就能解决。

环境准备

先确认基本环境：

# 看看 Python 和 pip 在哪
which python3
which pip3
python3 --version
pip3 --version

我的环境是 macOS + Python 3.12 + zsh，Windows 用户后面会单独说差异。

方案一：PATH 问题（最常见）

这是我遇到的情况。pip 安装 CLI 工具时，可执行文件会放到一个 scripts 目录里，但这个目录不一定在你的 PATH 里。

第一步：找到 openclaw 装到哪了

# 查看 pip 安装位置
pip3 show openclaw

# 找可执行文件
find $(python3 -m site --user-base) -name "openclaw" 2>/dev/null

# 或者直接搜
find ~/.local -name "openclaw" 2>/dev/null

执行完发现它躺在 ~/.local/bin/openclaw，但 PATH 里压根没有 ~/.local/bin。

第二步：把路径加到 PATH

# macOS / Linux (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 如果你用 bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows 用户：

# 先找到 Scripts 目录
python -m site --user-site
# 输出类似：C:\Users\你的用户名\AppData\Roaming\Python\Python312\site-packages
# 把 site-packages 替换成 Scripts，加到系统环境变量 PATH 里

# 或者直接用
python -m openclaw

加完 PATH 再敲一次：

openclaw --version

直接输出版本号，问题解决。

方案二：Python 环境打架

方案一没用的话，八成是 Python 环境乱了。这个坑我之前配 AI Coding 工具时踩过好几次。

排查流程：

# 看你到底有几个 Python
which -a python3
which -a pip3

# 看 pip 对应哪个 Python
pip3 -V
# 输出类似：pip 24.x from /usr/lib/python3/dist-packages/pip (python 3.12)

# 看 openclaw 装在哪个环境
pip3 show openclaw | grep Location

常见的坑：用 pip3 install 装的，但终端默认的 python3 指向另一个版本。

用 pipx 安装（2026 年了，CLI 工具就该用 pipx）

# 安装 pipx
pip3 install --user pipx
python3 -m pipx ensurepath

# 重启终端后
pipx install openclaw

pipx 会自动创建隔离环境，并把可执行文件放到 PATH 里，环境冲突直接绕过去。

# 验证
openclaw --version

用 conda 的话更直接：

# 确保在正确的 conda 环境里
conda activate your_env
pip install openclaw
openclaw --version

方案三：包名 / 安装不完整

有些同学是从 GitHub clone 下来装的，不走 PyPI：

# 卸载干净重装
pip3 uninstall openclaw -y

# 从 PyPI 安装
pip3 install openclaw --upgrade

# 或者从源码
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pip3 install -e .

还有一种情况是安装时有依赖报错但没注意（终端刷太快没看到红字），重装加 --verbose 看完整日志：

pip3 install openclaw --verbose 2>&1 | tee install.log
# 然后搜 ERROR
grep -i error install.log

踩坑记录

坑 1：macOS 自带 Python 被 Homebrew 覆盖

我 Mac 上 python3 指向 Homebrew 装的 3.13，但 pip3 还是系统的 3.12。装完之后 openclaw 跑不起来，因为依赖装到了 3.12 的 site-packages，运行时用的却是 3.13。

解决：用 python3 -m pip install openclaw 而不是直接 pip3，保证 pip 和 Python 对应同一个版本。

坑 2：Windows PowerShell 执行策略拦截

有个群友 Windows 上装好了、PATH 也对，但执行 openclaw 报的不是 command not found 而是执行策略错误。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

坑 3：装好了但调 API 报认证错误

这个不算 command not found 的问题，但装好之后紧接着就会遇到。OpenClaw 底层调的是各家大模型 API，得配 API Key。如果不想挨个去各家注册，可以用聚合 API 平台统一搞定。

我现在用的是 ofox.ai，一个 Key 调 50+ 模型（GPT-5、Claude Opus 4.6、Gemini 3、DeepSeek V3 都有），改个 base_url 就行：

from openai import OpenAI

client = OpenAI(
 api_key="your-ofox-key",
 base_url="https://api.ofox.ai/v1" # 聚合接口
)

# 测试一下连通性
response = client.chat.completions.create(
 model="claude-sonnet-4-20250514",
 messages=[{"role": "user", "content": "Hello from OpenClaw!"}],
 stream=True
)

for chunk in response:
 if chunk.choices[0].delta.content:
 print(chunk.choices[0].delta.content, end="")

ofox.ai 是 AI 模型聚合平台，低延迟直连，支持支付宝/微信，按量计费，有免费版可以先试试手感。在 OpenClaw 里切换不同模型跑对比的话，用聚合接口比分别管理多个 Key 省事太多。

完整排查流程图

graph TD
 A[openclaw command not found] --> B{which openclaw 有输出吗?}
 B -->|没有| C{pip show openclaw 有结果吗?}
 B -->|有| G[权限问题: chmod +x]
 C -->|没有| D[重新安装: pip3 install openclaw]
 C -->|有| E{find 找到可执行文件了吗?}
 E -->|找到了| F[PATH 问题: 把目录加到 PATH]
 E -->|没找到| H{检查 Python 版本对应}
 H --> I[用 python3 -m pip install openclaw]
 H --> J[或用 pipx install openclaw]
 D --> K[检查安装日志有无 ERROR]
 K -->|有报错| L[解决依赖问题后重装]
 K -->|无报错| E
 F --> M[source ~/.zshrc 后验证]
 I --> M
 J --> M
 M --> N{openclaw --version 正常?}
 N -->|是| O[搞定 ✅]
 N -->|否| P[提 Issue / 群里问]

小结

command not found 看着吓人，排查思路其实很固定：先看装没装上，再看 PATH 对不对，最后看环境有没有串。2026 年了，装 CLI 工具建议直接上 pipx，能省掉大多数环境问题。

OpenClaw 这波龙虾梗整得挺乐的，工具本身确实有点意思，装好了值得玩玩。还卡在别的报错上的话，评论区甩出来，我看到了帮你看看。