( *^-^)p ～ smart routing ～ cost optimization ～ multi-provider ～ q(^-^* )

---

>_ What is FreeClaw?

"From Cost Optimization to Intelligent Orchestration" ～(^-^～)

FreeClaw manages your AI API keys, monitors costs, and automatically routes tasks to the cheapest available model — saving you 30-90% on API spending.

                    +-----------+
  Your App  ------> | FreeClaw  | ------> OpenAI
  Claude Code       |  Hub      | ------> Anthropic
  Any Client        | (routing) | ------> Google
                    |  (^_^)    | ------> DeepSeek
                    +-----------+ ------> 40+ more...

>_ Features {#features}

～ Smart Routing ～ Simple task --> Free models (100% savings) Medium task --> Budget models (50-70% savings) Complex task --> Premium models (full power) AI complexity prediction auto-selects the tier!	～ Cost Tracking ～ Daily spending .... $2.40 Free tier used .... 847 calls Money saved ...... $18.60 ------------------------- Efficiency ....... 88.6% (^o^)
～ Circuit Breaker ～ Provider down? No problem! openai .... [OPEN] (healthy) anthropic . [OPEN] (healthy) groq ...... [HALF] (recovering) deepseek .. [CLOSED](bypassed) Auto-fallback, zero downtime.	～ Multi-Interface ～ TUI ......... Textual (SSH) Rich ........ Interactive menu CLI ......... Scripts & bots Hub ......... OpenAI-compatible API

>_ Install {#install}

# Standalone (no OpenClaw needed!)
git clone https://github.com/2233admin/freeclaw.git
cd freeclaw
pip install -r requirements.txt

# Or install as package
pip install .                    # core only
pip install ".[tui]"             # + beautiful TUI
pip install ".[mesh]"            # + Redis cluster support
pip install ".[tui,mesh]"        # everything! (>w<)

As OpenClaw Skill (click to expand)

# If you have OpenClaw installed, FreeClaw auto-detects it
# Config priority:
#   $FREECLAW_CONFIG > ~/.openclaw/openclaw.json > ~/.freeclaw/freeclaw.json

>_ Usage {#usage}

Quick Start ～

# Health check
python lib/cost_monitor.py health

# Launch TUI with startup animation
python clawapi-rich.py

# Route a task (returns best model)
python lib/smart_router.py route "translate hello to Japanese"

# Switch primary model
python lib/model_switcher.py list
python lib/model_switcher.py switch 3

CLI Commands ～

./clawapi status                    # Full status overview
./clawapi providers                 # List all providers
./clawapi models                    # List all models
./clawapi set-primary deepseek/deepseek-chat
./clawapi add-fallback minimax/MiniMax-M2.5
./clawapi validate                  # Check config health

TUI Preview ～

  ______              _____ _
 |  ____|            / ____| |
 | |__ _ __ ___  ___| |    | | __ ___      __
 |  __| '__/ _ \/ _ \ |    | |/ _` \ \ /\ / /
 | |  | | |  __/  __/ |____| | (_| |\ V  V /
 |_|  |_|  \___|\___|\_____|_|\__,_| \_/\_/

  API Hub for 40+ AI Providers

  ok Config       openclaw.json
  ok Providers    2 loaded
  ok Primary      claude-proxy/claude-sonnet-4
  ok Fallbacks    0 models
  ok Router       ready
  ok Breaker      ready

  2 providers  |  4 models  |  0 fallbacks

>_ How It Saves Money

Task	Example	Before	After	Savings
Simple	"what time is it?"	$0.015	$0.00	100%
Medium	"summarize this PR"	$0.30	$0.10	67%
Complex	"architect a microservice"	$1.50	$1.50	0%

Average savings: 30-90% depending on task mix (o^-^o)b

>_ Supported Providers

>_ Architecture {#architecture}

freeclaw/
  ├── clawapi                # Unified CLI entrypoint
  ├── clawapi-rich.py        # Rich TUI (with startup animation!)
  ├── clawapi-tui.py         # Textual TUI (full interactive)
  │
  ├── lib/
  │   ├── constants.py       # Config path resolution
  │   ├── config_manager.py  # Provider/model/fallback management
  │   ├── model_switcher.py  # Safe model switching
  │   ├── smart_router.py    # Three-tier intelligent routing
  │   ├── cost_monitor.py    # Usage tracking & reports
  │   ├── circuit_breaker.py # Provider health & auto-fallback
  │   ├── provider_adapter.py    # Unified provider adapter
  │   ├── builtin_providers.py   # 40+ provider templates
  │   ├── ai_complexity_predictor.py  # AI task analysis
  │   └── mesh_bridge.py    # FSC-Mesh Redis bridge
  │
  ├── .claude-plugin/        # Claude Code plugin metadata
  ├── skills/freeclaw/       # OpenClaw skill definition
  ├── config/                # Configuration templates
  └── data/                  # Runtime data

Config Resolution ～

$FREECLAW_CONFIG          # env var (highest priority)
  └─> ~/.openclaw/openclaw.json   # OpenClaw integration
       └─> ~/.freeclaw/freeclaw.json  # standalone (auto-created)

>_ Troubleshooting

Common issues

See TROUBLESHOOTING.md for:

• Protocol mismatch errors
• Config file corruption recovery
• API key expiration detection
• Circuit breaker status

>_ Roadmap: Claw API Hub

Project Board ～ tracking all tasks

Phase 1: CLI-First (March 2026)

#	Task	Status
#1	typer CLI 统一入口 (claw hub status/keys/cost/route)	🔲 Todo
#2	统一配置管理 (~/.claw/config.toml)	🔲 Todo

Phase 2: Gateway (March–April 2026)

#	Task	Status
#3	OpenAI-compatible HTTP proxy (/v1/chat/completions)	🔲 Todo
#4	流式响应 + SSE 透传	🔲 Todo
#5	熔断器 + 自动降级链 (Claude → DeepSeek → Doubao → Ollama)	🔲 Todo
#7	用量仪表盘 + 超预算报警	🔲 Todo

Phase 3: Mesh (April 2026)

#	Task	Status
#6	mesh_bridge 集群路由共享 (Redis 同步)	🔲 Todo

Vision

密钥管理器  ──→  统一 AI Gateway  ──→  分布式路由集群
 (v1.x)          (v2.0)               (v3.0)

Goal: 所有 AI 调用的唯一出口，CLI-first，agent-native。

>_ Links

---

made with mass mass love by mass mass people ～(=^-^)ノ