软件技术第一课：用Git克隆OpenClaw源码，在本地跑起来

上回我们讲了怎么用pip安装OpenClaw，然后写了个简单的天气智能体。但如果你跟我一样，总想看看“里面到底是怎么跑的”，或者你打算以后自己改改代码、加点私货，那光靠pip装好的包就不够用了。这时候就得把源码拉下来，在本地跑一份开发版。

这一课，我们就来干这件事。放心，不会比上次难多少，只是多了几个步骤。我会尽量把每个坑都提前指出来。

为什么要从源码跑？

可能有人会问：pip install它不香吗？香，但是源码版有几个好处：

• 可以看源码：出bug了你至少知道去哪个文件里找
• 方便改代码：想加个自定义工具，直接改完就能测试
• 追新功能：官方可能还没发新版，但GitHub上已经合并了新特性

我自己就是从pip版入坑，后来发现想加点东西必须动源码，才老老实实去学怎么克隆运行。别怕，学完这课你就又多了一项技能。

准备工作：先把Git装上

要克隆源码，电脑上得有Git。这玩意儿就像是一个版本管理工具，可以帮你把GitHub上的代码完整下载下来。

安装Git

• Windows：去Git官网下载安装包，一路下一步就行。装完在开始菜单里找“Git Bash”，打开就是命令行。
• Mac：如果你装了Homebrew，执行brew install git。没装的话，系统可能自带了，终端输入git --version看看。
• Linux：sudo apt install git（Ubuntu/Debian）或者sudo yum install git（CentOS）。

装完之后验证一下：

git --version

能显示版本号就说明OK了。我第一次装Windows版的时候忘了勾选“添加到PATH”，结果在CMD里用不了，只能去用Git Bash。后来重装了一次才搞定。如果你也遇到这问题，重装时记得选“Git from the command line and also from 3rd-party software”。

确定Python版本

和上次一样，Python版本最好在3.9到3.11之间。因为OpenClaw有些依赖对3.12的支持还不完善，别问我怎么知道的，我折腾了两个晚上。

python --version
# 或者
python3 --version

如果版本不对，建议用pyenv（Mac/Linux）或者直接从官网装一个。Windows用户直接去python.org下载安装就行，安装时记得勾选“Add Python to PATH”。

第一步：克隆OpenClaw源码

先打开终端（或者Git Bash），选一个你喜欢的目录，比如桌面或者文档。然后执行：

git clone https://github.com/openclaw-ai/openclaw.git

这个命令会把整个仓库下载到你当前目录下的openclaw文件夹里。

网络问题：如果你在墙内，GitHub克隆可能会很慢，甚至断掉。有两种解决办法：

1. 用代理（如果你有的话）
2. 用镜像加速，比如把https://github.com/换成https://hub.fastgit.xyz/，不过这种镜像不稳定，建议还是老实等或者找个网好的时候

克隆完成后，进入目录：

cd openclaw

第二步：创建虚拟环境

这一步和上次一样，一定要做。源码版的依赖可能更多，隔离起来省心。

# 创建虚拟环境
python -m venv venv

# 激活（Windows）
venv\Scripts\activate

# 激活（Mac/Linux）
source venv/bin/activate

看到终端前面有(venv)就对了。

第三步：安装依赖

源码版不像pip安装那样一条命令搞定所有，因为有些依赖是开发版的，得用requirements.txt或者pyproject.toml来装。

在OpenClaw的根目录下，一般会有requirements.txt。我们先装这个：

pip install -r requirements.txt

这个命令会把项目需要的基础依赖都装上。但是，我当初第一次跑的时候，这里就卡住了——因为有些包在国内下载很慢，或者干脆下载失败。

常见问题：

• 下载超时：可以换国内镜像源，比如用清华源：

  pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
  

• 某个包安装失败：比如numpy或torch，可能是因为Python版本不匹配，或者系统缺少编译环境。Windows用户建议去Unofficial Windows Binaries找对应的whl文件手动装。Mac/Linux用户可能需要先装一些系统依赖，比如build-essential。

如果你只是想跑起来，可以试试用pip直接装openclaw的源码版：

pip install -e .

这个命令会以“可编辑模式”安装当前目录下的项目，也就是你修改源码后不需要重新安装就能生效。-e模式也会自动处理依赖，但有时候依赖不全，建议先装requirements.txt再执行这个。

我当时是先用镜像装了requirements.txt，然后又执行了pip install -e .，最后所有功能才正常。

第四步：配置环境变量

源码版的智能体同样需要API Key。你可以在终端里临时设置，也可以创建一个.env文件。

我比较喜欢用.env文件，省得每次重新打开终端都要输一遍。

在openclaw目录下新建一个.env文件，内容如下：

OPENAI_API_KEY=sk-你的密钥

然后源码里如果有加载.env的机制（一般项目都会支持python-dotenv），就会自动读取。如果不支持，你可以在运行脚本之前手动导出。

第五步：运行示例程序

OpenClaw的源码里通常会有examples文件夹，里面放着一些示例。我们来找一个最简单的跑一下。

cd examples

看看里面有没有basic_agent.py或者hello_world.py之类的。如果没有，我们就用上次那个天气助手的代码，但这次直接在源码目录下创建一个新的测试文件。

为了保险起见，我习惯先在项目根目录下建一个test.py，内容就是简单的：

from openclaw import Agent

agent = Agent(name="Test", instructions="你是一个助手")
response = agent.run("你好")
print(response)

然后运行：

python test.py

如果顺利，你会看到智能体回复了一句问候。如果报错ModuleNotFoundError: No module named 'openclaw'，说明pip install -e .没执行，或者虚拟环境没激活。

常见坑点汇总

坑1：Python版本不对

症状：安装某些包时报错，或者运行时报SyntaxError，因为用了3.12的新语法但项目没兼容。

解决：换回3.10或3.11。我目前用3.10.12，一切正常。

坑2：依赖安装到系统Python里了

症状：明明在虚拟环境里执行了pip install，但运行python test.py还是提示缺少模块。

解决：检查一下which python（Mac/Linux）或where python（Windows），看路径是不是指向了虚拟环境里的venv。如果不是，说明你忘了激活虚拟环境，或者激活后又被重置了。

坑3：克隆下来的代码缺少子模块

有些项目会用git submodule，如果直接git clone可能子模块是空的。OpenClaw好像没有子模块，但万一你遇到，可以执行：

git submodule update --init --recursive

坑4：运行示例时找不到模块

如果你在examples目录下直接运行脚本，可能报错ImportError: attempted relative import with no known parent package。这是因为Python找不到项目根目录。解决办法：

• 在项目根目录下运行：python -m examples.basic_agent（注意是模块方式，不要加.py）
• 或者临时把项目根目录加入PYTHONPATH：export PYTHONPATH=$(pwd)（Mac/Linux）或set PYTHONPATH=%cd%（Windows），然后再运行。

跑通了，然后呢？

恭喜，你现在手上有一套完整的OpenClaw源码，并且可以在本地随意修改了。接下来你可以：

• 翻翻openclaw/agents下的源码，看看Agent类到底是怎么工作的
• 修改openclaw/tools，自己加一个新工具
• 试着改一下提示词模板，看看能不能让智能体更“皮”一点

我自己第一次跑通源码版的时候，第一件事就是把agent.run方法里的打印日志打开，想看看它和OpenAI API是怎么交互的。那种感觉就像打开了一个黑盒，里面原来没那么神秘。

最后说两句

从克隆源码到跑起来，其实就多了一两步。很多新手觉得“源码版一定很复杂”，其实只要你把环境搞对了，剩下的就是耐心等依赖下载。

如果你在某个步骤卡住了，别急。检查一下Python版本、虚拟环境有没有激活、网络是不是通的。这三个查完，八成问题就解决了。

下一篇我准备写怎么读懂OpenClaw的源码，从入口开始一步步跟下去，看看一个智能体从收到消息到返回结果，中间到底经历了什么。感兴趣的话，可以点个关注，别错过了。

好了，去试试吧。等你跑通的那一刻，你会发现自己又上了一层楼。