OpenFang Zero → Hero (Agent Operating System)

Repo gốc: https://github.com/RightNow-AI/openfang
Website/Docs: https://openfang.sh
Mục tiêu tài liệu: đi từ “chạy được trong 15 phút” → “vận hành an toàn + mở rộng + tích hợp hệ thống”.

[!summary] TL;DR

OpenFang là Agent Operating System (không phải chatbot framework): chạy agent tự động theo lịch, có dashboard, có API OpenAI-compatible, có Hands (gói năng lực tự trị) để “làm việc thay bạn”.

Điểm ăn tiền: Hands + Workflows/Triggers (pipeline + event-driven) + Skills (plugin tools) + Channel adapters + MCP/A2A + security defense-in-depth (16 lớp bảo mật).

Quickstart (macOS/Linux): curl -fsSL https://openfang.sh/install | sh → openfang init → openfang doctor → openfang start.

[!note] Snapshot (GitHub)

Tài liệu này dựa trên repo RightNow-AI/openfang (commit 0bb4e6f, snapshot ngày 2026-02-27).

v0.1.0 là bản public đầu (02/2026); nếu chạy production, nên pin commit/tag cho tới v1.0.

“Source of truth” trong repo: docs/README.md, docs/getting-started.md, docs/architecture.md, docs/configuration.md, docs/cli-reference.md, docs/providers.md, docs/channel-adapters.md, docs/workflows.md, docs/mcp-a2a.md, docs/security.md, docs/api-reference.md, MIGRATION.md, CHANGELOG.md.

Lưu ý: openfang.sh/docs hiện hiển thị nhãn v1.0.0 và có thêm một số primitive/lệnh (ví dụ openfang hand ..., openfang channel setup ..., openfang skill install ...) mà snapshot repo/CLI reference có thể chưa phản ánh đầy đủ. Khi làm theo command trong bài: hãy ưu tiên đối chiếu binary thật (openfang --version, openfang --help).

Website coverage (openfang.sh) (crawl ngày 2026-02-27):

Pages đã đọc: /, /download, /docs, /docs/getting-started, /docs/hands, /docs/architecture, /docs/configuration, /docs/security, /docs/providers, /docs/channel-adapters, /docs/agent-templates, /docs/skill-development, /docs/workflows, /docs/mcp-a2a, /docs/api-reference, /docs/cli-reference, /docs/desktop, /docs/troubleshooting.

Installer scripts đã đọc: /install, /install.ps1.

robots.txt/sitemap.xml: 404 tại thời điểm crawl, nên coverage dựa trên link graph trong site.

0) Bạn sẽ có gì sau khi đọc (outcomes)

Sau 60–120 phút thực hành, bạn có thể:

Cài OpenFang, bật dashboard, chat với agent, chạy 1 Hand thật sự tạo output.
Kết nối ít nhất 1 kênh (ví dụ Telegram/Slack) để Hand “báo cáo” tự động.
Chọn 1–2 LLM providers (cloud hoặc local), hiểu cách set key/base URL.
Tạo 1 agent template tối thiểu (manifest TOML) với capability rõ ràng.
Tạo 1 workflow pipeline đơn giản (sequential/fan-out/loop) và 1 trigger event-driven.
Cài/viết 1 skill (prompt_only hoặc python/wasm) và hiểu guardrails của nó.
Hiểu “khung an toàn” của OpenFang và biết cách vận hành không tự bắn vào chân.

1) OpenFang là gì (và không là gì)

1.1 OpenFang là gì

OpenFang là một “hệ điều hành cho agent”:

Có kernel (lập lịch, orchestration, RBAC, policy, budget).
Có runtime (agent loop, tool runner, sandbox, MCP/A2A).
Có memory substrate (SQLite + embeddings/vector, sessions).
Có channels (adapter tới các nền tảng chat/messaging).
Có Hands: các “capability packages” chạy tự trị theo lịch.
Có HTTP API (bao gồm endpoint kiểu OpenAI /v1/chat/completions) và dashboard.

1.2 OpenFang không phải

Không phải “framework để bạn tự ráp prompt + tool bằng tay rồi chat”.
Không phải “wrapper Python xung quanh LLM”.
Không thay bạn ra quyết định về scope/quality. OpenFang mạnh khi bạn đặt deliverable rõ và luồng vận hành có kiểm.

1.3 Mental model (để khỏi học nhầm)

flowchart TD
  U[Bạn] -->|config + keys + policies| K[Kernel<br/>schedule · RBAC · budgets]
  K --> R[Runtime<br/>agent loop · tools · sandbox · MCP/A2A]
  R --> M[Memory<br/>SQLite · sessions · embeddings]
  R --> C[Channels<br/>Telegram/Slack/...]
  R --> H[Hands<br/>7 gói tự trị]
  R --> A[Agents<br/>templates/custom]
  K --> API[HTTP API + Dashboard]

  H -->|reports| C
  A -->|chat / tasks| API
  M --> API

1.4 Những tính năng “hấp dẫn” của OpenFang (đúng kiểu Agent OS)

[!summary] Điểm khác biệt (từ GitHub/docs)

Một binary (~32MB) + đa nền tảng + desktop app (Tauri) + TUI: cảm giác “product” hơn là “framework”.

Hands: agent tự trị chạy theo lịch, có guardrails, có metrics, có lifecycle rõ.

Workflow engine: pipeline multi-agent (sequential/fan-out/loop/conditional) + visual builder.

Channels 40 adapters: đưa agent vào Telegram/Slack/Email/Webhooks… với policy DM/group + rate limit + formatting.

LLM layer: 3 drivers (Anthropic/Gemini/OpenAI-compatible) + model catalog/aliases + fallback + cost tracking.

Memory substrate: SQLite + semantic search/embeddings + canonical sessions cross-channel + compaction (chống token bloat).

Security (16 layers): capability gating, WASM dual-metered sandbox, audit trail Merkle hash-chain, SSRF/path traversal, prompt-injection scanner, loop guard…

Interop: OpenAI-compatible API (/v1/chat/completions), MCP client/server, A2A.

Stability/ops: openfang doctor, session repair + loop guard + tool timeouts, usage/cost tracking, /api/metrics (Prometheus), /api/audit/verify, config hot-reload.

UI/UX: WebChat UI (search, voice input, TTS playback, session switcher, browser screenshot rendering, canvas) + TUI + desktop app.

Migration & ecosystem: openfang migrate --from openclaw, marketplace skills (FangHub) + tương thích ClawHub/OpenClaw SKILL.md, SDKs (JS/Python) cho tích hợp.

[!note] Deep dive từ openfang.sh/#overview (điểm đáng “khoe”)

Positioning: “One binary” + Agent OS chạy nền: Hands chạy theo lịch, build knowledge graphs, report về dashboard.

Numbers (homepage snapshot): 30 agents, 40 channels, 38 tools, 26 LLM providers, 16 security systems; “14 crates, 137K lines, zero clippy warnings”.

Ghi chú: trong các phần khác trên site/docs có thể thấy số khác (ví dụ meta description nói 53 tools / 27 providers; docs providers nói “20 providers”). Hãy coi đây là “moving target”.

Sandboxed execution: tool code chạy trong WASM dual metering (fuel + epoch), file ops “workspace-confined”, subprocess env_clear() + timeout; nhấn mạnh graceful shutdown nhiều phase.

Tools “đáng dùng”: web search, browser automation, image generation, TTS, Docker, knowledge graphs; có MCP client + server.

Memory: SQLite + vector embeddings, canonical sessions cross-channel, auto compaction, và có nhắc “JSONL session mirroring”.

Protocols: MCP + A2A + OFP (P2P) với HMAC-SHA256 mutual auth.

Desktop: Tauri 2.0 app có system tray, notifications, single-instance, auto-start, global shortcuts.

Benchmarks (Feb 2026, theo homepage): cold start ~180ms, idle memory ~40MB, install size ~32MB; kèm bảng compare vs OpenClaw/ZeroClaw/CrewAI/AutoGen/LangGraph.

Homepage có nhắc lệnh kiểu openfang compare --all / openfang search ...; trong snapshot code/docs (commit 0bb4e6f) mình chưa thấy các subcommand này trong docs/cli-reference.md, nên coi như “marketing/roadmap” trừ khi bạn xác nhận binary bạn đang chạy có hỗ trợ.

Lưu ý: các con số có thể lệch theo version/docs; nếu làm tài liệu “vận hành”, ưu tiên đối chiếu CHANGELOG.md + docs/*.

1.5 “Đòn bẩy” để khai thác hiệu quả (chọn đúng primitive)

Nếu bạn muốn “nó tự chạy hằng ngày và báo cáo”: bắt đầu bằng Hand + channel.
Nếu bạn muốn “pipeline nhiều bước có kiểm soát”: dùng workflow (rẻ hơn và dễ debug hơn tự viết Hand).
Nếu bạn cần công cụ mới (DB/CRM/API nội bộ): ưu tiên MCP server hoặc skill (WASM nếu nhạy cảm).
Nếu bạn cần đưa agent vào đời sống team: đầu tư RBAC + channel policies + audit sớm.

1.6 OpenFang vs “agent frameworks” (để khỏi dùng sai bài)

OpenFang hướng tới vận hành “agent chạy nền” như một hệ thống (daemon, dashboard, channels, RBAC, audit, metrics).
Nhiều framework kiểu LangGraph/AutoGen/CrewAI thường mạnh ở “xây graph/flow trong app của bạn”, nhưng bạn vẫn phải tự lo phần vận hành (scheduling, channels, RBAC, audit, packaging).
Nếu bạn cần “drop-in infrastructure” cho agent (đặc biệt là always-on + multi-channel + hardening): OpenFang hợp.
Nếu bạn chỉ cần “library để embed vào codebase Python/TS” và bạn đã có infra: dùng framework có thể nhẹ hơn.

2) Quickstart (15 phút) — chạy được việc ngay

[!important] Mục tiêu quickstart Không “cài xong để đó”. Bạn phải thấy: dashboard chạy, 1 Hand chạy, và có output.

2.1 Prereqs tối thiểu

OS: macOS 12+, Linux (glibc 2.17+), Windows 10+
Architecture: x86_64 hoặc ARM64
Disk: ~50 MB
Ít nhất 1 LLM provider: cloud key (Anthropic/OpenAI/Gemini/...) hoặc local (Ollama/vLLM/LM Studio)

2.2 Cài đặt + khởi tạo

macOS/Linux:

# Installer (macOS/Linux)
curl -fsSL https://openfang.sh/install | sh
# Mirror (theo docs CLI, tuỳ thời điểm có thể dùng domain này):
# curl -fsSL https://get.openfang.ai | sh
openfang --version
openfang init

Windows (PowerShell):

irm https://openfang.sh/install.ps1 | iex
openfang init

Tuỳ chọn khác (khi bạn cần):

Desktop app (Tauri): tải từ GitHub Releases.
Docker: chạy image ghcr.io/RightNow-AI/openfang:latest hoặc docker compose up -d trong repo.
Cargo: cargo install --git https://github.com/RightNow-AI/openfang openfang-cli.

[!example] Docker quick run (từ openfang.sh/docs/getting-started)

docker pull ghcr.io/RightNow-AI/openfang:latest
docker run -d \
  --name openfang \
  -p 4200:4200 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v openfang-data:/data \
  ghcr.io/RightNow-AI/openfang:latest

[!note] OpenFang home (paths quan trọng) openfang init tạo ~/.openfang/config.toml và ~/.openfang/data/ (SQLite).

[!note] openfang.sh/install thực sự làm gì? (deep dive script cài đặt)

Detect OS/arch (uname -s, uname -m) → chọn target triple (Linux/macOS x86_64/arm64).

Download GitHub Releases latest (RightNow-AI/openfang) dạng openfang-<target>.tar.gz (Windows: .zip).

Extract và copy binary vào ~/.openfang/bin/openfang (Windows: %USERPROFILE%\\.openfang\\bin\\openfang.exe), rồi chmod +x.

Tự thêm ~/.openfang/bin vào PATH bằng cách append vào profile (.zshrc / .bashrc / .bash_profile / fish config / .profile); Windows add vào User PATH.

Nếu muốn tải thủ công theo kiến trúc/OS, dùng trang: https://openfang.sh/download

[!tip] Secrets config.toml nên chỉ trỏ tới env var names (api_key_env, bot_token_env, …), tránh nhét key trực tiếp vào file.

2.3 Set keys / base URLs (chọn 1 đường)

Cloud providers (ví dụ):

ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY…

Local providers:

OLLAMA_BASE_URL (thường http://localhost:11434)
VLLM_BASE_URL (thường http://localhost:8000)
LMSTUDIO_BASE_URL (thường http://localhost:1234)

[!tip] Cách ít đau nhất Bắt đầu bằng 1 provider “dễ chạy”, sau đó mới mở rộng routing/fallback.

2.4 Verify nhanh (doctor/status)

openfang doctor
openfang status

2.5 Start daemon + mở dashboard

openfang start

Kỳ vọng:

openfang start in ra URL API/Dashboard; thường là http://127.0.0.1:4200/ (nhưng hãy tin output của CLI hơn).
Health check: curl http://127.0.0.1:4200/api/health (thay port theo output openfang start nếu bạn đổi api_listen)

[!note] Daemon cung cấp gì? (từ openfang.sh/docs/getting-started)

REST API: http://127.0.0.1:4200/api/

WebSocket: ws://127.0.0.1:4200/api/agents/<id>/ws

WebChat UI: http://127.0.0.1:4200/

Tắt daemon: curl -X POST http://127.0.0.1:4200/api/shutdown

[!tip] Hot reload Theo changelog, config có thể hot-reload theo polling (không phải lúc nào cũng cần restart), nhưng production vẫn nên kiểm tra kỹ sau mỗi thay đổi.

2.6 Spawn 1 agent template và chat (để kiểm key + routing)

# Tip: chạy `openfang agent new` (không args) để mở picker templates
openfang agent new assistant
openfang chat assistant
> "Tóm tắt 5 xu hướng nổi bật về agent frameworks trong 2026."

[!tip] Nếu bạn muốn chat theo agent ID openfang agent list → openfang agent chat <AGENT_ID>.

2.7 Kích hoạt 1 Hand (qua dashboard/TUI) và xem tiến độ

Cách ổn định nhất:

Mở TUI: chạy openfang (không subcommand) → tab Hands → Activate researcher.
Hoặc mở web dashboard: openfang dashboard → tab Hands.

API (khi bạn muốn script hóa):

curl -X POST http://127.0.0.1:4200/api/hands/researcher/activate
curl http://127.0.0.1:4200/api/hands/active

[!note] Auth/port Nếu bạn bật api_key, thêm -H "Authorization: Bearer <api_key>". Nếu bạn đổi api_listen, thay 127.0.0.1:4200 theo port thực tế.

Kết quả mong đợi

Bạn chat với 1 agent trả lời ổn (key/config đúng).
Bạn thấy 1 Hand chạy nền và tạo output (dashboard/kênh chat nếu đã cấu hình).

3) Chuẩn “zero → hero” của tài liệu này

Một tài liệu Zero → Hero “đúng bài” luôn có:

Quickstart làm được ngay
Roadmap theo level (mỗi level có bài tập + output)
Checklist pass/fail rõ ràng
Troubleshooting theo triệu chứng
Cheat sheet để dùng lại hằng ngày

4) Roadmap theo Level (bài tập + output)

[!note] Rule of thumb Mỗi level phải tạo ra một artefact thật (report, lead list, prediction log, dashboard metrics…). Chỉ “chạy lệnh” không tính.

Level 0 — Local loop chạy được (30–45 phút)

Mục tiêu: daemon + dashboard lên; chạy được 1 Hand.

Bài tập

Chạy openfang doctor và đảm bảo không báo lỗi cấu hình/key.
Spawn 1 agent template (assistant) và chat 1 câu.
Kích hoạt Hand researcher và chờ nó chạy xong 1 vòng.
Dùng dashboard/TUI (tab Hands) hoặc gọi GET /api/hands/active để kiểm tra tiến độ/output.

Checklist pass

Dashboard truy cập được
openfang doctor pass (hoặc chỉ warning “thiếu provider” nếu bạn cố tình chưa set key)
Agent chat không lỗi auth/model
Hand chạy và tạo ra output (ít nhất 1 report)

Level 1 — Báo cáo qua kênh chat (45–90 phút)

Mục tiêu: output “chảy” về nơi bạn đọc mỗi ngày (Telegram/Slack/Discord/Email…).

Bài tập (gợi ý Telegram)

Set env var:

TELEGRAM_BOT_TOKEN=...

Setup nhanh: openfang channel setup telegram (interactive).
Hoặc thêm cấu hình kênh vào config (ví dụ cấu trúc TOML):

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "researcher"
allowed_users = ["123456789"]

Kích hoạt lại Hand và kiểm tra tin nhắn nhận được.

Checklist pass

Tin nhắn đến đúng người/đúng group
Có policy “allowed_users” hoặc cơ chế tương đương (không mở bừa)

Level 2 — Routing nhiều providers + kiểm soát chi phí (60–120 phút)

Mục tiêu: giảm rủi ro “1 provider chết là chết cả hệ”, và không cháy bill.

Bài tập

Bật 2 providers (ví dụ 1 cloud + 1 local) để có fallback.
Chạy 1 Hand và 3 phiên chat; quan sát log/cost (nếu bật).

Checklist pass

Khi provider A lỗi, hệ vẫn chạy (fallback)
Có giới hạn usage/budget theo agent (hoặc cấu hình tương đương)

Level 3 — Tạo agent template của bạn (60–90 phút)

Mục tiêu: agent có persona rõ + capability tối thiểu (nguyên tắc “least privilege”).

Bài tập

Tạo 1 agent “weekly-researcher” chỉ có web fetch + read-only memory (tuỳ use case).
Spawn agent đó và chạy 1 nhiệm vụ.

Manifest mẫu (rút gọn)

name = "weekly-researcher"
version = "0.1.0"
description = "Tổng hợp báo cáo tuần có trích dẫn"
author = "you"
module = "builtin:chat"
tags = ["research"]

[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"

[capabilities]
tools = ["web_fetch"]
memory_read = ["*"]
memory_write = ["self.*"]
agent_spawn = false

Checklist pass

Agent chạy đúng phạm vi tool/memory (không có “tool thừa”)
Output có format cố định (template báo cáo)

Level 3.5 — Workflows + Triggers (45–90 phút)

Mục tiêu: biến “một yêu cầu” thành pipeline có thể chạy lại, và tự động hoá theo event.

Bài tập

Tạo 1 workflow research → write → review (sequential) hoặc fan_out → collect.
Chạy workflow 2 lần với 2 input khác nhau và so output.
Tạo 1 trigger đơn giản (ví dụ fire khi agent spawn) để thấy event-driven hoạt động.

Checklist pass

openfang workflow run ... chạy ra artefact có format ổn định
Trigger fire đúng điều kiện và không spam (set --max-fires khi cần)

Level 4 — Skills và Hand tuỳ chỉnh (90–180 phút)

Mục tiêu: thêm “năng lực mới” (skill) hoặc đóng gói workflow thành “autonomous process” (Hand).

Bài tập

Cài 1 skill từ marketplace (openfang skill search/install) hoặc scaffold skill mới (openfang skill create).
Nếu task nhạy cảm: ưu tiên runtime wasm để chạy trong sandbox; nếu chỉ “knowledge”: dùng prompt_only.
Chọn 1 việc lặp lại hằng ngày (theo dõi đối thủ / tổng hợp tin / cảnh báo giá) rồi viết HAND.toml + playbook + guardrails.

Checklist pass

Skill cài được và tool xuất hiện trong runtime (agent gọi được)
Hand chạy theo lịch (không cần prompt)
Có guardrails (approval gates) cho hành động nhạy cảm
Có metrics hiển thị trên dashboard

Level 5 — Vận hành production (nửa ngày)

Mục tiêu: chạy ổn định + audit được + hạn chế bề mặt tấn công.

Bài tập

Bật HTTP auth (API key), giới hạn listen/bind, và chạy verify audit trail.
Thiết lập backup cho SQLite/memory.
Pin phiên bản/commit nếu bạn triển khai dài hạn (đúng cảnh báo pre-1.0).

Checklist pass

Có api_key (Bearer) trong ~/.openfang/config.toml (khuyến nghị)
Không expose public nếu chưa harden
Verify audit chain chạy được
Có backup/restore plan

5) Hands (điểm khác biệt lớn nhất)

Hands = gói “năng lực tự trị” chạy độc lập, theo lịch, không cần bạn prompt.

Mỗi Hand (theo README) gồm:

HAND.toml: manifest (tools, settings, requirements, metrics)
System prompt dạng playbook nhiều phase
SKILL.md: kiến thức nền được inject khi chạy
Guardrails: approval gates cho hành động nhạy cảm

5.1 7 Hands dựng sẵn (tóm tắt “đúng việc”)

Clip: YouTube URL → chọn đoạn hay → cắt shorts dọc; captions + thumbnail; optional AI voice-over; auto publish Telegram/WhatsApp (pipeline nhiều phase: FFmpeg + yt-dlp + STT).
Lead: chạy hằng ngày; discover+enrich; ICP scoring 0–100; dedupe; export CSV/JSON/Markdown; scheduled delivery; build ICP profile + knowledge graph theo thời gian.
Collector: OSINT-style monitoring; change detection + sentiment tracking; build knowledge graph; critical alerts khi có biến động.
Predictor: superforecasting engine; evidence chains; calibrated predictions; theo dõi accuracy bằng Brier scores; có contrarian mode.
Researcher: cross-reference nguồn; CRAAP evaluation; report có trích dẫn (APA); hỗ trợ đa ngôn ngữ.
Twitter: quản lý X; 7 content types xoay vòng; schedule; engagement tracking; brand voice control; approval queue (không post khi chưa OK).
Browser: web automation; Playwright bridge; session persistence; CAPTCHA detection; mandatory purchase approval gate.

[!tip] Kích hoạt/pause Hands Đường chính: dashboard/TUI (tab Hands). Nếu cần script hóa, dùng API /api/hands/* (xem Cheat sheet). Nếu binary của bạn có openfang hand --help thì dùng CLI cũng được.

5.2 Patterns khai thác Hands (từ `openfang.sh/docs/hands`)

Hands không chỉ “schedule chạy nền”, mà có thể:

Event-driven Hands: phản ứng theo event/webhook (thay vì chỉ cron)
- Ví dụ (docs minh hoạ):
  - [hand.triggers] events = ["file_created", "webhook_received"]
  - webhook_path = "/hooks/invoice"
Chaining nhiều Hand: output Hand A làm input Hand B
- Ví dụ: [hand.chain] after = ["data-fetcher"], input_from = "data-fetcher.output"
Custom dashboard widgets: vẽ chart/stat theo metrics của Hand
- Ví dụ: [[hand.dashboard.widgets]] type = "chart" metric = "invoices_processed" period = "7d"

[!note] Marketplace cho Hands (FangHub) Docs có nhắc luồng publish và ví dụ install kiểu openfang hand install fanghub://username/invoice-processor. Vì CLI có thể lệch theo version, hãy kiểm tra openfang hand --help trước khi viết automation.

6) Workflows & Triggers (pipeline + event-driven)

Nếu Hands là “gói năng lực tự trị”, thì Workflows và Triggers là cách bạn xây “hệ thống” từ nhiều agent mà không cần viết Hand mới.

6.1 Workflows (multi-agent pipelines)

Dùng khi: research → viết → review; hoặc fan-out (nhiều agent phân tích song song) → collect → tổng hợp.
Step modes: sequential, fan_out, collect, conditional, loop (có variable substitution {{input}} và {{var}}).
Tạo/chạy qua CLI hoặc REST API; web UI có visual workflow builder.

Quick commands:

openfang workflow list
openfang workflow create ./my-workflow.json
openfang workflow run <WORKFLOW_ID> "input text"

Workflow JSON tối thiểu (bạn có thể copy thành my-workflow.json):

{
  "name": "research-write-review",
  "description": "Research -> draft -> review",
  "steps": [
    {
      "name": "research",
      "agent_name": "researcher",
      "prompt": "Research kỹ chủ đề sau, trích link nguồn.\n\n{{input}}",
      "mode": "sequential",
      "timeout_secs": 300,
      "error_mode": "retry",
      "max_retries": 1,
      "output_var": "research"
    },
    {
      "name": "draft",
      "agent_name": "writer",
      "prompt": "Viết draft theo template:\n- TL;DR\n- 5 bullets\n- 5 nguồn\n\nNội dung:\n{{research}}",
      "mode": "sequential",
      "timeout_secs": 300,
      "error_mode": "fail",
      "output_var": "draft"
    },
    {
      "name": "review",
      "agent_name": "code-reviewer",
      "prompt": "Review draft theo checklist: đúng/sai, thiếu nguồn, claims mạnh, tone.\nTrả về: MUST FIX / SHOULD FIX / NIT.\n\n{{draft}}",
      "mode": "sequential",
      "timeout_secs": 180,
      "error_mode": "fail",
      "output_var": "review"
    }
  ]
}

6.2 Triggers (event → prompt → agent)

Dùng khi: phản ứng theo sự kiện (agent spawn/terminate, lifecycle events, …).
Trigger cần daemon đang chạy.

Ví dụ:

openfang trigger create <AGENT_ID> '{"agent_spawned":{"name_pattern":"*"}}' \
  --prompt "New agent spawned: {{event}}" \
  --max-fires 10
openfang trigger list

6.3 MCP & A2A (interop: tool servers và agent-to-agent)

MCP client: OpenFang connect tới MCP servers (GitHub/filesystem/DB/…) và namespace tools theo dạng mcp_{server}_{tool}.
MCP server: openfang mcp để IDE/clients gọi OpenFang agents như tool (stdio MCP); tool thường có dạng openfang_agent_<agent_name>.
A2A: expose agent card + task lifecycle để nói chuyện với agent systems khác.

Ví dụ config MCP (stdio):

[[mcp_servers]]
name = "github"
timeout_secs = 30
env = ["GITHUB_PERSONAL_ACCESS_TOKEN"]

[mcp_servers.transport]
type = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

7) Skills (plugin tools + FangHub/ClawHub)

Skills = gói tool bổ sung (ngoài built-in). OpenFang có 60 bundled skills và hỗ trợ cài thêm từ marketplace (FangHub), đồng thời tương thích format SKILL.md của OpenClaw.

7.1 Chọn runtime (để đúng trade-off an toàn)

prompt_only: chỉ inject kiến thức vào system prompt (không chạy code).
python / node: chạy subprocess (có env_clear() + giới hạn env passthrough), nhưng không sandbox mạnh như WASM.
wasm: chạy trong Wasmtime dual-metered sandbox (hợp cho tool nhạy cảm).

7.2 Điều làm skills “đáng tiền” trong OpenFang

Có marketplace (FangHub) + tương thích skill kiểu OpenClaw (SKILL.md), install xong là dùng.
Skill được quét prompt-injection trước khi inject (đặc biệt với prompt_only).
Install từ remote có checksum verification (tăng an toàn supply-chain).

7.3 CLI (đủ để dùng hằng ngày)

openfang skill list
openfang skill search "docker kubernetes"
openfang skill install web-search
openfang skill remove web-search
openfang skill create

8) Providers (cloud + local) và chiến lược chọn nhanh

8.1 Danh mục keys/base URLs hay gặp

Từ .env.example và README:

Cloud: Anthropic, OpenAI, Gemini, Groq, DeepSeek, OpenRouter, Together, Mistral, Fireworks…
Local: Ollama, vLLM, LM Studio…

8.2 “Chọn nhanh” theo nhu cầu

Bạn muốn nhanh và ít rủi ro: chọn 1 cloud provider + 1 fallback.
Bạn muốn privacy/offline: bắt đầu với Ollama/vLLM/LM Studio, rồi thêm cloud cho task nặng.
Bạn muốn nhiều model nhất: dùng OpenRouter như gateway (BYOK), nhưng vẫn nên có fallback native.

8.3 Model catalog, aliases, fallback, cost (thứ hay bị bỏ sót)

OpenFang có 3 native drivers: Anthropic, Gemini, và OpenAI-compatible (route ra nhiều providers).
Có model catalog + aliases, hỗ trợ routing + fallback + cost tracking (tokens/cost có thể hiện ở footer).
OpenFang auto-detect provider nào “sẵn sàng” dựa trên env vars tại lúc boot.

Ví dụ fallback (để khi cloud lỗi vẫn chạy):

[[fallback_providers]]
provider = "ollama"
model = "llama3.2:latest"
api_key_env = ""
base_url = "http://localhost:11434"

[[fallback_providers]]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"

9) Channels (40 adapters) — đưa output về nơi bạn đọc

9.1 Vì sao channels quan trọng

Agent OS chỉ “đáng tiền” khi output đi vào luồng làm việc hằng ngày:

Telegram/Slack/Discord để alert + report
Email để tổng hợp weekly
Webhooks để đẩy vào hệ khác

9.2 Ví dụ config (Telegram)

Từ hướng dẫn migrate (mang tính tham khảo format):

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
default_agent = "coder"
allowed_users = ["123456789"]

[!tip] Kỷ luật vận hành Tách “agent viết report” và “agent gửi report” nếu bạn cần kiểm duyệt/approval.

9.3 Overrides, policies, và setup nhanh (nơi “vận hành thật”)

Mỗi channel đều hỗ trợ overrides: đổi model/system prompt, policy DM/group, rate limit theo user, output format (Markdown/Telegram HTML/Slack mrkdwn…).
Setup interactive: openfang channel list (xem thiếu env/config) và openfang channel setup <channel>.

Ví dụ overrides (Telegram):

[channels.telegram.overrides]
group_policy = "mention_only"
dm_policy = "respond"
rate_limit_per_user = 10
output_format = "telegram_html"
usage_footer = "tokens"

10) Security model (đọc 10 phút để tránh toang)

OpenFang nhấn mạnh defense-in-depth. Những điểm bạn nên nắm (tóm tắt từ SECURITY.md + README):

10.1 Access control và permissioning

Capability-based permissions: agent chỉ làm được thứ nó được cấp (tools/memory/network/shell…).
RBAC multi-user: phân vai Owner/Admin/User/Viewer.
API authentication: Bearer token; có “loopback bypass” cho local CLI.

10.2 Input validation và chống tấn công thường gặp

Chống path traversal (canonicalization + symlink escape prevention).
Chống SSRF (block private IP, metadata endpoints, DNS rebinding).
Prompt injection scanning trên skills (dò override/exfiltration/shell injection).
Rate limiting (GCRA), health redaction, CORS policy (hạn chế khi không có API key).

10.3 Runtime isolation + audit

Tool code chạy trong WASM dual-metered sandbox (fuel + epoch interruption).
Subprocess sandbox: env_clear() + giới hạn biến môi trường.
Taint tracking để theo dõi luồng thông tin nhạy cảm.
Merkle hash-chain audit trail, có endpoint verify (ví dụ /api/audit/verify).

10.4 Hardening checklist (tối thiểu)

Set api_key trong ~/.openfang/config.toml trước khi expose ra LAN/Internet.
Bind api_listen vào 127.0.0.1:<port> và đặt reverse proxy/TLS nếu cần public.
Giữ “least privilege”: capability/tool list tối thiểu; tránh ToolAll nếu không bắt buộc.
Với channels: set allowed_users + group_policy để tránh bot “nói chuyện với cả thế giới”.
Verify audit trail: gọi /api/audit/verify sau khi chạy một vài actions.

[!important] Nguyên tắc vàng Nếu bạn expose OpenFang ra khỏi localhost mà chưa hiểu rõ policy/auth/capabilities: coi như bạn đang tự mở RCE-as-a-service cho chính mình.

11) Migration (nếu bạn đã dùng OpenClaw)

Quick migrate:

openfang migrate --from openclaw

Các tuỳ chọn hay dùng:

openfang migrate --from openclaw --source-dir /path/to/openclaw/workspace
openfang migrate --from openclaw --dry-run

Sau migrate, OpenFang tạo migration_report.md trong ~/.openfang/ để bạn biết cái gì import được/cái gì cần làm tay.

12) Troubleshooting (theo triệu chứng)

12.1 Dashboard không lên

Checklist:

Port đang bị chiếm? (dashboard/API thường theo README là localhost:4200)
Bạn đã openfang start chưa?
Bật log chi tiết: set RUST_LOG=openfang=debug (hoặc RUST_LOG=debug) rồi chạy lại.

12.2 Provider lỗi 401/invalid key

Checklist:

Key đúng biến env chưa (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, …)?
Bạn có đang set nhầm nhiều key và routing ưu tiên sai không?
Nếu dùng local: base URL có đúng không (Ollama/vLLM/LM Studio)?

12.3 Hand chạy nhưng “không ra artefact”

Checklist:

Bạn có cấu hình kênh gửi output chưa?
Hand có cần input/target ban đầu không (ví dụ Collector)?
Xem tab Hands trong dashboard/TUI, hoặc gọi GET /api/hands/active để biết đang stuck phase nào.

12.4 Tin nhắn không tới (Telegram/Slack/Discord)

Checklist:

Token env var có được load vào process không?
allowed_users/policy có chặn không?
Kênh chat có cho bot post không (permission trong platform)?

13) Cheat sheet (dùng hằng ngày)

13.1 Commands cốt lõi

# TUI dashboard (terminal)
openfang

openfang init
openfang doctor
openfang start
openfang status
openfang dashboard
# (thay port theo api_listen)
curl http://127.0.0.1:4200/api/health
curl http://127.0.0.1:4200/api/metrics
curl -X POST http://127.0.0.1:4200/api/shutdown

# Agents
openfang agent new <template>
openfang agent spawn <manifest.toml>
openfang agent list
openfang chat <agent-name>
openfang agent chat <agent-id>

# Hands (qua API; UI/TUI vẫn là đường chính)
# (Thêm Authorization header nếu bật api_key; thay port theo api_listen)
# (Các endpoint /api/hands/* có trong repo snapshot commit 0bb4e6f; nếu bản bạn không có, hãy đối chiếu docs/version hoặc xem UI)
curl -X POST http://127.0.0.1:4200/api/hands/<hand_id>/activate
curl http://127.0.0.1:4200/api/hands/active
curl -X POST http://127.0.0.1:4200/api/hands/instances/<instance_id>/pause
curl -X POST http://127.0.0.1:4200/api/hands/instances/<instance_id>/resume
curl -X DELETE http://127.0.0.1:4200/api/hands/instances/<instance_id>

# Hands (nếu binary của bạn có `openfang hand --help`)
openfang hand list
openfang hand activate <hand>
openfang hand status <hand>
openfang hand pause <hand>
openfang hand resume <hand>
openfang hand deactivate <hand>

# Workflows / triggers
openfang workflow list
openfang workflow create <workflow.json>
openfang workflow run <workflow-id> "input"
openfang trigger list
openfang trigger create <agent-id> '<pattern-json>'
openfang trigger delete <trigger-id>

# Skills / channels / MCP
openfang skill list
openfang skill install <source>
openfang channel list
openfang channel setup <channel>
openfang mcp

openfang migrate --from openclaw

13.2 Env vars hay dùng

Provider keys: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, …
Local endpoints: OLLAMA_BASE_URL, VLLM_BASE_URL, LMSTUDIO_BASE_URL
Channels: TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, …
CLI/TUI: RUST_LOG, OPENFANG_AGENTS_DIR, EDITOR, VISUAL

13.3 Paths quan trọng

~/.openfang/config.toml (config)
~/.openfang/data/openfang.db (SQLite)
~/.openfang/daemon.json (daemon discovery)
~/.openfang/skills/ (skills cài thêm)
~/.openfang/tui.log (log cho TUI)

14) Gợi ý lộ trình thực chiến (nếu bạn mới bắt đầu)

Level 0: spawn assistant agent + chạy 1 Hand (để thấy đủ “chat + autonomous”).
Level 1: nối Telegram/Slack để output “đi vào đời sống”.
Level 2: thêm fallback providers + bật usage footer/cost tracking.
Level 3: dựng 1 workflow pipeline (sequential/fan-out) cho 1 use case thật.
Level 3.5: thêm 1 trigger event-driven (để workflow/agent tự chạy theo event).
Level 4: cài/viết 1 skill (hoặc tự viết Hand nếu workflow chưa đủ).
Level 5: harden trước khi expose.

15) Trường hợp khai thác hiệu quả (playbooks)

[!summary] Cách nghĩ nhanh

Hands = “autopilot chạy nền” (theo lịch, có guardrails/metrics).

Workflows = “pipeline có thể chạy lại” (dễ debug, dễ chuẩn hoá output).

Triggers = “event-driven” (tự chạy khi có sự kiện).

Skills/MCP = “thêm tool” (kết nối hệ ngoài hoặc đóng gói logic).

Channels = “đưa output về đúng nơi” (policy + formatting + rate limit).

15.1 Daily/Weekly Intel Brief (đối thủ, thị trường, sản phẩm)

Khi dùng: bạn muốn 1 bản tin mỗi sáng/tuần, có trích nguồn, có thay đổi đáng chú ý.

Thiết kế hiệu quả

Input: danh sách đối thủ/keyword + nguồn ưu tiên (blog, changelog, repo releases, filings…).
Engine: Collector (monitor) → Researcher (cited report) → Writer (tóm tắt 1 trang).
Output: Telegram/Email + lưu vào KB (memory/notes).

Mẹo vận hành

Dùng channel overrides để chạy model rẻ cho “alert ngắn”, model mạnh cho “report dài”.
Đặt “definition of done”: 5 bullets + 3 điều bất thường + 5 links nguồn.

15.2 Lead Gen vận hành (ICP → enrich → score → dedupe → export)

Khi dùng: bạn muốn “mỗi ngày có 10–50 leads đủ chuẩn”, không phải đi tìm thủ công.

Tận dụng cái OpenFang làm sẵn

Lead Hand: build ICP profile theo thời gian, chấm điểm 0–100, dedupe, xuất CSV/JSON/Markdown.
Channels/Webhook: đẩy vào Slack/Email/CRM.

Guardrails nên có

Chỉ allow outbound tới domains cho phép (capability NetConnect/SSRF guard).
Audit trail cho mọi bước “enrich”.

15.3 Content Factory có kiểm soát (research → outline → draft → review)

Khi dùng: bạn muốn sản xuất nội dung đều, nhưng vẫn giữ chất lượng và style.

Workflow mẫu (ý tưởng)

Step 1 (researcher): research có trích dẫn.
Step 2 (writer): viết theo template cố định.
Step 3 (code-reviewer/editor): checklist fact/style + “must fix”.
Step 4 (optional): social-media agent tạo teaser posts.

Khai thác mạnh

Dùng fan_out để nhiều agent “phản biện” cùng lúc, rồi collect để tổng hợp.
Dùng loop để refine đến khi có keyword “APPROVED”.

15.4 Browser Automation cho tác vụ lặp (nhưng tránh rủi ro)

Khi dùng: điền form, thao tác web nhiều bước, thu thập dữ liệu, kiểm tra UI.

Tận dụng Browser Hand

Session persistence (không phải login lại mỗi lần).
Có gate bắt buộc trước hành động nhạy cảm (ví dụ purchase).

Cách làm “khôn”

Tách “khám phá UI” (1 lần) và “thực thi routine” (hằng ngày).
Log + screenshot làm evidence cho mỗi run.

15.5 Forecasting/Prediction Engine (calibrated, có scoring)

Khi dùng: bạn muốn dự báo (market, launch, roadmap) và đo độ đúng theo thời gian.

Tận dụng Predictor Hand

Confidence intervals + Brier score + contrarian mode (chống groupthink).
Lưu prediction log để học lại.

15.6 Social Media Autopilot (nhưng có approval queue)

Khi dùng: bạn muốn post đều, trả lời mentions, tracking metrics; vẫn cần “human in the loop”.

Tận dụng Twitter Hand

7 formats xoay vòng, schedule, phản hồi mentions.
Approval queue: không post khi chưa được OK.

15.7 “Agent fleet” cho team (RBAC + channel policies + audit)

Khi dùng: nhiều người dùng chung, cần phân quyền, tránh agent làm bậy.

Thiết kế hiệu quả

RBAC: owner/admin/user/viewer + channel bindings.
Capability theo vai: “ops” có quyền thấp; “orchestrator/security-auditor” quyền cao nhưng giới hạn.
Bật api_key và chặn CORS/port expose.

15.8 IDE integration: dùng OpenFang như “đầu não” qua MCP

Khi dùng: bạn muốn Cursor/VS Code/Claude Desktop gọi agent “trong nhà” (có policies, audit).

Khai thác

openfang mcp (MCP server, stdio) để IDE gọi openfang_agent_<name>.
Kết hợp MCP client (GitHub/filesystem/DB) để agent có tool phong phú nhưng vẫn namespaced.

15.9 Drop-in OpenAI API (để tái dùng tooling hiện có)

Khi dùng: bạn đã có app/tooling nói chuyện với OpenAI SDK, muốn “đi qua OpenFang”.

Khai thác

Trỏ base URL tới OpenFang và dùng /v1/chat/completions (streaming SSE hoặc non-stream).
Dùng api_key để bắt auth khi không chạy localhost.

15.10 Ops/Monitoring loop (metrics + audit + channel alerts)

Khi dùng: bạn muốn agent hỗ trợ vận hành: health check, báo cáo usage/cost, cảnh báo bất thường.

Khai thác

/api/metrics (Prometheus) + usage analytics để thấy “đốt tiền ở đâu”.
Triggers để tự tạo báo cáo theo event (ví dụ agent crash/terminate).
Channel overrides để alert ngắn gọn, tránh spam.

15.11 Event-driven Hand: xử lý hoá đơn/inbox tự động (webhook/file → extract → validate → export)

Khi dùng: bạn có “dòng chảy” dữ liệu lặp (hoá đơn, đơn hàng, ticket, log) và muốn nó tự xử lý theo event, có dashboard metrics, có cảnh báo lỗi.

Thiết kế hiệu quả (từ patterns trong openfang.sh/docs/hands)

Dùng Hand thay vì agent chat: vì cần chạy liên tục, có lifecycle/metrics rõ.
Bật event trigger (minh hoạ): [hand.triggers] events = ["file_created", "webhook_received"] + webhook_path = "/hooks/invoice".
Nếu pipeline có bước “fetch dữ liệu” riêng: dùng chaining ([hand.chain] after = ["data-fetcher"]).
Tạo dashboard widgets theo dõi: invoices_processed, validation_errors để “nhìn là biết toang”.

Guardrails

Nếu có thao tác nhạy cảm (chuyển tiền, mua hàng, xoá dữ liệu): bắt buộc approval gate/human-in-the-loop.
Đẩy lỗi về channel (Slack/Telegram/Email) thay vì chỉ log.

[!note] Về lệnh openfang hand ... Các command trong các playbook dưới đây theo openfang.sh/docs/hands. Nếu binary bạn đang chạy không có nhóm lệnh openfang hand, hãy dùng dashboard/TUI (tab Hands) hoặc API /api/hands/* (xem Cheat sheet) để thao tác.

15.12 Clip Hand (Content Creation) — “đổi long-form thành shorts” theo pipeline nhiều phase

Khi dùng: bạn có video dài (YouTube/podcast/webinar) và muốn ra đều clip ngắn có caption/thumbnail/voice-over.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate clip
Cấu hình input (UI/TUI; hoặc CLI nếu có): openfang hand config clip --set source_url="https://youtube.com/..."
Chọn output: export file (để review) và/hoặc gửi về channel (Telegram/Slack) để duyệt.
Đặt “definition of done”: mỗi run tạo X clip, có quality score, có captions, có 1 thumbnail.
Bật guardrails: không auto publish ra kênh public nếu chưa có approval.

Guardrails / rủi ro hay gặp

Bản quyền + chính sách nền tảng: chỉ dùng nguồn bạn có quyền.
Pipeline phụ thuộc toolchain (yt-dlp/FFmpeg): nếu run fail, ưu tiên check openfang doctor + log.

Kênh output gợi ý

Telegram/Slack: gửi preview + link artefact để duyệt nhanh.
Webhook: đẩy metadata (title/timestamps/tags) sang hệ scheduling.

15.13 Lead Hand (Data Intelligence) — “mỗi ngày có lead đủ chuẩn”

Khi dùng: cần lead gen vận hành (discover → enrich → score → dedupe → export) mà không phải làm thủ công.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate lead
Cấu hình ICP nhanh (UI/TUI; hoặc CLI nếu có): openfang hand config lead --set target_industry="SaaS" --set min_score=70
Đặt output format + nơi nhận (CSV/JSON + Slack/Email/Webhook).
Theo dõi metrics: leads discovered/enriched, average score, dedupe rate.
Chốt guardrail: “chỉ generate list”, không tự contact nếu chưa có approval/human review.

Guardrails

Privacy/compliance: hạn chế PII, log redaction, lưu trữ có chủ đích.
NetConnect allowlist (nếu bạn harden): chỉ cho phép domain cần thiết để enrich.

Kênh output gợi ý

Slack: daily “top N leads >= min_score”.
Webhook: đẩy thẳng sang CRM.

15.14 Collector Hand (OSINT Intelligence) — “monitor đối thủ/keyword 24/7”

Khi dùng: competitive monitoring, brand monitoring, threat intel, market surveillance.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate collector
Cấu hình target (UI/TUI; hoặc CLI nếu có): openfang hand config collector --set target="competitor-name"
Đặt alert threshold: chỉ ping khi “có thay đổi đáng kể” (giảm noise).
Lưu knowledge graph/memory theo namespace để truy vấn lại.
Review định kỳ: xem “signal-to-noise” và tinh chỉnh nguồn.

Guardrails

Tránh scraping bừa: ưu tiên RSS/public sources; tôn trọng ToS.
Bật channel policy/rate limit để không spam group chat.

Kênh output gợi ý

Telegram/Slack: anomaly alerts ngắn.
Email: weekly digest có trích nguồn.

15.15 Predictor Hand (Calibrated Forecasting) — “dự báo có đo độ đúng”

Khi dùng: strategic planning, risk assessment, trend forecasting; cần prediction log + calibration.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate predictor
Cấu hình domain + contrarian mode (UI/TUI; hoặc CLI nếu có): openfang hand config predictor --set domain="technology" --set contrarian_mode=true
Chuẩn hoá output: mỗi prediction phải có probability + evidence chain.
Track Brier score theo thời gian (để biết có “ảo tưởng tự tin” không).
Tạo loop review: định kỳ so prediction vs outcome để tự calibrate.

Guardrails

Không dùng dự báo làm quyết định high-stakes nếu không có quy trình review.
Giữ dữ liệu đầu vào/nguồn rõ ràng để tránh “forecast theo cảm tính”.

Kênh output gợi ý

Slack: “weekly forecast board” (top 10 dự báo + mức tin cậy).
Webhook: đẩy vào dashboard nội bộ.

15.16 Researcher Hand (Deep Autonomous Research) — “report có trích dẫn”

Khi dùng: due diligence, tech assessment, market research; cần report có nguồn, đa ngôn ngữ.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate researcher
Set topic (UI/TUI; hoặc CLI nếu có): openfang hand config researcher --set topic="quantum computing 2025"
Definition of done: 1 report có TL;DR + 5–15 sources + citations (APA).
Dùng model mạnh cho “analysis”, model rẻ cho “tóm tắt/format” (routing/overrides).
Lưu report vào memory/KB để query lại.

Guardrails

Bắt buộc citations cho claims mạnh; không có nguồn thì hạ mức tin cậy.
Nếu report dùng để quyết định lớn: thêm bước review (workflow “research → review → approve”).

Kênh output gợi ý

Email: report dài.
Slack/Telegram: TL;DR + 5 link quan trọng.

15.17 Twitter Hand (Social Media Management) — “autopilot nhưng phải duyệt”

Khi dùng: thought leadership, community engagement, content distribution; cần approval queue.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate twitter
Bật approval (UI/TUI; hoặc CLI nếu có): openfang hand config twitter --set approval_required=true
Define brand voice + topics cấm (policy).
Chốt lịch posting + quota (tránh spam/ban).
Theo dõi engagement analytics để tối ưu nội dung.

Guardrails

Không auto-post khi chưa có review (đúng tinh thần approval queue).
Tránh post nội dung “có thể gây hại”: legal/claims/PII.

Kênh output gợi ý

Slack: kênh “approval queue” (mọi draft post vào đây).
Email: weekly performance recap.

15.18 Browser Hand (Web Automation) — “Playwright có purchase gate”

Khi dùng: form automation, testing workflows, price monitoring, data extraction multi-step.

Checklist triển khai

Activate Hand (dashboard/TUI hoặc CLI nếu có): openfang hand activate browser
Cấu hình mode (UI/TUI; hoặc CLI nếu có): openfang hand config browser --set headless=true
Chuẩn hoá “evidence”: luôn lưu screenshot + log cho mỗi run.
Đặt boundary rõ: trang nào được phép thao tác, hành động nào cần approval.
Thiết kế retry/backoff để tránh bị block/429.

Guardrails

Purchase approval gate: không cho phép giao dịch tài chính nếu chưa xác nhận người thật.
Không nhét secrets vào prompt; dùng env + capability gating.

Kênh output gợi ý

Telegram/Slack: alert khi có thay đổi giá/đơn hàng/step fail.
Webhook: đẩy data extract sang hệ ETL.

16) Best Recipes (Cookbook theo docs `openfang.sh`)

[!summary] Cách dùng phần này Mỗi trang docs = 5 bullets kiểu “làm được ngay”. Nếu gặp lệch version/command: chạy openfang --help để đối chiếu binary.

16.1 Download (`/download`) — chọn cách cài đúng nhất

Xác nhận system requirements: macOS 12+, Linux glibc 2.17+, Windows 10+; x86_64/ARM64; ~50MB disk.
Chọn installer nhanh: macOS/Linux dùng curl -fsSL https://openfang.sh/install | sh; Windows dùng irm https://openfang.sh/install.ps1 | iex.
Nếu muốn thủ công: tải artefact theo OS/arch từ GitHub Releases latest (tar.gz/zip theo target triple).
Nếu không muốn “đụng máy”: dùng Docker image để thử nhanh trước.
Sau cài: openfang --version + openfang doctor để verify.

16.2 Installer scripts (`/install`, `/install.ps1`) — hiểu để tránh “cài mù”

/install detect OS/arch → map sang target triple → tải releases/latest → copy vào ~/.openfang/bin/openfang.
/install tự append PATH vào profile (.zshrc/.bashrc/fish/.profile) nếu chưa có.
/install.ps1 detect x64/arm64 → tải zip → extract → copy vào %USERPROFILE%\\.openfang\\bin\\openfang.exe.
/install.ps1 thêm ~\\.openfang\\bin vào User PATH (yêu cầu restart terminal để chắc ăn).
Cả hai script đều “fail fast” nếu thiếu release tương ứng hoặc file tải về quá nhỏ (coi như lỗi).

16.3 Getting Started (`/docs/getting-started`) — đường ngắn nhất để chạy được việc

Cài xong thì chạy openfang init (interactive) hoặc openfang init --quick (CI/scripts).
Chỉ cần set 1 env var provider là chạy (GROQ/GEMINI/ANTHROPIC/OPENAI...); local provider (Ollama/vLLM/LM Studio) có thể không cần key.
Verify nhanh: openfang doctor + openfang status.
Start daemon: openfang start → mở http://127.0.0.1:4200/ (WebChat UI) + API /api/*.
Nếu chạy Docker: map port 4200 và mount volume data để persist state.

16.4 Hands (`/docs/hands`) — “primitive ăn tiền” của OpenFang

Hands = “autonomous capability packages”: chạy theo lịch, build knowledge, report metrics; không phải chatbot.
7 Hands built-in: Clip/Lead/Collector/Predictor/Researcher/Twitter/Browser (mỗi cái có playbook + guardrails).
Lifecycle rõ: Inactive ↔ Active ↔ Paused; activate/pause/resume/deactivate để kiểm soát.
Cấu trúc Hand chuẩn: HAND.toml (manifest) + system-prompt.md (playbook nhiều phase) + SKILL.md (knowledge).
Patterns xịn: event-driven triggers, chaining nhiều Hand, custom dashboard widgets theo metrics.

16.5 Architecture (`/docs/architecture`) — mental model để debug nhanh

OpenFang là workspace 14 crates: CLI/desktop/API/kernel/runtime/channels/wire/skills/memory/types...
Debug boot lỗi theo boot sequence: config → data dir → SQLite → LLM driver → model catalog → metering/router → skills → channels.
Memory có nhiều lớp: KV per-agent + semantic search + namespace shared để share cross-agent.
Web tools context có web search/fetch với SSRF guard + caching (đọc config để tune).
Capability enforcement là “đường chính” của security: agent chỉ làm thứ được cấp trong manifest.

16.6 Configuration (`/docs/configuration`) — chỉnh đúng 20% field ăn 80% giá trị

Mọi field đều optional (serde default); thiếu thì lấy default; config ở ~/.openfang/config.toml.
Secrets không nhét trực tiếp; config chỉ giữ tên env var (*_env); debug output auto redaction.
3 thứ nên set sớm: api_key (auth), api_listen (bind), usage_footer (tokens/cost).
Providers: [default_model] + [[fallback_providers]]; local provider set base_url.
Integrations: [[mcp_servers]] (stdio/SSE), [a2a], [channels.*] + overrides (policy/rate limit/output format).

16.7 Security (`/docs/security`) — đọc để khỏi tự biến mình thành RCE-as-a-service

OpenFang đi theo defense-in-depth: capability gating + WASM dual metering + audit trail + taint tracking + SSRF + path traversal + loop guard...
Nếu expose khỏi localhost: bắt buộc api_key, bind chặt api_listen, và hạn chế capabilities/tools.
Supply-chain: manifest signing (Ed25519) + prompt-injection scanner cho skills + secret zeroization.
API layer: security headers + GCRA rate limiter + health endpoint redaction (không leak cấu hình).
Vận hành: verify audit chain định kỳ; xem metrics/usage để phát hiện hành vi lạ.

16.8 Providers (`/docs/providers`) — chọn model/provider “đúng bài”

OpenFang dùng 3 drivers (Anthropic/Gemini/OpenAI-compatible) để cover nhiều providers.
Quick setup: set 1 key env var là boot được; boot auto-detect providers nào “ready”.
Dùng model catalog + aliases để tránh hardcode model id rối rắm; per-agent override khi cần.
Routing/fallback để cân bằng cost/latency: model rẻ cho task nhẹ, model mạnh cho task nặng.
Debug nhanh bằng API: /api/models, /api/models/aliases, /api/providers.

16.9 Channel Adapters (`/docs/channel-adapters`) — đưa agent vào “nơi bạn đọc”

40 channels: Telegram/Discord/Slack/Email/Webhook/... (nhiều platform enterprise/social/privacy).
Enable adapter bằng cách thêm section [channels.<name>] trong config + set env token.
Dùng overrides để vận hành: DM/group policy, per-user rate limit, output format (TelegramHtml/SlackMrkdwn...), usage footer.
Với webhook-based channels (WhatsApp/LINE/Viber...): cần public endpoint hoặc tunnel + verify token đúng.
Nếu sợ spam: bật allowed_users + group_policy “mention_only” + rate limit theo user.

16.10 Agent Templates (`/docs/agent-templates`) — “đội hình” 30 agents có tier rõ ràng

30 templates chia 4 tier theo độ khó/cost; tier cao dùng model mạnh hơn.
Spawn bằng CLI (openfang agent new ... hoặc openfang spawn ... tuỳ version) hoặc REST API (template name + overrides).
Set keys để unlock tier: tối thiểu GROQ_API_KEY, thêm GEMINI_API_KEY, thêm DEEPSEEK_API_KEY.
Custom templates đặt vào agents/custom/ hoặc ~/.openfang/agents/ để quản lý như “catalog nội bộ”.
Tách agent theo vai: writer/researcher/reviewer/security-auditor để pipeline dễ kiểm soát.

16.11 Skill Development (`/docs/skill-development`) — thêm tool theo cách an toàn

Skills = bundle tools; runtime: python/node (subprocess), wasm (sandboxed), prompt_only (SKILL.md), builtin.
Chọn wasm khi tool nhạy cảm (sandbox mạnh); chọn prompt_only khi chỉ cần knowledge.
Install: local dir, marketplace name, hoặc git URL; list/remove để quản lý lifecycle.
Manifest cần schema input rõ + requirements tối thiểu (tools/capabilities) để “least privilege”.
OpenClaw compatibility: nhận SKILL.md/YAML frontmatter, tự convert sang prompt_only.

16.12 Workflows (`/docs/workflows`) — pipeline multi-agent reproducible

Dùng workflows khi cần “chạy lại được” và audit được (research → write → review, fan-out → collect).
Step modes: sequential/fan-out/conditional/loop; output_var để truyền giữa steps.
Variable substitution {{input}}/{{var}} giúp prompt template hoá.
Set timeout + error_mode (fail/retry) để workflow không “treo vô hạn”.
Trigger engine để chạy workflow theo event (kết hợp channels để alert/report).

16.13 MCP & A2A (`/docs/mcp-a2a`) — interop đúng chuẩn công nghiệp

MCP client: nối external MCP servers (GitHub/filesystem/postgres/puppeteer...) qua [[mcp_servers]].
MCP server: chạy openfang mcp để IDE (Cursor/VS Code/Claude Desktop) gọi agent như tool.
A2A server publish agent card tại /.well-known/agent.json; có endpoints /a2a/* cho task lifecycle.
A2A client: khai báo external agents trong config để “federate” nhiều agent system.
Security: xem lại auth/bind/CORS trước khi expose; coi MCP/A2A như “tăng bề mặt tấn công” nếu không harden.

16.14 API Reference (`/docs/api-reference`) — automation đúng cách

Khi set api_key, hầu hết endpoints yêu cầu Authorization: Bearer ... (trừ /api/health và /).
Top endpoints nên nhớ: /api/agents, /api/agents/{id}/message, /api/models, /api/providers, /api/skills, /api/status, /api/shutdown.
Có WebSocket chat (/api/agents/{id}/ws) và SSE streaming (/message/stream) cho UI/automation.
OpenAI-compatible endpoint: /v1/chat/completions để reuse SDK/tooling hiện có.
API layer có rate limiter + security headers; production nên monitor /api/metrics.

16.15 CLI Reference (`/docs/cli-reference`) — CLI là “đầu điều khiển”

Hiểu 2 mode: daemon mode (CLI nói chuyện với daemon) và in-process mode (ephemeral).
Dùng openfang (không args) để mở TUI dashboard; log riêng ở ~/.openfang/tui.log.
openfang init --quick cho CI/scripts; openfang doctor --repair để tự fix lỗi thường gặp.
openfang status --json hữu dụng cho scripting/monitoring.
Tạo completion cho bash/zsh/fish/powershell để thao tác nhanh.

16.16 Desktop (`/docs/desktop`) — “agent OS đóng gói” như app

Desktop app là wrapper Tauri 2.0 boot cùng kernel/API như headless daemon.
Điểm mạnh: system tray + notifications + single-instance (phù hợp always-on).
Vẫn dùng cùng ~/.openfang/config.toml và env vars (keys/tokens).
Nếu share máy/team: vẫn nên set api_key (đừng nghĩ desktop là “auto safe”).
Debug vẫn theo RUST_LOG + log kernel.

16.17 Troubleshooting (`/docs/troubleshooting`) — chẩn đoán theo thứ tự đúng

Bắt đầu: openfang doctor → openfang status → curl /api/health.
Log: RUST_LOG=openfang=debug openfang start (hoặc bật crate-specific).
Nếu provider lỗi: check env var, test provider endpoint, giảm context bằng compaction, dùng model nhỏ cho agent đơn giản.
Nếu channel lỗi: token/intents/scopes + allowed_users/policy + webhook public access (nếu cần).
Nếu “port in use/config lỗi”: dùng openfang config show + đổi api_listen + kill process chiếm port.

thuongtin/OpenFang.md

OpenFang Zero → Hero (Agent Operating System)

0) Bạn sẽ có gì sau khi đọc (outcomes)

1) OpenFang là gì (và không là gì)

1.1 OpenFang là gì

1.2 OpenFang không phải

1.3 Mental model (để khỏi học nhầm)

1.4 Những tính năng “hấp dẫn” của OpenFang (đúng kiểu Agent OS)

1.5 “Đòn bẩy” để khai thác hiệu quả (chọn đúng primitive)

1.6 OpenFang vs “agent frameworks” (để khỏi dùng sai bài)

2) Quickstart (15 phút) — chạy được việc ngay

2.1 Prereqs tối thiểu

2.2 Cài đặt + khởi tạo

2.3 Set keys / base URLs (chọn 1 đường)

2.4 Verify nhanh (doctor/status)

2.5 Start daemon + mở dashboard

2.6 Spawn 1 agent template và chat (để kiểm key + routing)

2.7 Kích hoạt 1 Hand (qua dashboard/TUI) và xem tiến độ

3) Chuẩn “zero → hero” của tài liệu này

4) Roadmap theo Level (bài tập + output)

Level 0 — Local loop chạy được (30–45 phút)

Level 1 — Báo cáo qua kênh chat (45–90 phút)

Level 2 — Routing nhiều providers + kiểm soát chi phí (60–120 phút)

Level 3 — Tạo agent template của bạn (60–90 phút)

Level 3.5 — Workflows + Triggers (45–90 phút)

Level 4 — Skills và Hand tuỳ chỉnh (90–180 phút)

Level 5 — Vận hành production (nửa ngày)

5) Hands (điểm khác biệt lớn nhất)

5.1 7 Hands dựng sẵn (tóm tắt “đúng việc”)

5.2 Patterns khai thác Hands (từ openfang.sh/docs/hands)

6) Workflows & Triggers (pipeline + event-driven)

6.1 Workflows (multi-agent pipelines)

6.2 Triggers (event → prompt → agent)

6.3 MCP & A2A (interop: tool servers và agent-to-agent)

7) Skills (plugin tools + FangHub/ClawHub)

7.1 Chọn runtime (để đúng trade-off an toàn)

7.2 Điều làm skills “đáng tiền” trong OpenFang

7.3 CLI (đủ để dùng hằng ngày)

8) Providers (cloud + local) và chiến lược chọn nhanh

8.1 Danh mục keys/base URLs hay gặp

8.2 “Chọn nhanh” theo nhu cầu

8.3 Model catalog, aliases, fallback, cost (thứ hay bị bỏ sót)

9) Channels (40 adapters) — đưa output về nơi bạn đọc

9.1 Vì sao channels quan trọng

9.2 Ví dụ config (Telegram)

9.3 Overrides, policies, và setup nhanh (nơi “vận hành thật”)

10) Security model (đọc 10 phút để tránh toang)

10.1 Access control và permissioning

10.2 Input validation và chống tấn công thường gặp

10.3 Runtime isolation + audit

10.4 Hardening checklist (tối thiểu)

11) Migration (nếu bạn đã dùng OpenClaw)

12) Troubleshooting (theo triệu chứng)

12.1 Dashboard không lên

12.2 Provider lỗi 401/invalid key

12.3 Hand chạy nhưng “không ra artefact”

12.4 Tin nhắn không tới (Telegram/Slack/Discord)

13) Cheat sheet (dùng hằng ngày)

13.1 Commands cốt lõi

13.2 Env vars hay dùng

13.3 Paths quan trọng

14) Gợi ý lộ trình thực chiến (nếu bạn mới bắt đầu)

15) Trường hợp khai thác hiệu quả (playbooks)

15.1 Daily/Weekly Intel Brief (đối thủ, thị trường, sản phẩm)

15.2 Lead Gen vận hành (ICP → enrich → score → dedupe → export)

15.3 Content Factory có kiểm soát (research → outline → draft → review)

15.4 Browser Automation cho tác vụ lặp (nhưng tránh rủi ro)

15.5 Forecasting/Prediction Engine (calibrated, có scoring)

15.6 Social Media Autopilot (nhưng có approval queue)

15.7 “Agent fleet” cho team (RBAC + channel policies + audit)

15.8 IDE integration: dùng OpenFang như “đầu não” qua MCP

15.9 Drop-in OpenAI API (để tái dùng tooling hiện có)

15.10 Ops/Monitoring loop (metrics + audit + channel alerts)

15.11 Event-driven Hand: xử lý hoá đơn/inbox tự động (webhook/file → extract → validate → export)

15.12 Clip Hand (Content Creation) — “đổi long-form thành shorts” theo pipeline nhiều phase

15.13 Lead Hand (Data Intelligence) — “mỗi ngày có lead đủ chuẩn”

15.14 Collector Hand (OSINT Intelligence) — “monitor đối thủ/keyword 24/7”

15.15 Predictor Hand (Calibrated Forecasting) — “dự báo có đo độ đúng”

15.16 Researcher Hand (Deep Autonomous Research) — “report có trích dẫn”

15.17 Twitter Hand (Social Media Management) — “autopilot nhưng phải duyệt”

5.2 Patterns khai thác Hands (từ `openfang.sh/docs/hands`)

16) Best Recipes (Cookbook theo docs `openfang.sh`)

16.1 Download (`/download`) — chọn cách cài đúng nhất

16.2 Installer scripts (`/install`, `/install.ps1`) — hiểu để tránh “cài mù”

16.3 Getting Started (`/docs/getting-started`) — đường ngắn nhất để chạy được việc

16.4 Hands (`/docs/hands`) — “primitive ăn tiền” của OpenFang

16.5 Architecture (`/docs/architecture`) — mental model để debug nhanh

16.6 Configuration (`/docs/configuration`) — chỉnh đúng 20% field ăn 80% giá trị

16.7 Security (`/docs/security`) — đọc để khỏi tự biến mình thành RCE-as-a-service

16.8 Providers (`/docs/providers`) — chọn model/provider “đúng bài”

16.9 Channel Adapters (`/docs/channel-adapters`) — đưa agent vào “nơi bạn đọc”

16.10 Agent Templates (`/docs/agent-templates`) — “đội hình” 30 agents có tier rõ ràng

16.11 Skill Development (`/docs/skill-development`) — thêm tool theo cách an toàn

16.12 Workflows (`/docs/workflows`) — pipeline multi-agent reproducible

16.13 MCP & A2A (`/docs/mcp-a2a`) — interop đúng chuẩn công nghiệp

16.14 API Reference (`/docs/api-reference`) — automation đúng cách

16.15 CLI Reference (`/docs/cli-reference`) — CLI là “đầu điều khiển”

16.16 Desktop (`/docs/desktop`) — “agent OS đóng gói” như app

16.17 Troubleshooting (`/docs/troubleshooting`) — chẩn đoán theo thứ tự đúng