Deployment Guide
================

This guide covers deploying OpenClaw Trading to production environments.

Prerequisites
-------------

System Requirements
~~~~~~~~~~~~~~~~~~~

* Python 3.10 or higher
* 4+ CPU cores (for parallel agent execution)
* 8GB+ RAM
* 10GB+ disk space

Required Services
~~~~~~~~~~~~~~~~~

* Exchange API access (for live trading)
* Market data provider (e.g., Yahoo Finance, Alpha Vantage)
* Optional: Database for persistent storage
* Optional: Redis for caching

Installation
------------

Production Install
~~~~~~~~~~~~~~~~~~

1. Create a dedicated user:

.. code-block:: bash

   sudo useradd -r -s /bin/false openclaw
   sudo mkdir /opt/openclaw
   sudo chown openclaw:openclaw /opt/openclaw

2. Clone and install:

.. code-block:: bash

   cd /opt/openclaw
   sudo -u openclaw git clone https://github.com/yourusername/openclaw-trading.git .
   sudo -u openclaw python3.10 -m venv venv
   sudo -u openclaw venv/bin/pip install -e "."

3. Create environment file:

.. code-block:: bash

   sudo -u openclaw cp .env.example .env
   sudo -u openclaw chmod 600 .env

4. Edit configuration:

.. code-block:: bash

   sudo -u openclaw nano .env

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

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

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

   * - Variable
     - Description
     - Default
   * - ``INITIAL_CAPITAL``
     - Default 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 as decimal
     - ``0.001``
   * - ``DATA_COST_PER_CALL``
     - Cost per market data call
     - ``0.01``
   * - ``LOG_LEVEL``
     - Logging level
     - ``INFO``
   * - ``ENABLE_LIVE_TRADING``
     - Enable live trading (vs paper)
     - ``false``

Configuration File
~~~~~~~~~~~~~~~~~~

Create ``config/production.yaml``:

.. code-block:: yaml

   # Production configuration
   environment: production

   # Economic settings
   economy:
     initial_capital: 10000.0
     token_cost_per_1m_input: 2.5
     token_cost_per_1m_output: 10.0
     trade_fee_rate: 0.001
     data_cost_per_call: 0.01

   # Workflow settings
   workflow:
     enable_parallel: true
     timeout_seconds: 300
     max_retries: 3

   # Exchange settings
   exchange:
     name: alpaca  # or "interactive_brokers", "binance"
     paper_trading: true

   # Logging
   logging:
     level: INFO
     format: json
     output: /var/log/openclaw/trading.log

   # Monitoring
   monitoring:
     enable_metrics: true
     enable_alerts: true
     alert_thresholds:
       drawdown_percent: 10.0
       loss_streak_count: 5

Systemd Service
---------------

Create ``/etc/systemd/system/openclaw.service``:

.. code-block:: ini

   [Unit]
   Description=OpenClaw Trading System
   After=network.target

   [Service]
   Type=simple
   User=openclaw
   Group=openclaw
   WorkingDirectory=/opt/openclaw
   Environment=PYTHONPATH=/opt/openclaw/src
   Environment=ENV=production
   ExecStart=/opt/openclaw/venv/bin/python -m openclaw.cli.main server
   Restart=always
   RestartSec=10

   [Install]
   WantedBy=multi-user.target

Enable and start:

.. code-block:: bash

   sudo systemctl daemon-reload
   sudo systemctl enable openclaw
   sudo systemctl start openclaw

Docker Deployment
-----------------

Dockerfile
~~~~~~~~~~

.. code-block:: dockerfile

   FROM python:3.10-slim

   WORKDIR /app

   # Install dependencies
   COPY pyproject.toml .
   RUN pip install --no-cache-dir -e "."

   # Copy source
   COPY src/ ./src/
   COPY config/ ./config/

   # Create non-root user
   RUN useradd -m -u 1000 openclaw && \
       chown -R openclaw:openclaw /app
   USER openclaw

   # Expose port
   EXPOSE 8000

   # Health check
   HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
       CMD python -c "import openclaw; print('healthy')"

   CMD ["python", "-m", "openclaw.cli.main", "server"]

docker-compose.yml
~~~~~~~~~~~~~~~~~~

.. code-block:: yaml

   version: '3.8'

   services:
     openclaw:
       build: .
       container_name: openclaw-trading
       restart: unless-stopped
       environment:
         - ENV=production
         - INITIAL_CAPITAL=10000
       volumes:
         - ./config:/app/config:ro
         - ./data:/app/data
         - ./logs:/app/logs
       ports:
         - "8000:8000"
       networks:
         - openclaw-network

     # Optional: Redis for caching
     redis:
       image: redis:7-alpine
       container_name: openclaw-redis
       restart: unless-stopped
       volumes:
         - redis-data:/data
       networks:
         - openclaw-network

   volumes:
     redis-data:

   networks:
     openclaw-network:
       driver: bridge

Security Considerations
-----------------------

Secrets Management
~~~~~~~~~~~~~~~~~~

1. Never commit API keys to version control
2. Use environment variables or secret management
3. Rotate keys regularly
4. Use different keys for paper vs live trading

Network Security
~~~~~~~~~~~~~~~~

1. Run behind a firewall
2. Use VPN for exchange connections
3. Enable rate limiting
4. Monitor for unusual activity

Access Control
~~~~~~~~~~~~~~

1. Create dedicated exchange API keys
2. Limit API permissions (no withdrawals)
3. IP whitelist if possible
4. Two-factor authentication

Monitoring
----------

Health Checks
~~~~~~~~~~~~~

.. code-block:: bash

   # Check service status
   sudo systemctl status openclaw

   # Check logs
   sudo journalctl -u openclaw -f

   # Check health endpoint
   curl http://localhost:8000/health

Metrics
~~~~~~~

Monitor these key metrics:

* System uptime
* Agent survival rates
* Average trade PnL
* Decision costs
* API response times
* Error rates

Alerts
~~~~~~

Configure alerts for:

* Agent bankruptcy
* Drawdown thresholds
* API failures
* Unusual trading patterns
* System resource usage

Backup and Recovery
-------------------

Backup Strategy
~~~~~~~~~~~~~~~

1. **Configuration**: Version controlled
2. **Agent States**: Daily backups
3. **Trade History**: Continuous replication
4. **Logs**: Rotated and archived

Recovery Procedure
~~~~~~~~~~~~~~~~~~

1. Stop service: ``sudo systemctl stop openclaw``
2. Restore from backup
3. Verify configuration
4. Start service: ``sudo systemctl start openclaw``
5. Validate operation

Scaling
-------

Horizontal Scaling
~~~~~~~~~~~~~~~~~~

For high-volume trading:

1. Deploy multiple instances
2. Use load balancer
3. Shard by symbol
4. Shared state with Redis

Vertical Scaling
~~~~~~~~~~~~~~~~

Increase resources:

* More CPU cores for parallel analysis
* More RAM for larger datasets
* Faster disk for I/O operations
* Lower latency network

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

Common Issues
~~~~~~~~~~~~~

**High Memory Usage**

* Reduce parallel workers
* Enable memory limits
* Check for memory leaks

**Slow Analysis**

* Check network latency
* Enable caching
* Optimize database queries
* Increase timeout values

**Exchange API Errors**

* Check rate limits
* Verify API keys
* Check network connectivity
* Review exchange status

**Agent Bankruptcies**

* Review strategy parameters
* Check market conditions
* Verify cost calculations
* Adjust risk thresholds

Logs
~~~~

View detailed logs:

.. code-block:: bash

   # Application logs
   tail -f /var/log/openclaw/trading.log

   # System logs
   sudo journalctl -u openclaw -f

   # Error logs
   grep ERROR /var/log/openclaw/trading.log