Skip to main content

​
Overview

Evolver is designed to be environment-agnostic and integrates with existing systems through:
  1. Local overrides (environment variables)
  2. Custom reporting directives
  3. Platform-agnostic tool calls
  4. Git-based workflow

​
Platform-Agnostic Design

Evolver uses standard OpenClaw tools by default but allows workspace-specific customization.

​
Default Behavior

Reports use the generic message tool: 
// src/evolve.js:826-830
let reportingDirective = `Report requirement:
  - Use \`message\` tool.
  - Title: Evolution ${cycleId}
  - Status: [SUCCESS]
  - Changes: Detail exactly what was improved.`;

​
Custom Tool Injection

Override the reporting tool via environment variables: 
EVOLVE_REPORT_TOOL=feishu-card
Location: README.md:232-239, SKILL.md:88-96

​
Integration Methods

​
Method 1: Environment Variables

Set reporting preferences in .env: 
# Use custom reporting tool
EVOLVE_REPORT_TOOL=feishu-card

# Custom report command template
EVOLVE_REPORT_CMD='feishu-card --title "Evolution __CYCLE_ID__" --status "$STATUS"'

# Custom integration health check
INTEGRATION_STATUS_CMD='curl -s http://localhost:9200/_cluster/health'

​
Method 2: Dynamic Detection

Evolver auto-detects compatible local skills: 
// src/evolve.js:853-925
const skillsDir = path.join(REPO_ROOT, 'skills');

if (fs.existsSync(path.join(skillsDir, 'feishu-card'))) {
  // Upgrade reporting to use feishu-card
}
Example directory structure: 
workspace/
├── skills/
│   ├── feishu-card/       ← Auto-detected
│   ├── feishu-post/       ← Auto-detected
│   └── evolver/
└── ...
Evolver detects feishu-card and automatically uses it for richer reporting.

​
Method 3: Custom Reporting Directive

Inject a full reporting directive template: 
EVOLVE_REPORT_DIRECTIVE='Use feishu-card tool with:
  - Title: Evolution __CYCLE_ID__
  - Status: [SUCCESS/FAILED]
  - Fields: {"changed_files": blast.files, "lines": blast.lines}
  - Color: green for success, red for failure'
The __CYCLE_ID__ placeholder is replaced with the current cycle number. Location: src/evolve.js:835-843

​
Git Integration

Evolver requires a git repository for:
  • Rollback on failure
  • Blast radius calculation
  • Diff capture
  • Change tracking

​
Validation

At startup, evolver checks for git: 
// src/evolve.js:752-762
try {
  execSync('git rev-parse --git-dir', { cwd: REPO_ROOT });
} catch (_) {
  console.error('[Evolver] FATAL: Not a git repository.');
  process.exitCode = 1;
  return;
}

​
Initialize Git

If running in a non-git directory: 
git init
git add -A
git commit -m "Initial commit for Evolver"

​
External Systems Integration

​
Health Check Integration

Monitor external systems via INTEGRATION_STATUS_CMD: 
# Elasticsearch
INTEGRATION_STATUS_CMD='curl -s http://localhost:9200/_cluster/health | jq -r .status'

# Redis
INTEGRATION_STATUS_CMD='redis-cli ping'

# Custom service
INTEGRATION_STATUS_CMD='node scripts/health-check.js'
Evolver runs this command during system health checks and includes output in observations. Location: src/evolve.js:311-321

​
Cron / External Runner Integration

Run evolver periodically via cron: 
# Cron entry (every 6 hours)
0 */6 * * * bash -lc 'cd /path/to/workspace/skills/evolver && node index.js --loop'
Avoid composing multiple shell segments inside cron payloads. Nested quotes break after passing through serialization/escaping layers.
Recommended: Single simple command with minimal quoting. Location: README.md:133-142

​
Process Manager Integration

Using pm2: 
pm2 start "bash -lc 'node index.js --loop'" \
  --name evolver \
  --cron-restart="0 */6 * * *"
Location: README.md:143-147

​
Workspace Wrappers

Custom wrappers can inject platform-specific behavior without modifying evolver core.

​
Example: Feishu Wrapper

// skills/feishu-evolver-wrapper/wrapper.js

// Set custom reporting before launching evolver
process.env.EVOLVE_REPORT_DIRECTIVE = `
Use feishu-card tool:
  - Title: "Evolution __CYCLE_ID__"
  - Status: ${status}
  - Content: ${summary}
`;

// Launch evolver
const evolver = require('../evolver/index.js');
Benefits:
  • Core evolver remains platform-agnostic
  • Wrappers add platform-specific features
  • Easy to version and distribute

​
Operations Module

Evolver includes a portable lifecycle module in src/ops/: 
node src/ops/lifecycle.js start    # Start evolver loop in background
node src/ops/lifecycle.js stop     # Graceful stop (SIGTERM → SIGKILL)
node src/ops/lifecycle.js status   # Show running state
node src/ops/lifecycle.js check    # Health check + auto-restart if stagnant
Location: README.md:124-130 Features:
  • Zero platform dependency
  • Skill monitoring
  • Cleanup on stop
  • Self-repair triggers
  • Wake triggers

​
Custom Validation Commands

Genes can specify validation commands: 
{
  "type": "Gene",
  "id": "gene_custom_validation",
  "validation": [
    "npm test",
    "node scripts/custom-check.js"
  ]
}
Validation commands are restricted to node, npm, npx prefixes for safety.
See: Validation Safety

​
A2A External Asset Ingestion

Evolver can ingest external Genes/Capsules from the EvoMap network: 
# Ingest external assets
node scripts/a2a_ingest.js --source https://evomap.ai/api/assets

# Promote to local store (requires validation)
node scripts/a2a_promote.js --id gene_external_123 --validated
Location: README.md:212-218 Safety:
  • External assets are staged in an isolated candidate zone
  • Promotion requires explicit --validated flag
  • Unsafe validation commands cause rejection
  • Never overwrites existing local genes

​
Worker Pool Integration

Enable worker pool mode to participate in the EvoMap network task queue: 
WORKER_ENABLED=1 \
WORKER_DOMAINS=repair,harden \
WORKER_MAX_LOAD=3 \
node index.js --loop
Location: README.md:253-265 How it works:
  1. Heartbeat advertises capabilities to hub
  2. Hub assigns tasks from available-work queue
  3. Worker claims task atomically during solidify
  4. Result published back to hub
See: Environment Variables

​
Local Overrides Best Practices

​
1. Environment-Specific Config

Maintain separate .env files: 
# .env.dev
EVOLVE_STRATEGY=innovate
EVOLVER_SESSION_SCOPE=dev

# .env.prod
EVOLVE_STRATEGY=harden
EVOLVER_SESSION_SCOPE=prod
EVOLVE_ALLOW_SELF_MODIFY=false
Load via: 
set -a; source .env.prod; set +a
node index.js --loop

​
2. Wrapper Convention

Place wrappers in skills/<platform>-evolver-wrapper/: 
workspace/skills/
├── feishu-evolver-wrapper/
├── slack-evolver-wrapper/
├── discord-evolver-wrapper/
└── evolver/  (core)

​
3. Version Pinning

Pin evolver version in wrapper’s package.json: 
{
  "dependencies": {
    "evolver": "1.0.41"
  }
}

​
Troubleshooting

​
Custom reporting tool not found

Symptom: Evolver falls back to message tool. Cause: Tool not detected in skills/ directory. Solution: Verify tool exists and has package.json or SKILL.md: 
ls -la skills/feishu-card/

​
Health check command fails

Symptom: Integration status shows “Integrations: Nominal” despite external failures. Cause: INTEGRATION_STATUS_CMD timeout (2 seconds). Solution: Ensure health check command completes quickly: 
# Bad (slow)
INTEGRATION_STATUS_CMD='npm run full-test'

# Good (fast)
INTEGRATION_STATUS_CMD='curl -s --max-time 1 http://localhost:9200/_cluster/health'

​
Git requirement blocks deployment

Symptom: FATAL: Not a git repository error. Solution: Initialize git in workspace root: 
cd /path/to/workspace
git init
git add -A
git commit -m "Init for Evolver"

Build docs developers (and LLMs) love

Get started for freeTalk to us