Installation Guide
==================

System Requirements
-------------------

* **Python**: 3.10 or higher
* **Operating System**: Linux, macOS, or Windows
* **Memory**: 4GB minimum, 8GB recommended
* **Disk**: 1GB free space
* **Network**: Internet connection for market data

Install from Source
-------------------

1. **Clone the repository**:

.. code-block:: bash

   git clone https://github.com/yourusername/openclaw-trading.git
   cd openclaw-trading

2. **Create a virtual environment**:

.. code-block:: bash

   python -m venv .venv

3. **Activate the environment**:

On Linux/macOS:

.. code-block:: bash

   source .venv/bin/activate

On Windows:

.. code-block:: bash

   .venv\Scripts\activate

4. **Install dependencies**:

.. code-block:: bash

   pip install -e "."

5. **Install development dependencies** (optional):

.. code-block:: bash

   pip install -e ".[dev]"

6. **Verify installation**:

.. code-block:: bash

   python -c "import openclaw; print('OpenClaw installed successfully')"

Development Install
-------------------

For contributors or developers:

.. code-block:: bash

   # Install with all dev dependencies
   pip install -e ".[dev]"

   # Install pre-commit hooks
   pre-commit install

   # Run tests
   pytest tests/

   # Run linting
   ruff check .
   black --check .

   # Run type checking
   mypy src/openclaw

Docker Install
--------------

Build and run with Docker:

.. code-block:: bash

   # Build image
   docker build -t openclaw-trading .

   # Run container
   docker run -it --rm openclaw-trading

Using Docker Compose:

.. code-block:: bash

   # Start all services
   docker-compose up -d

   # View logs
   docker-compose logs -f

   # Stop services
   docker-compose down

Configuration
-------------

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

Create a ``.env`` file:

.. code-block:: bash

   # Copy example
   cp .env.example .env

   # Edit configuration
   nano .env

Common settings:

.. list-table::
   :header-rows: 1

   * - Variable
     - Description
     - Default
   * - ``INITIAL_CAPITAL``
     - Starting capital for agents
     - ``10000.0``
   * - ``TOKEN_COST_PER_1M_INPUT``
     - Cost per 1M input tokens
     - ``2.5``
   * - ``TOKEN_COST_PER_1M_OUTPUT``
     - Cost per 1M output tokens
     - ``10.0``
   * - ``TRADE_FEE_RATE``
     - Trading fee (0.001 = 0.1%)
     - ``0.001``
   * - ``LOG_LEVEL``
     - Logging level
     - ``INFO``

Configuration Files
~~~~~~~~~~~~~~~~~~~

Place configuration files in ``config/``:

.. code-block:: yaml

   # config/default.yaml
   environment: development

   economy:
     initial_capital: 1000.0
     token_cost_per_1m_input: 2.5
     token_cost_per_1m_output: 10.0

Troubleshooting
---------------

Installation Issues
~~~~~~~~~~~~~~~~~~~

**Permission Errors**

.. code-block:: bash

   # Use --user flag
   pip install --user -e "."

   # Or use virtual environment (recommended)
   python -m venv .venv

**Missing System Dependencies**

On Ubuntu/Debian:

.. code-block:: bash

   sudo apt-get update
   sudo apt-get install python3-dev build-essential

On macOS:

.. code-block:: bash

   # Install Xcode command line tools
   xcode-select --install

**Python Version Issues**

.. code-block:: bash

   # Check Python version
   python --version

   # Install Python 3.10+ if needed
   # On Ubuntu:
   sudo apt-get install python3.10 python3.10-venv

   # On macOS with Homebrew:
   brew install python@3.10

Verification
------------

Test the installation:

.. code-block:: bash

   # Run unit tests
   pytest tests/unit -v

   # Run a simple example
   python examples/01_quickstart.py

   # Check CLI
   openclaw --help

Next Steps
----------

* Read the :doc:`quickstart` guide
* Explore :doc:`examples`
* Review :doc:`architecture`