1 line
19 KiB
JSON
1 line
19 KiB
JSON
{"repo": "captainphantasy/floydclaw", "files": {"OPENCLAW_CONTROL_REQUIREMENTS.md": {"7385c1916541950da05d9a7f9fda256d224ce5f2": {"t": 1785746530.7431405, "n": 18789, "h": "0c01fcb97b14225a", "c": "# OpenClaw Control Requirements Document\n**Generated:** 2026-02-15\n**OpenClaw Version:** 2026.2.14\n**Installation Type:** Binary (Homebrew)\n**Status:** ⚠️ Partially Configured - Needs Setup\n\n---\n\n## Executive Summary\n\nYour OpenClaw installation is **already configured** to use your Floyd AI Proxy Harness as the primary model provider. However, several critical items need attention for full operational control.\n\n**✅ What's Working:**\n- OpenClaw gateway running at `ws://127.0.0.1:18789`\n- Floyd Harness proxy healthy at `http://localhost:8000/v1`\n- GLM-5 model configured as primary (200k context, 131k output)\n- Operator token available with admin scopes\n\n**⚠️ What Needs Attention:**\n- Security vulnerabilities (credentials directory permissions)\n- Memory plugin unavailable\n- No channels configured (Discord/Telegram/Slack)\n- Gateway not running as system service\n- Potential API key exposure in Floyd Harness\n\n---\n\n## Phase 1: Authentication & Access Control\n\n### 1.1 OpenClaw API Tokens\n\nYou have **TWO** tokens for CLI control:\n\n#### A. Gateway Authentication Token\n```\nLocation: ~/.openclaw/openclaw.json → gateway.auth.token\nToken: 69163b3e56a611a889134579c845c0eee727418a8b3d3f25e6fef704b57f0986\nPurpose: WebSocket gateway authentication\nUsage: Connect to ws://127.0.0.1:18789 with this token in auth header\n```\n\n**Verification Command:**\n```bash\n# Test gateway connection with token\ncurl -H \"Authorization: Bearer 69163b3e56a611a889134579c845c0eee727418a8b3d3f25e6fef704b57f0986\" \\\n http://127.0.0.1:18789/health\n```\n\n#### B. Operator Token (CLI Control)\n```\nLocation: ~/.openclaw/identity/device-auth.json → tokens.operator\nToken: Y3jr-g3km4utCp33k5GIKLGhDBaN3u_5aH3MtAFKQvE\nScopes:\n - operator.admin (full CLI control)\n - operator.approvals (manage approval lists)\n - operator.pairing (device pairing)\nPurpose: CLI automation, remote control, API access\n```\n\n**Verification Command:**\n```bash\n# Test operator token - should return device info\nopenclaw devices list\n```\n\n### 1.2 Floyd Harness Authentication\n\n```\nLocation: /Volumes/Storage/floyd-harness/.env\nBase URL: http://127.0.0.1:8000/v1\nAPI Key (OpenClaw uses): local-harness\n\n⚠️ CRITICAL: Real provider keys exposed in .env file:\n - ZAI_API_KEY=4b678e923c2e48e18f7856fc6feff6b5.RjmxZh9xVbb7LXVH\n - DEEPSEEK_API_KEY=sk-e7ecc670770a402fadc5a0ddf9ffdeaa\n```\n\n**Verification Command:**\n```bash\n# Test Floyd Harness proxy\ncurl http://localhost:8000/admin/health\n# Expected: {\"status\":\"healthy\",\"service\":\"floyd-harness\"}\n```\n\n---\n\n## Phase 2: Configuration Items to Gather\n\n### 2.1 OpenClaw Configuration Files\n\n| File | Location | Purpose | Status |\n|------|----------|---------|--------|\n| **Main Config** | `~/.openclaw/openclaw.json` | Gateway, models, agents | ✅ Present |\n| **Agent Models** | `~/.openclaw/agents/main/agent/models.json` | Model provider configs | ✅ Present |\n| **Auth Profiles** | `~/.openclaw/agents/main/agent/auth-profiles.json` | OAuth tokens per provider | ✅ Present |\n| **Device Auth** | `~/.openclaw/identity/device-auth.json` | Operator tokens | ✅ Present |\n| **Sessions** | `~/.openclaw/agents/main/sessions/sessions.json` | Active session state | ✅ Present |\n| **Credentials** | `~/.openclaw/credentials/` | Channel credentials (WhatsApp, etc.) | ⚠️ Empty, 755 permissions |\n\n**Gather Command:**\n```bash\n# Backup all OpenClaw configs\ntar -czf ~/openclaw-config-backup-$(date +%Y%m%d).tar.gz \\\n -C ~ .openclaw/openclaw.json \\\n -C ~ .openclaw/agents/main/agent/ \\\n -C ~ .openclaw/identity/ \\\n -C ~ .openclaw/credentials/\n```\n\n### 2.2 Floyd Harness Configuration\n\n| File | Location | Purpose | Status |\n|------|----------|---------|--------|\n| **Environment** | `/Volumes/Storage/floyd-harness/.env` | API keys, settings | ✅ Present |\n| **Config Template** | `/Volumes/Storage/floyd-harness/.env.template` | Configuration template | ✅ Present |\n| **Main App** | `/Volumes/Storage/floyd-harness/app/main.py` | FastAPI application | ✅ Present |\n| **Logs** | `/Volumes/Storage/floyd-harness/logs/` | Usage logs, SQLite DB | ✅ Present |\n\n**Gather Command:**\n```bash\n# Backup Floyd Harness configs (sanitize API keys first!)\ncd /Volumes/Storage/floyd-harness\ncp .env .env.backup\nsed -i '' 's/API_KEY=.*/API_KEY=REDACTED/g' .env.backup\ntar -czf ~/floyd-harness-backup-$(date +%Y%m%d).tar.gz \\\n .env.template README.md app/\n```\n\n### 2.3 System Integration Points\n\n| Item | Current Value | Needed For |\n|------|---------------|------------|\n| **Node Version** | 25.6.1 | OpenClaw runtime |\n| **Python Version** | 3.9 (system) | Floyd Harness |\n| **Gateway Port** | 18789 | WebSocket connections |\n| **Dashboard URL** | http://127.0.0.1:18789/ | Control UI |\n| **Floyd Proxy Port** | 8000 | OpenAI-compatible API |\n\n---\n\n## Phase 3: Security Audit & Fixes\n\n### 3.1 Critical Security Issues\n\n#### 🔴 ISSUE 1: Credentials Directory World-Readable\n```\nCurrent: /Users/douglastalley/.openclaw/credentials (mode 755)\nRisk: Other users can read channel credentials\nFix: chmod 700 /Users/douglastalley/.openclaw/credentials\n```\n\n**Fix Command:**\n```bash\nchmod 700 ~/.openclaw/credentials\nls -la ~/.openclaw/ | grep credentials\n# Should show: drwx------ (700)\n```\n\n#### 🔴 ISSUE 2: API Keys Exposed in Plain Text\n```\nLocation: /Volumes/Storage/floyd-harness/.env\nRisk: Git history, file system access exposes real keys\nKeys Exposed:\n - Z.ai API key (GLM-5 access)\n - DeepSeek API key (fallback provider)\n```\n\n**Fix Strategy:**\n1. **Rotate Keys Immediately** (generate new keys from provider dashboards)\n2. **Use Environment Variables** (never commit .env to git)\n3. **Add to .gitignore**:\n ```bash\n echo \".env\" >> /Volumes/Storage/floyd-harness/.gitignore\n echo \"*.key\" >> /Volumes/Storage/floyd-harness/.gitignore\n ```\n4. **Use Secret Management**:\n ```bash\n # Option A: macOS Keychain\n security add-generic-password -a \"zai-api\" -s \"floyd-harness\" -w \"YOUR_KEY\"\n\n # Option B: Environment variable in shell profile\n echo 'export ZAI_API_KEY=\"your_key_here\"' >> ~/.zshrc\n ```\n\n#### ⚠️ ISSUE 3: Reverse Proxy Headers Not Trusted\n```\nCurrent: gateway.trustedProxies = empty\nRisk: If you expose dashboard through reverse proxy, auth could be bypassed\nFix: Only needed if using nginx/cloudflared tunnel\n```\n\n**Fix Command (if using reverse proxy):**\n```bash\n# Example for nginx on same machine\nopenclaw config set gateway.trustedProxies '[\"127.0.0.1\"]'\n```\n\n### 3.2 Security Best Practices Checklist\n\n- [ ] Rotate Z.ai API key\n- [ ] Rotate DeepSeek API key\n- [ ] Add `.env` to `.gitignore`\n- [ ] Fix credentials directory permissions (`chmod 700`)\n- [ ] Verify `.env` not in git history (`git log --all -- .env`)\n- [ ] If committed, use BFG Repo-Cleaner to remove from history\n- [ ] Consider using environment variables instead of `.env` file\n- [ ] Enable 2FA on Z.ai and DeepSeek accounts\n- [ ] Set up API key usage alerts with providers\n\n---\n\n## Phase 4: OpenClaw Setup Checklist\n\n### 4.1 Core Setup (REQUIRED)\n\n- [ ] **Verify Gateway Health**\n ```bash\n openclaw status\n openclaw health\n ```\n\n- [ ] **Test Floyd Harness Connection**\n ```bash\n curl http://localhost:8000/admin/health\n curl http://localhost:8000/v1/models\n ```\n\n- [ ] **Test OpenClaw → Floyd Connection**\n ```bash\n # Should show floyd-harness/glm-5 as configured\n openclaw models status\n ```\n\n- [ ] **Fix Security Issues** (see Phase 3.1)\n ```bash\n chmod 700 ~/.openclaw/credentials\n ```\n\n- [ ] **Enable Memory Plugin** (currently unavailable)\n ```bash\n openclaw plugins list\n openclaw plugins enable memory-core # or install if needed\n ```\n\n### 4.2 Channel Setup (OPTIONAL - based on use case)\n\nDecide which channels you need:\n\n- [ ] **Discord Bot**\n - Requires: Discord Bot Token, Application ID\n - Command: `openclaw channels login discord --verbose`\n\n- [ ] **Telegram Bot**\n - Requires: Telegram Bot Token (from @BotFather)\n - Command: `openclaw channels login telegram --verbose`\n\n- [ ] **Slack App**\n - Requires: Slack App OAuth tokens, Signing Secret\n - Command: `openclaw channels login slack --verbose`\n\n- [ ] **WhatsApp Web**\n - Requires: QR code scan from phone\n - Command: `openclaw channels login whatsapp --verbose`\n\n### 4.3 Service Setup (RECOMMENDED)\n\n- [ ] **Install Gateway as LaunchAgent** (auto-start on boot)\n ```bash\n openclaw gateway install\n # Creates: ~/Library/LaunchAgents/com.openclaw.gateway.plist\n ```\n\n- [ ] **Install Node Service as LaunchAgent**\n ```bash\n openclaw node install\n ```\n\n### 4.4 Advanced Configuration (OPTIONAL)\n\n- [ ] **Configure Fallback Models**\n ```bash\n openclaw models fallbacks add floyd-harness/deepseek-chat\n ```\n\n- [ ] **Set Up Remote Access** (Tailscale)\n ```bash\n openclaw config set tailscale.enabled true\n openclaw config set gateway.mode \"tailscale\"\n ```\n\n- [ ] **Configure Memory Backend**\n ```bash\n openclaw memory configure --backend sqlite # or redis, etc.\n ```\n\n- [ ] **Set Up Webhooks**\n ```bash\n openclaw webhooks add https://your-server.com/webhook\n ```\n\n---\n\n## Phase 5: API Access for Programmatic Control\n\n### 5.1 Using Operator Token for API Calls\n\n```bash\n# Example: Get all configured channels\ncurl -H \"Authorization: Bearer Y3jr-g3km4utCp33k5GIKLGhDBaN3u_5aH3MtAFKQvE\" \\\n http://127.0.0.1:18789/api/channels\n\n# Example: Send a message\ncurl -X POST \\\n -H \"Authorization: Bearer Y3jr-g3km4utCp33k5GIKLGhDBaN3u_5aH3MtAFKQvE\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"channel\":\"discord\",\"target\":\"#general\",\"message\":\"Hello from API!\"}' \\\n http://127.0.0.1:18789/api/message/send\n```\n\n### 5.2 WebSocket Connection (Real-time Control)\n\n```javascript\n// Example Node.js script\nconst WebSocket = require('ws');\n\nconst ws = new WebSocket('ws://127.0.0.1:18789', {\n headers: {\n 'Authorization': 'Bearer 69163b3e56a611a889134579c845c0eee727418a8b3d3f25e6fef704b57f0986'\n }\n});\n\nws.on('open', () => {\n console.log('Connected to OpenClaw gateway');\n\n // Subscribe to events\n ws.send(JSON.stringify({\n type: 'subscribe',\n events: ['message', 'agent_response']\n }));\n});\n\nws.on('message', (data) => {\n console.log('Received:', JSON.parse(data));\n});\n```\n\n### 5.3 CLI Automation Examples\n\n```bash\n# Script: Check all systems health\n#!/bin/bash\necho \"=== OpenClaw Health ===\"\nopenclaw health\n\necho -e \"\\n=== Floyd Harness Health ===\"\ncurl -s http://localhost:8000/admin/health | jq\n\necho -e \"\\n=== Model Status ===\"\nopenclaw models status\n\necho -e \"\\n=== Active Sessions ===\"\nopenclaw sessions list\n\n# Script: Rotate tokens (requires operator.admin scope)\n#!/bin/bash\nopenclaw devices rotate-token operator\n# New token will be printed - save it!\n```\n\n---\n\n## Phase 6: Integration Verification\n\n### 6.1 End-to-End Test\n\nRun this test to verify the full stack:\n\n```bash\n#!/bin/bash\n# File: /Volumes/Storage/openclaw/verify-stack.sh\n\nset -e\n\necho \"1. Checking OpenClaw Gateway...\"\nopenclaw health | grep -q \"healthy\" && echo \"✅ Gateway healthy\"\n\necho \"2. Checking Floyd Harness...\"\ncurl -s http://localhost:8000/admin/health | grep -q \"healthy\" && echo \"✅ Floyd Harness healthy\"\n\necho \"3. Checking Model Configuration...\"\nopenclaw models status | grep -q \"floyd-harness/glm-5\" && echo \"✅ GLM-5 configured\"\n\necho \"4. Testing Model Connection...\"\nRESPONSE=$(curl -s -X POST http://localhost:8000/v1/chat/completions \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"glm-5\",\"messages\":[{\"role\":\"user\",\"content\":\"test\"}]}')\necho \"$RESPONSE\" | grep -q \"choices\" && echo \"✅ Model responds\"\n\necho \"5. Checking Security...\"\nls -la ~/.openclaw/credentials | grep -q \"drwx------\" && echo \"✅ Credentials secured\"\n\necho -e \"\\n🎉 All systems operational!\"\n```\n\n**Run it:**\n```bash\nchmod +x /Volumes/Storage/openclaw/verify-stack.sh\n./verify-stack.sh\n```\n\n### 6.2 Load Test (Optional)\n\n```bash\n# Test concurrent requests through Floyd Harness\nab -n 100 -c 10 -p payload.json -T application/json \\\n http://localhost:8000/v1/chat/completions\n\n# Where payload.json contains:\n# {\"model\":\"glm-5\",\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}\n```\n\n---\n\n## Phase 7: Monitoring & Observability\n\n### 7.1 OpenClaw Monitoring\n\n```bash\n# Real-time logs\nopenclaw logs --follow\n\n# Status dashboard\nopenclaw status --all\n\n# Security audit\nopenclaw security audit --deep\n```\n\n### 7.2 Floyd Harness Monitoring\n\n```bash\n# Usage statistics (last 24 hours)\ncurl http://localhost:8000/admin/stats?hours=24 | jq\n\n# Cache performance\ncurl http://localhost:8000/admin/stats/cache | jq\n\n# All registered MCP tools\ncurl http://localhost:8000/admin/tools | jq\n\n# Current configuration (sanitized)\ncurl http://localhost:8000/admin/config | jq\n```\n\n### 7.3 Log Locations\n\n| Component | Log Location | Rotation |\n|-----------|--------------|----------|\n| OpenClaw Gateway | `~/.openclaw/logs/gateway.log` | Auto (10MB) |\n| OpenClaw Agent | `~/.openclaw/agents/main/logs/` | Auto |\n| Floyd Harness | `/Volumes/Storage/floyd-harness/logs/floyd-harness.log` | 10MB, 7 days |\n| Floyd Usage DB | `/Volumes/Storage/floyd-harness/logs/usage.db` | Manual |\n\n---\n\n## Phase 8: Disaster Recovery\n\n### 8.1 Backup Strategy\n\n**Daily Backup Script:**\n```bash\n#!/bin/bash\n# File: /Volumes/Storage/openclaw/backup-daily.sh\n\nBACKUP_DIR=\"/Volumes/Storage/openclaw/backups\"\nDATE=$(date +%Y%m%d)\n\nmkdir -p \"$BACKUP_DIR\"\n\n# OpenClaw configs\ntar -czf \"$BACKUP_DIR/openclaw-$DATE.tar.gz\" -C ~ .openclaw/\n\n# Floyd Harness configs (without API keys)\ncd /Volumes/Storage/floyd-harness\ntar -czf \"$BACKUP_DIR/floyd-harness-$DATE.tar.gz\" \\\n --exclude='.env' \\\n --exclude='*.db' \\\n --exclude='logs/*.log' \\\n app/ README.md .env.template requirements.txt\n\n# Keep only last 7 days\nfind \"$BACKUP_DIR\" -name \"*.tar.gz\" -mtime +7 -delete\n\necho \"Backup complete: $BACKUP_DIR\"\n```\n\n**Automate with cron:**\n```bash\n# Run daily at 2 AM\ncrontab -e\n# Add: 0 2 * * * /Volumes/Storage/openclaw/backup-daily.sh\n```\n\n### 8.2 Recovery Procedure\n\n```bash\n# If OpenClaw config is corrupted:\ncd ~\nrm -rf .openclaw\ntar -xzf /Volumes/Storage/openclaw/backups/openclaw-YYYYMMDD.tar.gz\n\n# If Floyd Harness needs rebuild:\ncd /Volumes/Storage/floyd-harness\n./run.sh # Reinstalls venv and dependencies\n\n# If API keys compromised:\n# 1. Generate new keys from provider dashboards\n# 2. Update .env file\n# 3. Restart Floyd Harness: pkill -f uvicorn && ./run.sh\n```\n\n---\n\n## Phase 9: Next Steps\n\n### Immediate Actions (Today)\n\n1. **Fix Security Issues**\n - [ ] `chmod 700 ~/.openclaw/credentials`\n - [ ] Rotate Z.ai API key\n - [ ] Rotate DeepSeek API key\n - [ ] Add `.env` to `.gitignore`\n\n2. **Verify Integration**\n - [ ] Run `verify-stack.sh` script\n - [ ] Test with simple prompt through OpenClaw\n\n3. **Enable Services**\n - [ ] `openclaw gateway install` (auto-start on boot)\n - [ ] `openclaw node install`\n\n### Short-term (This Week)\n\n4. **Configure Channels** (as needed)\n - [ ] Discord bot setup\n - [ ] Telegram bot setup\n - [ ] WhatsApp Web pairing\n\n5. **Enable Memory**\n - [ ] Investigate why memory plugin is unavailable\n - [ ] Install/configure memory backend\n\n6. **Set Up Monitoring**\n - [ ] Create monitoring dashboard script\n - [ ] Configure log rotation\n\n### Long-term (This Month)\n\n7. **Advanced Features**\n - [ ] Configure fallback models\n - [ ] Set up remote access (Tailscale)\n - [ ] Create custom MCP tools for Floyd Harness\n - [ ] Integrate with CI/CD pipelines\n\n8. **Documentation**\n - [ ] Document your specific use cases\n - [ ] Create runbooks for common operations\n - [ ] Set up alerting for failures\n\n---\n\n## Appendix A: Quick Reference Commands\n\n```bash\n# OpenClaw Status\nopenclaw status # Basic status\nopenclaw status --all # Detailed status\nopenclaw health # Health check\nopenclaw logs --follow # Real-time logs\n\n# Model Management\nopenclaw models status # Show configured models\nopenclaw models list # List available models\nopenclaw models set floyd-harness/glm-5 # Set primary model\n\n# Channel Management\nopenclaw channels login discord # Login to Discord\nopenclaw channels list # List all channels\nopenclaw status --deep # Deep channel status\n\n# Configuration\nopenclaw config get models.providers.floyd-harness.baseUrl # Get config\nopenclaw config set gateway.port 18789 # Set config\n\n# Security\nopenclaw security audit # Basic audit\nopenclaw security audit --deep # Deep audit\nchmod 700 ~/.openclaw/credentials # Fix permissions\n\n# Services\nopenclaw gateway install # Install LaunchAgent\nopenclaw gateway start # Start gateway\nopenclaw gateway stop # Stop gateway\nopenclaw gateway restart # Restart gateway\n\n# Tokens\nopenclaw devices list # List paired devices\nopenclaw devices rotate-token operator # Rotate operator token\n\n# Floyd Harness\ncurl http://localhost:8000/admin/health # Health check\ncurl http://localhost:8000/admin/stats?hours=24 # Usage stats\ncurl http://localhost:8000/admin/tools # MCP tools\n```\n\n---\n\n## Appendix B: File Locations Summary\n\n```\nOpenClaw Binary: /opt/homebrew/bin/openclaw\nOpenClaw Config: ~/.openclaw/openclaw.json\nOpenClaw Models: ~/.openclaw/agents/main/agent/models.json\nOpenClaw Auth: ~/.openclaw/identity/device-auth.json\nOpenClaw Credentials: ~/.openclaw/credentials/\nOpenClaw Logs: ~/.openclaw/logs/\n\nFloyd Harness: /Volumes/Storage/floyd-harness/\nFloyd Config: /Volumes/Storage/floyd-harness/.env\nFloyd Logs: /Volumes/Storage/floyd-harness/logs/\n\nGateway URL: ws://127.0.0.1:18789\nDashboard URL: http://127.0.0.1:18789/\nFloyd Proxy URL: http://127.0.0.1:8000/v1\n```\n\n---\n\n## Appendix C: Token/Key Inventory\n\n| Token/Key | Location | Scope | Status | Action Needed |\n|-----------|----------|-------|--------|---------------|\n| Gateway Auth Token | `~/.openclaw/openclaw.json` | Gateway WebSocket | ✅ Active | None |\n| Operator Token | `~/.openclaw/identity/device-auth.json` | CLI Admin | ✅ Active | None |\n| Z.ai API Key | `floyd-harness/.env` | GLM-5 Access | ⚠️ Exposed | **ROTATE** |\n| DeepSeek API Key | `floyd-harness/.env` | Fallback Provider | ⚠️ Exposed | **ROTATE** |\n\n---\n\n**Document Status:** ✅ Complete\n**Next Review:** After security fixes and channel setup\n**Maintained By:** Claude (OpenClaw Operations Expert)\n\n---\n\n## Evidence Sources\n\n- OpenClaw Configuration: `~/.openclaw/openclaw.json` (observed)\n- OpenClaw Status: `openclaw status` command output (observed)\n- Floyd Harness Health: `curl http://localhost:8000/admin/health` (observed)\n- Floyd Harness Config: `/Volumes/Storage/floyd-harness/.env` (observed)\n- OpenClaw CLI Help: `openclaw --help`, `openclaw models --help` (observed)\n- OpenClaw Docs: https://docs.openclaw.ai/ (referenced)\n- Floyd Harness README: `/Volumes/Storage/floyd-harness/README.md` (observed)\n"}}}} |