OpenFang / OpenClaw Integration

🤖 OpenFang / OpenClaw Integration

Thông tin nhanh

OpenFang: Nền tảng agent tự động hóa — chạy theo schedule (cron), có guardrails

OpenClaw: Agent runtime — chạy on-demand, interactive

HAND config: openfang-hand/HAND.toml — định nghĩa agent behavior

Skills: 3 CRM skills trong skills/ — dạy agent cách dùng CRM tools

Xem thêm: MCP Server · Agent API · Agent Tokens

Tổng quan

graph TB
    style OF fill:#2d333b,stroke:#d2a8ff,color:#e6edf3
    style HAND fill:#2d333b,stroke:#f0883e,color:#e6edf3
    style SKILLS fill:#2d333b,stroke:#6d5dfc,color:#e6edf3
    style MCP fill:#2d333b,stroke:#3fb950,color:#e6edf3

    OF["🤖 OpenFang Platform"]
    HAND["📋 HAND Config<br/>(schedule, tools, guardrails)"]
    SKILLS["📚 CRM Skills<br/>(operations, outreach, analytics)"]
    MCP["🔌 MCP Server<br/>(7 CRM tools)"]

    OF --> HAND
    HAND --> SKILLS
    HAND --> MCP

Mô tả: OpenFang chạy HAND config theo schedule → HAND chỉ định tools cần dùng (qua MCP) và skills (hướng dẫn agent). Agent đọc skills → quyết định hành động → gọi tools → CRM API xử lý.

HAND Configuration

File openfang-hand/HAND.toml định nghĩa:

[hand]
name = "crm-lead-gen"
version = "1.0.0"
description = "Autonomous CRM lead management"

[hand.schedule]
cron = "*/30 8-18 * * 1-6"       # Mỗi 30 phút, 8h-18h, T2-T7
timezone = "Asia/Ho_Chi_Minh"

[hand.settings]
crm_base_url = "https://api.salehay.com"
agent_token_secret = "CRM_AGENT_TOKEN"  # Secret name (not value!)
max_calls_per_run = 10
max_messages_per_run = 20
priority_focus = "high"

[hand.tools]
required = [
  "crm_create_lead", "crm_search", "crm_log_call",
  "crm_get_bookings", "crm_send_message",
  "crm_get_analytics", "crm_update_lead"
]

[hand.skills]
required = ["crm-operations", "crm-outreach", "crm-analytics"]

[hand.guardrails]
approval_required = ["crm_send_message"]   # Cần approval trước khi gửi tin
max_tool_calls = 50                        # Max API calls per run

[hand.dashboard]
metrics = [
  { name = "Leads Contacted", query = "crm_log_call.count" },
  { name = "Messages Sent", query = "crm_send_message.count" },
  { name = "New Leads Found", query = "crm_create_lead.count" },
]

Các thành phần HAND

Section	Mô tả
`schedule`	Cron expression + timezone — khi nào agent chạy
`settings`	Config (URL, token secret, giới hạn per-run)
`tools`	Danh sách MCP tools agent được dùng
`skills`	Danh sách skills agent cần đọc để hiểu context
`guardrails`	An toàn: approval trước khi dùng tool nhạy cảm, giới hạn max calls
`dashboard`	Metrics hiển thị trên OpenFang dashboard
`system_prompt`	System prompt hướng dẫn agent behavior

System Prompt

HAND.toml chứa system prompt dạy agent quy trình 4 phase:

Assessment: Gọi crm_get_analytics → đánh giá pipeline health
Outreach: Gọi hot leads → crm_log_call + crm_send_message
Booking Management: crm_get_bookings → gửi reminders
Reporting: Tóm tắt actions, flag leads cần human attention

Rules (trong System Prompt)

Không gọi 1 lead quá 3 lần/ngày
Luôn log outcomes (kể cả unsuccessful)
Dùng tiếng Việt trong tin nhắn khách hàng
Tôn trọng giờ làm việc (8-18h, T2-T7)
Escalate tới human nếu khách giận dữ/đe dọa

CRM Skills

3 skills nằm trong skills/, mỗi skill có SKILL.md chứa hướng dẫn:

1. crm-operations

File: skills/crm-operations/SKILL.md

Dạy agent CRUD operations cơ bản:

Tạo lead (crm_create_lead)
Tìm kiếm (crm_search)
Cập nhật lead (crm_update_lead)
Xem bookings (crm_get_bookings)
Xem analytics (crm_get_analytics)
Lead status flow: new → contacted → appointment_set → showed_up → converted
Best practices: search trước khi tạo để tránh duplicate

2. crm-outreach

File: skills/crm-outreach/SKILL.md

Dạy agent customer outreach:

Log cuộc gọi (crm_log_call)
Gửi tin nhắn (crm_send_message)
Workflow 1: New Lead Follow-up (search → call → log → update status)
Workflow 2: Booking Reminder (get bookings → remind → confirm)
Workflow 3: Lost Lead Re-engagement (search lost → message → re-activate)
Vietnamese phone etiquette, Zalo best practices
Rate limits: max 5 calls/lead/day, max 3 messages/lead/day

3. crm-analytics

File: skills/crm-analytics/SKILL.md

Dạy agent đọc và phân tích data:

Response structure từ crm_get_analytics
Prioritization matrix (nhiều leads mới → ưu tiên outreach)
Daily routine (analytics → hot leads → bookings → follow-up)
Lead scoring heuristic (Hot/Warm/Cold)
Target metrics: Contact Rate >60%, Show-up >70%, Conversion >25%

Setup Guide

Bước 1: Tạo Agent Token

Trong Admin Dashboard → Settings → Agent Tokens → Tạo mới:

Name: “OpenFang Sales Agent”
Type: openfang
Scopes: leads:read, leads:write, calls:write, messages:write, analytics:read, bookings:read
Rate Limit: 60
Lưu token ngay khi tạo (chỉ hiển thị 1 lần)

Bước 2: Cài MCP Server

cd mcp-server
npm install

Bước 3: Cấu hình OpenFang

# Set token qua secret manager
openfang secret set CRM_AGENT_TOKEN agent_abc123...

# Copy HAND config
cp openfang-hand/HAND.toml ~/.openfang/hands/crm-lead-gen/HAND.toml

# Copy skills
cp -r skills/crm-operations ~/.openfang/skills/
cp -r skills/crm-outreach ~/.openfang/skills/
cp -r skills/crm-analytics ~/.openfang/skills/

Bước 4: Kiểm tra

# Test MCP Server
CRM_AGENT_TOKEN=agent_xxx node mcp-server/index.js
# Expect: "SaleHay CRM MCP Server running on stdio"

# Test Agent API
curl -H "X-Agent-Token: agent_xxx" https://api.salehay.com/api/agent/analytics
# Expect: JSON response với pipeline data

Cấu hình cho OpenClaw

Thay vì HAND.toml, OpenClaw dùng JSON config:

{
  "mcpServers": {
    "salehay-crm": {
      "command": "node",
      "args": ["/path/to/mcp-server/index.js"],
      "env": {
        "CRM_BASE_URL": "https://api.salehay.com",
        "CRM_AGENT_TOKEN": "agent_xxx"
      }
    }
  }
}

Skills được load tự động nếu nằm trong thư mục ~/.openclaw/skills/.

Troubleshooting

Agent token bị lỗi 401

Kiểm tra token chưa bị thu hồi (is_active = true)
Kiểm tra biến môi trường CRM_AGENT_TOKEN đã set đúng
Kiểm tra token có đủ scopes cho endpoint đang gọi

Rate limit 429

Mặc định 60 req/phút. Nếu agent gọi quá nhiều, tăng rate_limit hoặc giảm frequency.
Rate limit reset mỗi 60 giây.

MCP Server không kết nối được API

Kiểm tra CRM_BASE_URL có trailing slash không (không nên có)
Kiểm tra network — MCP Server cần reach được API URL
Chạy curl -H "X-Agent-Token: xxx" <CRM_BASE_URL>/api/health để test