# claw-erp

AI multi-agent backend for Odoo ERP. Connects AI agents to your Odoo instance and exposes a REST API for dashboards.

## What is this?

claw-erp connects AI agents to your Odoo ERP and exposes a REST API + WebSocket for dashboards. It provides:

- **Multi-agent support** — specialized agents for finance, sales, operations
- **Odoo integration** — reads ERP data via MCP protocol (JSON-RPC)
- **REST API** — endpoints for KPIs, insights, charts, chat
- **WebSocket chat** — real-time conversation with streaming
- **Memory** — persistent context between conversations
- **Cron/Heartbeat** — proactive monitoring and scheduled reports
- **Skills** — modular capabilities via SKILL.md files
- **Multi-provider LLM** — Anthropic, OpenAI, Moonshot/Kimi, Ollama, Groq, and more

## Quick Start

```bash
# Clone
git clone https://github.com/PayDece/claw-erp.git
cd claw-erp

# Configure
cp .env.example .env
# Edit .env with your Odoo and LLM credentials

# Run with Docker
cd docker && docker compose up --build

# Or run locally
pip install -e "."
clawerp gateway
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Service health check |
| GET | `/api/agents` | List configured agents |
| GET | `/api/kpis` | Current KPIs from Odoo |
| GET | `/api/kpis/cfo` | CFO-specific financial KPIs |
| GET | `/api/insights` | Agent-generated insights |
| GET | `/api/insights/cfo` | CFO-specific insights |
| GET | `/api/charts/cfo` | CFO financial charts |
| POST | `/api/chat` | Send message, get response |
| WS | `/api/ws/chat` | Real-time chat |

## Configuration

- **Odoo**: Set `ODOO_URL`, `ODOO_DB`, `ODOO_USERNAME`, `ODOO_PASSWORD` in `.env`
- **LLM**: Set at least one provider API key (e.g., `MOONSHOT_API_KEY`, `ANTHROPIC_API_KEY`)
- **API**: Set `API_KEY` for dashboard authentication
- **MCP**: Configure Odoo MCP server in `config/config.example.json`

## Architecture

```
Dashboard (Next.js) ──REST/WS──> claw-erp (Python) ──JSON-RPC──> Odoo
                                    |
                                    |── FastAPI (REST + WebSocket)
                                    |── Agent Runtime (LLM + Tools)
                                    |── MCP Client (Odoo connector)
                                    |── Skills (SKILL.md)
                                    |── Memory (MEMORY.md)
                                    +── Cron/Heartbeat
```

## Project Structure

```
clawerp/          # Core Python package
  api/            # FastAPI REST + WebSocket
  agent/          # Agent runtime, tools, memory
  channels/       # Messaging platform adapters
  config/         # Pydantic configuration
  cron/           # Scheduled tasks
  heartbeat/      # Periodic monitoring
  providers/      # LLM providers
skills/           # Workspace skills (SKILL.md files)
workspace/        # Agent workspace (SOUL.md, MEMORY.md, HEARTBEAT.md)
docker/           # Docker deployment
config/           # Configuration examples
```

## Security

This repository has been audited with multiple security scanners:

**Gitleaks** — Secret detection scanner
- Result: **0 leaks found** in public repository
- No API keys, passwords, or tokens in tracked files
- All credentials use environment variable placeholders (`${VAR}`)

**Oktsec** — AI agent security auditor ([oktsec.com](https://oktsec.com))
- Scanned MCP configuration and workspace files (SOUL.md, TOOLS.md)
- Findings: OCLAW-007 (env var placeholders flagged as credential fields — expected, they are `${PLACEHOLDERS}` not real values), OCLAW-012 (broad Odoo tool access — by design, the agent needs ERP read access)
- Recommendation: enable sandbox mode for production deployments

**Aguara** — Static security scanner for AI agent skills & MCP servers ([aguarascan.com](https://aguarascan.com))
- 131 files scanned with 173 rules in 1.33s
- **14 findings**: 1 critical, 6 high, 2 medium, 5 low
- Critical: `SUPPLY_018` in tmux skill (false positive on heading text — inherited from nanobot framework, not used in production, patched)
- High: credential logging without redaction (`CRED_018`), unescaped HTML output in Telegram channel (`THIRDPARTY_006`), canonicalization bypass in DingTalk (`MCP_016`)
- Most findings are in inherited framework code (channels, skills), not in the Odoo-specific code we wrote
- Full report: run `aguara scan .` locally

**Credential management:**
- `.env` file is in `.gitignore` — never committed
- `config.json` uses `${ENV_VAR}` placeholders only
- Docker entrypoint injects secrets at runtime from environment variables

To run your own audit:
```bash
# Secret scanning
brew install gitleaks
gitleaks detect --source . --no-git -v

# AI agent security audit (oktsec)
go install github.com/oktsec/oktsec/cmd/oktsec@latest
oktsec scan-openclaw --path ./config.json

# AI agent skill & MCP scanner (aguara)
go install github.com/garagon/aguara/cmd/aguara@latest
aguara scan .
```

## Dashboard

This backend is designed to work with [paydece-mission-control](https://github.com/PayDece/paydece-mission-control), a Next.js dashboard that provides:

- Real-time CFO KPIs from Odoo
- AI-generated financial insights
- Interactive chat with the AI agent
- Charts and data visualization

## License

MIT