Setting up a development environment for openclaw involves a multi-step process that ensures you have the correct system dependencies, can pull the latest source code, configure the application for your specific needs, and begin contributing or building upon the project. This guide will walk you through the entire setup on a Unix-like system (Linux or macOS), which is the standard for this type of development work.
System Prerequisites and Dependency Management
Before you can even think about cloning the repository, you need to prepare your system. The project is built on a modern technology stack, and missing a single dependency can cause the entire setup to fail. The core requirements typically include a specific version of Python, a C++ compiler toolchain, and several system libraries.
Python 3.9+ is non-negotiable. We recommend using a version manager like pyenv to install and manage multiple Python versions seamlessly. This prevents conflicts with your system's Python. After installing pyenv, you can set the local Python version with two commands:
pyenv install 3.9.18
pyenv local 3.9.18
Next, you'll need the build tools. On Ubuntu/Debian, this is handled by the build-essential package. On macOS, you need the Xcode Command Line Tools. You can install them by running xcode-select --install.
Here is a table of common system-level dependencies you'll need to install via your package manager:
| Operating System | Package Manager | Essential Packages to Install |
|---|---|---|
| Ubuntu/Debian | apt | build-essential, cmake, pkg-config, libssl-dev, libffi-dev, python3-dev |
| Fedora/CentOS | dnf / yum | gcc-c++, cmake, pkgconfig, openssl-devel, libffi-devel, python3-devel |
| macOS | Homebrew | cmake, pkg-config, openssl |
Once these are installed, you have a solid foundation. The next critical step is isolating your project's Python environment.
Creating an Isolated Python Environment
Never install Python packages globally. It's a recipe for version conflicts and "dependency hell." Instead, we use a virtual environment. The standard library's venv module is perfect for this. Navigate to your preferred development directory and run:
python -m venv openclaw-env
This creates a folder named openclaw-env containing a completely isolated Python installation. To start using it, you must activate it:
source openclaw-env/bin/activate
Your command prompt should now show (openclaw-env), confirming you are working inside the environment. All subsequent Python-related commands (like pip install) will only affect this isolated space. Remember, you need to activate this environment every time you open a new terminal window to work on the project.
Cloning the Repository and Installing Python Dependencies
With your environment active, it's time to get the source code. Use Git to clone the main repository. The exact URL will depend on where the project is hosted (e.g., GitHub, GitLab).
git clone https://github.com/openclaw/openclaw.git
cd openclaw
Inside the repository, you will find a requirements.txt file and often a setup.py or pyproject.toml file. These files list all the Python packages the project needs. The most reliable way to install them is using pip with the editable flag, which links the installed package to your live code, so changes are reflected immediately.
pip install -e .
This command reads the project's configuration and installs all dependencies, which can number in the dozens. A complex project might have dependencies like numpy for numerical computing, pytorch or tensorflow for machine learning, fastapi for web endpoints, and sqlalchemy for database interaction. The installation process can take several minutes as it compiles any C/C++ extensions. Watch for any error messages; they usually point to a missing system library we covered in the first step.
Configuration and Securing Secrets
The application will not run without proper configuration. You will typically find a template file like config.example.yaml or .env.example. Your first task is to copy this to a new file that the application will actually read, such as config.yaml or .env.
cp config.example.yaml config.yaml
Now, open config.yaml in a text editor. This is where you'll need to provide critical settings. Common configuration parameters include:
- API Keys: For services like OpenAI, Anthropic, or a vector database.
- Database URL: The connection string for your database (e.g.,
sqlite:///./openclaw.dbfor a local SQLite file). - Model Paths: Local file paths to any large language models you plan to use.
- Server Host and Port: Defining which network interface and port the application will run on (e.g.,
127.0.0.1:8000).
Crucially, never commit your config.yaml or .env file to version control. They often contain secrets. Ensure they are listed in the .gitignore file. For added security, consider using a secrets manager for production deployments.
Database Setup and Initialization
Most sophisticated applications require a database. The project likely uses an Object-Relational Mapper (ORM) like SQLAlchemy or Django ORM. The first run of the application often involves creating the database schema. This process is called "migrations."
First, ensure your database is running. If you're using SQLite, the file will be created automatically. For PostgreSQL or MySQL, you need to have the database server running and have created an empty database matching the name in your configuration.
Then, you typically run an command to create the tables. This might look like one of the following, depending on the framework:
python -m alembic upgrade head (for SQLAlchemy with Alembic migrations)
or
python manage.py migrate (if using a Django-based structure)
This command reads the migration files (which are version-controlled SQL scripts) and applies them to your database, bringing it to the latest schema version. You should see a success message and can verify by checking that the necessary tables now exist in your database.
Verifying the Setup with a Test Run
The moment of truth. It's time to start the application. The method depends on the project's design. It could be a simple Python script, a command-line interface (CLI) tool, or a web server.
For a web application, the command might be:
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
The --reload flag is invaluable for development as it automatically restarts the server when you change the code. If successful, you'll see output indicating the server has started. Open your web browser and go to http://127.0.0.1:8000. You might see a landing page, API documentation (like Swagger UI at /docs), or a login prompt.
Additionally, run the project's test suite to ensure everything is working as expected by the developers. This is usually done with pytest:
python -m pytest
A passing test suite gives you high confidence that your environment is correctly configured. If tests fail, the error output is the first place to look for clues about misconfigurations or missing components.
Integrating with an IDE for Productive Development
A proper setup extends to your code editor. Using an IDE like Visual Studio Code or PyCharm dramatically improves productivity. The key is to configure the IDE to use the Python interpreter from the virtual environment you created.
In VS Code, you would press Ctrl+Shift+P (or Cmd+Shift+P on macOS), type "Python: Select Interpreter," and choose the path to the python binary inside your openclaw-env folder. This ensures that the IDE's autocomplete, linting, and debugging tools are aware of all the project's installed packages.
Also, install the relevant extensions for your tech stack, such as a Python extension, a Docker extension if you're using containers, and a linter/formatter like Black or Ruff to maintain code consistency with the project's style guide.
Optional but Recommended: Containerization with Docker
For the most consistent development experience, especially if you work across multiple machines, consider using Docker. The project likely provides a Dockerfile and a docker-compose.yml file.
Docker encapsulates the entire environment—system dependencies, Python version, and application code—into a container. This guarantees that the application runs the same way on your laptop as it does for every other developer and in production. The typical workflow is:
docker-compose up --build
This command builds the images and starts the containers, which might include the application itself, a database, and a redis cache, all networked together. While the initial build can be time-consuming, it eliminates nearly all "it works on my machine" problems and is a valuable skill for modern development.