把 Geneclaw 跑起来，只要七步

昨天那篇解决的是“Geneclaw 到底是什么”。今天这篇不再谈谱系，只做一件更硬的事：把它真正跑起来，而且不是“命令敲完就算”，而是确认你装对了、命令走通了、失败时知道该往哪查。

这篇文章默认你已经知道两件事。第一，Geneclaw 不是基因分析工具，而是一个基于 nanobot 的自演化 Agent 框架。第二，我们今天的目标不是把它研究透，而是完成一次可信的本地首跑：环境对、依赖对、CLI 对、第一条流程能走。

很多人卡死，不是因为 Geneclaw 太难，而是因为一上来就 pip install，根本没先确认自己正在用哪个 Python、pip 是不是同一个解释器、网络能不能拉依赖、后面要不要 API key。这篇就按这个思路来。

而且这篇会优先按 Windows 用户来写。原因很现实：今天最常见的失败场景，本来就集中在 Windows——Microsoft Store Python、python 和 py 混用、PowerShell 激活脚本被拦、PATH 混乱、pip 装进了另一个解释器里。你如果是 macOS 或 Linux 用户，命令思路一样，只是个别命令要换写法。

先做一个 30 秒预检

在你 clone 之前，先把下面三条敲出来。它们的价值比一上来安装大得多：

1
2
3

python --version
python -m pip --version
python -c "import sys; print(sys.executable)"

如果你在 Windows 上，建议再补两条：

1 2	py -V where python

你要确认的是三件事：

第一，你的 Python 至少是 3.11。第二，你后面要用的 pip 就挂在这个 Python 身上，而不是系统里另一个旧版本。第三，你知道当前解释器到底装在哪。很多 Windows 机器的问题，从这里就已经能看出来了：装的是 Microsoft Store Python，或者系统里同时有三个 Python，结果 python 和 pip 不认同一个环境。

如果 py -V 能正常输出版本，后面在 Windows 下我更建议你优先用 py -3.11 这类写法，因为它比裸 python 更不容易误连到旧环境。

第一步：确认你的 Python 环境

Geneclaw 要求 Python >= 3.11。

最基本的检查还是这一条：

1	python --version

如果不是 3.11 或更高版本，你需要先装一个。这里最稳的做法不是乱装，而是直接选一个你自己能控制的发行版。对大多数人来说，Miniconda 是最省事的：

1
2
3

# Windows 用这个
winget install Anaconda.Miniconda3
# 或者直接去官网下 Miniconda

装完后，关掉旧终端，重新开一个终端，再跑一次：

1 2	python --version python -m pip --version

如果这里还不对，不要进入下一步。因为后面所有报错，十有八九都会被你误判成“项目问题”，其实是解释器就没选对。

如果你是 Windows 用户，我这里再给一个更明确的建议：

不要优先用 Microsoft Store 里那个 Python，也不要随手下来源不明的集成包。最稳的还是官方 Python 或 Miniconda。你需要的是一个你知道装在哪里、知道怎么被 PATH 调用、知道怎么创建独立环境的 Python，而不是“电脑里反正有个 Python”。

第二步：准备一个合适的目录

不要在系统默认位置跑，也别在下载目录里直接堆。单独建一个你自己能管理、以后能删干净的目录：

1 2	mkdir geneclaw-test cd geneclaw-test

这样做不是形式主义，而是为了把这次首跑和你电脑上其他 Python 项目隔开。后面如果环境坏了，你能整目录删掉重来，不用猜到底污染了哪一层。

第三步：克隆仓库

1 2	git clone https://github.com/Clawland-AI/Geneclaw.git cd Geneclaw

到这里先别急着安装。先看一眼当前目录是不是像一个正常的 Python 项目：有没有 pyproject.toml，有没有 README，仓库名字对不对。你不是在证明自己会 clone，而是在确认你拿到的是一个完整项目，而不是浏览器随手下来的 zip 或错误目录。

第四步：创建虚拟环境（强烈建议）

这一步国内学生最容易跳过，然后从第五步开始一路踩坑。一定要用虚拟环境，而且最好是一项目一环境。

# 如果你装了 conda
conda create -n geneclaw python=3.11
conda activate geneclaw

# 如果你用 pip 自带的 venv（Windows 更建议直接指定 py）
py -3.11 -m venv .venv

# 通用写法
python -m venv venv
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# Windows cmd:
.venv\Scripts\activate.bat
# Linux/Mac:
source venv/bin/activate

这里有个 Windows 用户特别常见的坑：PowerShell 可能会拦激活脚本。如果你看到类似“因为系统上禁止运行脚本，所以无法加载”的报错，不是 venv 坏了，而是 PowerShell 执行策略在拦。最小修法通常是当前用户级别放开：

1	Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

然后重新打开 PowerShell 再激活。不要一看到激活失败就重新装 Python，很多人就是在这里白折腾半小时。

激活完别自我感动，马上再做一次绑定检查：

1
2
3

python --version
python -m pip --version
python -c "import sys; print(sys.executable)"

如果你看到的 Python 路径已经落在这个新环境里，说明你现在安装的包才会进这个环境。很多人以为自己“开了 venv”，结果终端里实际走的还是系统 Python，这类问题后面会表现成“明明装了包却 import 不到”。

第五步：安装依赖

官方给出的安装方式是：

1	python -m pip install -e ".[dev]"

如果你还想跑 dashboard（可视化界面），装这个：

1	python -m pip install -e ".[dev,dashboard]"

这里我故意把原来的 pip install 改成了 python -m pip install。原因很简单：这样能最大限度确保你调用的是当前这个解释器自己的 pip，而不是 PATH 里某个别的 pip。

再解释一下 -e。它不是“高级玩法”，而是 editable install。意思是这个仓库会以开发模式装进当前环境，后面你改本地代码，CLI 还是能直接指向这份代码。像 Geneclaw / nanobot 这种框架型项目，首跑阶段用它是合理的。

如果安装很慢或超时，先别判断项目坏了。国内网络条件下，最常见的问题就是 PyPI 拉取慢、间歇失败，或者某些依赖下载不稳定。可以先试镜像：

1	python -m pip install -e ".[dev]" -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你在 Windows 上已经确认 py 是正常的，也可以写成：

1	py -3.11 -m pip install -e ".[dev]"

这会进一步减少“命令明明跑了，但其实装进另一个 Python”这种问题。

如果你在这里就失败，优先看三类信息：

第一类，版本不兼容，比如 Python 太低。第二类，网络或下载失败。第三类，编译型依赖在你的系统上缺基础工具链。不要把这三类错误混成一句“装不上”。

第六步：验证安装成功

安装完成后，检查 nanobot 命令是否可用：

1	nanobot --help

如果输出了帮助信息，说明安装成功。

然后试一下 Geneclaw 相关的命令：

1	nanobot geneclaw --help

这一步不是走形式，它实际在回答两个问题：

第一，入口脚本有没有正确注册；第二，Geneclaw 的子命令有没有真的挂进去。如果 nanobot --help 能跑而 nanobot geneclaw --help 不行，那就不是“整个项目没装上”，而更可能是 extras、模块注册或当前 checkout 本身有问题。

如果你想进一步确认 CLI 的确来自当前环境，可以再跑：

1	python -c "import shutil; print(shutil.which('nanobot'))"

它会告诉你 nanobot 这个命令到底指向哪。

Windows 用户也可以补一条：

1	where nanobot

如果这里返回了多个路径，就要小心。你可能不是第一次装它，或者之前别的环境里也注册过同名命令。

第七步：跑通第一个流程

Geneclaw 默认是 dry-run 模式，不会真的改你的代码。先让它跑一个最简单的流程试试：

1	nanobot geneclaw doctor

这个命令的价值非常高，因为它不是在“展示功能”，而是在帮你先做一次环境体检。如果一切正常，会输出类似 “All checks passed” 的信息。即便不完全正常，它也往往比你直接上 autopilot 更早暴露问题。

如果你想看它更完整的流程，可以跑：

1	nanobot geneclaw autopilot --goal "Write a hello world function"

这里的目标故意写得很小。第一次跑，不要上来就给复杂目标，更不要把自己的真实项目目录直接丢进去。你现在只想验证三件事：命令能起、流程能走、日志能读。

关键不是它最后有没有“写出一个好函数”，而是它有没有走完 Observe → Diagnose → Propose → Gate → Execute 这条链路。因为默认是 dry-run，所以它不会真的改你的文件，这正适合作为第一轮验证。

如果 doctor 能过、autopilot 也能跑到后面，你就已经完成了首跑。到这里，才算真正有资格讨论“这个框架适不适合继续深挖”。

如果你已经到这一步，还想再确认一点，可以顺手看看日志或终端输出里有没有明确出现 doctor、diagnose、propose、gate 这类阶段性提示。第一次跑的时候，你要学会看的不是“它好不好用”，而是“它到底卡在流程的哪一段”。

常见问题

1. pip install 报错找不到包

先检查 Python 版本是不是 3.11+，然后检查 pip 本身是不是最新：

1	python -m pip install --upgrade pip

如果升级 pip 后还是报同样的错，再看报错里到底是“包不存在”、还是“网络没拉下来”、还是“构建失败”。这三类处理方式完全不同。

2. 装了多个 Python，导致找不到命令

如果你之前装过多个版本的 Python，python 和 pip 可能指向不同版本。不要猜，直接查：

# 确认 python 和 pip 指向同一个解释器
which python
which pip
# Windows 用 where
where python
where pip

更稳一点，再补一条：

1	python -m pip --version

这条命令会把 pip 归到当前 python 身上，是定位“装进去了但命令不见了”这类问题时最有用的一条。

Windows 下再补两个特别有用的排查命令：

1 2	py -0 where python

py -0 会列出本机 py launcher 能看到的 Python 版本，where python 会告诉你 PATH 里到底有哪些 python.exe。很多“玄学问题”其实到这一步就已经不玄了。

3. 依赖装到系统 Python 里去了

如果你没用虚拟环境，依赖会装到全局。这会导致不同项目之间版本冲突。最直接的症状就是：这个项目刚装完能跑，过几天你装了另一个项目，它又坏了。回到第四步，用虚拟环境，别省。

4. 网络问题导致模型下载失败

Geneclaw 本身不自带大模型，但它在诊断和提案阶段会调用 LLM。如果你没有配置 API key，或者网络不通外网，会在这一步卡住。

这里要分清两层：一层是 Python 包能不能装下来，另一层是运行时模型服务能不能调用成功。前者是 pip / 镜像 / 网络问题，后者是 API key / 模型配置 / 外网连通性问题。不要把这两层混在一起。

国内最常见的做法无非两种：要么走代理，要么切到你自己可访问的 LLM API，并按项目要求改配置。你至少要先知道自己卡在哪一层，再决定怎么救。

如果项目需要环境变量，不要一上来就全局乱配。Windows 下你至少先学会区分两种方式：

PowerShell 当前会话临时设置：

1	$env:OPENAI_API_KEY="your-key"

cmd 当前会话临时设置：

1	set OPENAI_API_KEY=your-key

先临时设通，再考虑要不要写进更长期的环境配置。你现在要的是确认它能跑，不是立刻把机器改成长期工作站。

5. `doctor` 能过，`autopilot` 失败

这通常说明“基础安装”已经完成，但“运行时配置”还没完成。优先检查：

1	nanobot geneclaw --help

然后回头看 README 里和模型、provider、key、配置文件有关的部分。doctor 偏向环境检查，autopilot 更接近真实工作流，后者对运行时配置更敏感。

6. PowerShell、cmd、Git Bash 命令不完全一样

这不是小事。很多初学者直接复制 README 里的命令，结果作者默认的是 bash，而你本地开的是 PowerShell。最常见的区别就出现在虚拟环境激活、环境变量设置、路径写法上。

所以你在 Windows 上要有一个基本原则：先确认这条命令是给哪个 shell 写的，再复制。 如果 README 没写清楚，就优先用 PowerShell 或 cmd 的等价写法，不要硬把 bash 命令往 PowerShell 里塞。

跑完之后该干什么

如果上面七步都走通了，说明你已经跨过了最难的一道门：不是“会看别人跑”，而是“自己机器上确实跑过”。接下来最值得做的不是乱试功能，而是顺着这个顺序往下走。

先把 nanobot geneclaw 的子命令看一遍，知道这个 CLI 入口到底提供了什么。再去看 examples 或官方示例，理解它期待什么输入。然后才是读配置、改参数、观察不同模式的差异。顺序不要反过来。

这篇文章真正想帮你建立的，不是一个 Geneclaw 专属技巧，而是一种跑开源 Agent 项目的基本动作：先校准解释器，再隔离环境，再用 python -m pip 保证安装路径，再用 help / doctor / 最小 autopilot 验证入口、环境和流程。把这套动作练熟了，下次你换的就不只是 Geneclaw。

来源

Geneclaw 官方仓库：https://github.com/Clawland-AI/Geneclaw
Geneclaw 官网：https://geneclaw.ai
nanobot 上游：https://github.com/HKUDS/nanobot