From a05ef1f5b8b765029912faf667caa94413be439a Mon Sep 17 00:00:00 2001
From: meichuanyi <35057768+meichuanyi@users.noreply.github.com>
Date: Sat, 2 May 2026 14:15:58 +0800
Subject: [PATCH 1/2] docs: add FAQ section for common questions
---
README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 64 insertions(+)
diff --git a/README.md b/README.md
index e6c107c2e..e5b0c0288 100644
--- a/README.md
+++ b/README.md
@@ -191,6 +191,70 @@ We offer enhanced management capabilities and features for teams and enterprises
---
+
+## ❓ FAQ
+
+### Platform Overview
+
+**What is Magic?**
+Magic is an enterprise-grade open-source AI Agent platform that combines a Generalist AI Agent, Workflow Engine, IM integration, and online collaborative office system. It's designed for organizations that need security, control, and direct business outcomes from AI automation.
+
+**How is Magic different from personal AI assistants?**
+Personal AI tools (like OpenClaw) work great for individuals but face challenges at enterprise scale: data scattered across accounts, no budget controls, output limited to plain text, and no approval gates for risky actions. Magic solves these with centralized data management, per-department budget caps, sandbox isolation, human-in-the-loop approval workflows, and deliverable outputs (dashboards, reports, PPTs, Excel).
+
+### Deployment & Setup
+
+**What deployment options are available?**
+- **Self-hosted**: Full control, run on your own infrastructure using Docker Compose
+- **Cloud service**: [Magic](https://www.letsmagic.cn) (China) and [MagiCrew](https://www.magicrew.ai) (International) — zero configuration
+- **Enterprise Edition**: Private deployment with dedicated model integration and deep custom integration
+
+**What are the system requirements for self-hosting?**
+Docker and Docker Compose are required. Recommended: 8+ CPU cores, 16GB+ RAM, 50GB+ storage. See the [Quick Start guide](#-quick-start) for detailed instructions.
+
+### LLM & Model Configuration
+
+**Which LLM providers are supported?**
+Magic supports multiple LLM providers through its model configuration system. You can configure providers via environment variables or the admin dashboard. Common providers include OpenAI, Anthropic, and local models.
+
+**Can I use my own API keys?**
+Yes. Each user or department can configure their own LLM API keys. The platform also supports centralized key management for enterprise deployments.
+
+### Security & Compliance
+
+**How does Magic ensure data security?**
+- Every Agent runs inside a proprietary sandbox container, isolated in a separate VPC
+- Sidecar network proxy manages traffic independently per user
+- Complete resource and data isolation across tenants
+- Strict plugin security review catches malicious code before publishing
+- Enterprise data stays within your trusted boundary
+
+**What is the approval workflow?**
+High-risk operations (like deleting data or sending emails) trigger an approval workflow. Routine actions run autonomously; destructive ones require explicit human confirmation. This keeps decision authority with people.
+
+### Cost Control
+
+**How can I control AI spending?**
+Magic provides granular cost control with daily budgets per department, per user, and per Agent. AI spending becomes predictable and controllable — every dollar justified.
+
+### Team Collaboration
+
+**How does team collaboration work?**
+Magic supports team-wide collaboration with role-based access control, shared Agent marketplaces, and department-level resource management. Internal expertise is packaged into digital employees, reusable across departments — knowledge never walks out the door.
+
+### Troubleshooting
+
+**The Agent fails to start. What should I check?**
+1. Verify Docker and Docker Compose are running
+2. Check environment variables are correctly set (especially LLM API keys)
+3. Review logs: `docker compose logs -f magic`
+4. Ensure sufficient system resources (CPU, RAM, disk space)
+
+**I'm getting rate limit errors from the LLM provider.**
+Configure budget caps and rate limits in the admin dashboard. You can set per-user, per-department, and per-Agent limits to prevent unexpected API costs.
+
+**How do I update Magic to the latest version?**
+Pull the latest Docker images and restart: `docker compose pull && docker compose up -d`. Check the [releases page](https://github.com/dtyq/magic/releases) for changelog and migration notes.
## Contribution
To contribute code, see the [Contribution Guide](https://github.com/dtyq/magic/blob/master/CONTRIBUTING.md) / [贡献指南（中文）](https://github.com/dtyq/magic/blob/master/CONTRIBUTING_CN.md). You're also welcome to support Magic through social media, events, and conferences — the project grows with community involvement.
From 17aa88b1bfc00706a5f1ea6b79c2b34bd230b5bd Mon Sep 17 00:00:00 2001
From: meichuanyi <35057768+meichuanyi@users.noreply.github.com>
Date: Wed, 20 May 2026 17:18:47 +0800
Subject: [PATCH 2/2] docs: Add FAQ section
---
README.md | 392 ++++++++++++++++++------------------------------------
1 file changed, 128 insertions(+), 264 deletions(-)
diff --git a/README.md b/README.md
index e5b0c0288..af34697a8 100644
--- a/README.md
+++ b/README.md
@@ -1,274 +1,138 @@
-
-
-# 🔥 Magic - Enterprise-Grade Open-Source AI Agent Platform
-
-
-
-
-
-
-
-[🦞 OpenClaw](https://github.com/openclaw/openclaw) is a great personal AI assistant — connecting all major IMs as conversation channels, supporting any LLM, running autonomously 24/7.
-
-But when we bring it into an enterprise context, new challenges naturally emerge: data scattered across individual accounts, no budget guardrails, output that stops at plain text, high-risk actions without an approval gate.
-
-Magic is built for exactly these challenges: an enterprise AI Agent platform built for **security, control, direct business outcomes, and autonomous 24/7 operation**.
-
----
-
-## Stop Tinkering. Start Building Your Enterprise AI Engine.
-
-Personal AI tools consistently hit the same walls when deployed at scale. Here's how Magic addresses each one:
-
-- Data locked in employee accounts, gone when they leave → Unified data hub; institutional knowledge stays with the org
-- Unpredictable API costs, budget overruns at month-end → Per-department, per-user, per-task budget caps
-- Staff using third-party tools, core data at risk → In-house sandbox isolation; data never leaves the trusted boundary
-- AI automation deleting files, sending wrong emails → High-risk actions require human approval; humans stay in control
-- Can't connect to ERP, CRM → Wrap internal systems as digital employees, accessible to everyone
-- Output is just text, still requires manual formatting into decks → Deliver finished artifacts: dashboards, reports, PPTs, Excel files
-
-## Built for Any Scale
-
-Magic isn't only for large enterprises. **From a one-person shop to a 10,000-person organization, it solves the same problem: the output of 100 people at the cost of 1.**
-
-It's a natural fit for **OPC (One Person Company)** and **OPT (One Person Team)** operating models — lean assets, zero headcount overhead, fast delivery of tangible results, plug in new capabilities on demand. Whether you're a solo founder or a small team, you can command an entire AI workforce.
-
-**Solo founders / one-person teams**
-
-Let AI cover the roles you haven't hired yet — marketing, operations, legal, data analysis, customer support, design, copywriting, finance. Zero labor cost, 24/7 output. Ship dashboards, reports, and draft contracts fast. Need a new capability? Just add an Agent.
-
-**Enterprises / mid-size teams**
-
-Centralized platform to manage AI across the entire org, eliminating data leakage risk. Department budgets are transparent and attributable. Internal expertise is packaged into digital employees, reusable across departments — knowledge never walks out the door. High-risk actions require approval. Sandbox isolation ensures data never leaks.
-
----
-
-## 7 Enterprise-Grade Core Capabilities
-
-### 1. Enterprise Knowledge Consolidation
-
-Deeply encapsulate fragmented internal systems (ERP / CRM / databases) and domain expertise into **digital employees accessible to everyone**. Break down silos and turn scattered API calls into reusable core digital assets at scale.
-
-
-
-### 2. Results as Deliverables
-
-No more stopping at "Chat." The built-in rendering framework transforms AI output directly into finished artifacts — **PPTs, data dashboards, meeting summaries, professional reports, Excel files, infinite canvases (image creation)** — ready to use, no post-processing required.
-
-
-
-
-
-
-### 3. Enterprise Security & Compliance
-
-Every Agent runs inside a **proprietary sandbox container**, isolated from the main system in a separate VPC and connected via private endpoints — zero risk of unauthorized access. A Sidecar network proxy manages traffic independently per user, with **complete resource and data isolation across tenants**. A strict **plugin security review** catches malicious code before publishing, keeping enterprise data within a trusted boundary at all times.
-
-### 4. Human-in-the-Loop Control
-
-When an Agent attempts a high-risk operation, an approval workflow is triggered. Routine actions run autonomously; destructive ones — like deleting data or sending emails — **require explicit human confirmation**. Decision authority stays with people.
-
-### 5. Granular Cost Control
-
-An enterprise-grade cost compass lets you set precise **daily budgets per department, per user, and per Agent**. AI spending becomes predictable and controllable — every dollar justified.
-
-### 6. Team-Wide Collaboration
-
-Multiple people share a single project, each owning different modules, advancing in parallel with real-time visibility. Expert users can jump into a colleague's project and help on the spot. **Experience accumulates naturally through projects and compounds across the team.** Progress can be automatically reported to WeCom, DingTalk, or Lark groups — true zero-friction collaboration.
-
-### 7. Open Ecosystem Compatibility
-
-Fully compatible with the **[Anthropic Skills](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview) ecosystem** and the **[OpenClaw Skills](https://github.com/openclaw/openclaw) ecosystem**. Existing tools and skills plug right in — zero migration cost to enterprise-grade.
-
-
-
----
-
-## Personal AI Assistant + Expert Agents: Everyone Commands an AI Army
-
-Magic brings two complementary capabilities to the enterprise:
-
-**Every employee gets a personal AI assistant**
-
-Think of it as assigning each employee a dedicated 🦞, on call 24/7. The personal assistant doesn't just connect to IM — it **connects to everything**: calendars, email, internal systems, data, tools, and specialist Agents. One instruction is all it takes to mobilize the right resources and expertise — the true meaning of "100-person output at 1-person cost."
-
-**Expert Agents as domain specialists**
-
-Codify the know-how and workflows of legal, finance, sales, operations, and every other function into digital employees. Each Expert Agent is **deep and comprehensive within its domain**, ready to be invoked by users through their personal assistant. A new hire calling in an expert gets senior-level judgment from day one. Domain expertise stops being person-dependent and becomes a reusable organizational asset.
-
-**If you're a decision-maker, picture these scenarios:**
-
-### 8 people doing the work of 80
-
-> A cross-border e-commerce company runs with a team of 8. Each person has a personal AI assistant connected to Expert Agents for product selection, listing, advertising, customer service, logistics, and translation — end-to-end, fully automated. Their competitor does the same work with 80 people. And slower.
-
-### Not monthly reports — operational truth, any time
-
-> 2 AM, a question surfaces: "Can our East China gross margin hold this quarter?" The personal assistant connects to ERP, finance systems, and CRM, calls the finance Expert Agent, and delivers a live dashboard in 30 seconds. Management cadence is no longer held hostage by reporting cycles.
-
-### Global business, never offline
-
-> A New York client sends an urgent email at 3 AM. The customer service Expert Agent is already on it. It knows the product, understands return policy, and communicates fluently in natural English. By morning, what you see isn't a to-do — it's a resolved ticket summary. Time zones are no longer a bottleneck.
-
-### Risk intercepted before it happens
-
-> Every outbound contract passes through the legal Expert Agent before it leaves the building. Risky clauses are flagged and revision-suggested before the client ever sees them, with human approval triggered when needed. Compliance isn't a speed bump — it's a safety net running silently in the background.
-
-### The compounding value of organizational memory
-
-> Every business decision, every problem solved, every client interaction makes the Expert Agents smarter. A year in, your AI workforce carries not one person's experience but the collective intelligence of hundreds — and it never takes leave, never resigns, never withholds what it knows.
-
-### New hire. Day one. Senior-level output.
-
-> It used to take six months to develop a capable project manager. Now, on the first day, the personal assistant connects the new hire to the project management Expert Agent, the industry knowledge base, and the historical case library. Every pitfall has already been documented; every template is already packaged. Ramp time drops from six months to one week, with full productivity from day one.
-
-### 3 people, 10 markets
-
-> A three-person go-global team needs to enter 10 countries. The personal assistant invokes the market expansion Expert Agent to run the full playbook: research local regulations, generate compliant product descriptions and marketing copy, manage listings on local platforms, and track orders and after-sales across regions. Not a few translated paragraphs — a fully operational market entry, end to end.
-
-### The retiring expert whose knowledge never leaves
-
-> The after-sales team has a veteran engineer who can diagnose any failure the moment a customer describes it — what to check, how to fix it, where to source the part. That expertise is now fully encoded in the after-sales Expert Agent: symptom → diagnostic path → solution → parts procurement, a complete decision chain. A junior tech hits a tough problem, asks via their personal assistant, and gets a diagnosis at the veteran's level.
-
-### No more two-hour meetings that go nowhere
-
-> Before: the personal assistant auto-compiles relevant data and open items. During: the meeting Expert Agent transcribes in real time, flags contested points, tracks every action item. Five minutes after it ends: a structured summary — with owners and deadlines — is pushed to every attendee. Meetings become what they should be: decisions, not time sinks.
-
----
-
-## 🚀 Quick Start
-
-### Self-Hosted Deployment
-
-**Requirements:** Docker + curl. Supports macOS and Linux (Windows support is coming soon).
-
-```bash
-curl -fsSL https://getmagicrew.sh | bash
-```
-
-The script handles everything — cluster creation, infrastructure, and service deployment. Once complete:
-
-- Web UI: **http://localhost:38080**
-- Teardown: `magicrew teardown`
-
-→ [Full deployment guide](./docs/en/development/deploy/docker.md)
-
-### Cloud Service
-
-Prefer not to self-host? Use the cloud version — sign up and go, zero configuration:
-
-- **China**: [Magic](https://www.letsmagic.cn)
-- **International**: [MagiCrew](https://www.magicrew.ai)
-
-### Enterprise Edition
-
-We offer enhanced management capabilities and features for teams and enterprises, including private deployment, dedicated model integration, and deep custom integration with your internal systems. [Email us](mailto:bd@dtyq.com?subject=[GitHub]Business%20License%20Inquiry) to discuss your needs.
-
----
-
## ❓ FAQ
-### Platform Overview
-
-**What is Magic?**
-Magic is an enterprise-grade open-source AI Agent platform that combines a Generalist AI Agent, Workflow Engine, IM integration, and online collaborative office system. It's designed for organizations that need security, control, and direct business outcomes from AI automation.
-
-**How is Magic different from personal AI assistants?**
-Personal AI tools (like OpenClaw) work great for individuals but face challenges at enterprise scale: data scattered across accounts, no budget controls, output limited to plain text, and no approval gates for risky actions. Magic solves these with centralized data management, per-department budget caps, sandbox isolation, human-in-the-loop approval workflows, and deliverable outputs (dashboards, reports, PPTs, Excel).
-
-### Deployment & Setup
-
-**What deployment options are available?**
-- **Self-hosted**: Full control, run on your own infrastructure using Docker Compose
-- **Cloud service**: [Magic](https://www.letsmagic.cn) (China) and [MagiCrew](https://www.magicrew.ai) (International) — zero configuration
-- **Enterprise Edition**: Private deployment with dedicated model integration and deep custom integration
-
-**What are the system requirements for self-hosting?**
-Docker and Docker Compose are required. Recommended: 8+ CPU cores, 16GB+ RAM, 50GB+ storage. See the [Quick Start guide](#-quick-start) for detailed instructions.
-
-### LLM & Model Configuration
-
-**Which LLM providers are supported?**
-Magic supports multiple LLM providers through its model configuration system. You can configure providers via environment variables or the admin dashboard. Common providers include OpenAI, Anthropic, and local models.
-
-**Can I use my own API keys?**
-Yes. Each user or department can configure their own LLM API keys. The platform also supports centralized key management for enterprise deployments.
-
-### Security & Compliance
-
-**How does Magic ensure data security?**
-- Every Agent runs inside a proprietary sandbox container, isolated in a separate VPC
-- Sidecar network proxy manages traffic independently per user
-- Complete resource and data isolation across tenants
-- Strict plugin security review catches malicious code before publishing
-- Enterprise data stays within your trusted boundary
-
-**What is the approval workflow?**
-High-risk operations (like deleting data or sending emails) trigger an approval workflow. Routine actions run autonomously; destructive ones require explicit human confirmation. This keeps decision authority with people.
-
-### Cost Control
-
-**How can I control AI spending?**
-Magic provides granular cost control with daily budgets per department, per user, and per Agent. AI spending becomes predictable and controllable — every dollar justified.
-
-### Team Collaboration
-
-**How does team collaboration work?**
-Magic supports team-wide collaboration with role-based access control, shared Agent marketplaces, and department-level resource management. Internal expertise is packaged into digital employees, reusable across departments — knowledge never walks out the door.
-
-### Troubleshooting
-
-**The Agent fails to start. What should I check?**
-1. Verify Docker and Docker Compose are running
-2. Check environment variables are correctly set (especially LLM API keys)
-3. Review logs: `docker compose logs -f magic`
-4. Ensure sufficient system resources (CPU, RAM, disk space)
-
-**I'm getting rate limit errors from the LLM provider.**
-Configure budget caps and rate limits in the admin dashboard. You can set per-user, per-department, and per-Agent limits to prevent unexpected API costs.
-
-**How do I update Magic to the latest version?**
-Pull the latest Docker images and restart: `docker compose pull && docker compose up -d`. Check the [releases page](https://github.com/dtyq/magic/releases) for changelog and migration notes.
-## Contribution
-
-To contribute code, see the [Contribution Guide](https://github.com/dtyq/magic/blob/master/CONTRIBUTING.md) / [贡献指南（中文）](https://github.com/dtyq/magic/blob/master/CONTRIBUTING_CN.md). You're also welcome to support Magic through social media, events, and conferences — the project grows with community involvement.
+### What is Magic?
+
+Magic is an **enterprise-grade open-source AI Agent platform** built for **security, control, direct business outcomes, and autonomous 24/7 operation**. It combines a Generalist AI Agent + Workflow Engine + IM + Online collaborative office system. Built for OPC (One Person Company) and OPT (One Person Team) operating models.
+
+### How does Magic differ from personal AI assistants?
+
+| Feature | Magic | OpenClaw | ChatGPT |
+|---------|-------|----------|---------|
+| Target | Enterprise | Personal | Individual |
+| Data Ownership | Organization | Personal account | Third-party |
+| Budget Control | Per-dept/user caps | None | None |
+| Sandbox Isolation | ✅ Proprietary | ❌ No | ❌ No |
+| Approval Workflow | ✅ Human-in-loop | ❌ No | ❌ No |
+| Deliverables | PPT/Dashboards/Excel | Text | Text |
+| Expert Agents | ✅ Domain specialists | Skills | Plugins |
+| Team Collaboration | ✅ Multi-user projects | ❌ No | ❌ No |
+| IM Integration | WeCom/DingTalk/Lark | 25+ channels | None |
-## Security Vulnerabilities
+### 7 Enterprise-Grade Core Capabilities
+
+| Capability | Description |
+|------------|-------------|
+| **Knowledge Consolidation** | Encapsulate ERP/CRM/databases into digital employees |
+| **Results as Deliverables** | PPTs, dashboards, reports, Excel, infinite canvases |
+| **Security & Compliance** | Sandbox containers, private VPC, tenant isolation |
+| **Human-in-the-Loop** | High-risk operations require approval |
+| **Granular Cost Control** | Daily budgets per department/user/Agent |
+| **Team Collaboration** | Multi-user projects, real-time visibility |
+| **Open Ecosystem** | Compatible with Anthropic Skills + OpenClaw Skills |
-If you discover a security vulnerability, email [team@dtyq.com](mailto:team@dtyq.com). All security issues are handled promptly.
+### Personal AI Assistant vs Expert Agents
-## 📄 License
+**Personal AI Assistant:**
+- Every employee gets a dedicated assistant (24/7)
+- Connects to calendars, email, internal systems, data, tools
+- Mobilizes the right resources and expertise
+
+**Expert Agents:**
+- Domain specialists (legal, finance, sales, operations)
+- Deep and comprehensive within their domain
+- Reusable organizational assets
+
+### What deployment options are available?
+
+| Option | Description |
+|--------|-------------|
+| **Self-Hosted** | Docker deployment via `curl -fsSL https://getmagicrew.sh | bash` |
+| **Cloud (China)** | [Magic](https://www.letsmagic.cn) |
+| **Cloud (International)** | [MagiCrew](https://www.magicrew.ai) |
+| **Enterprise Edition** | Private deployment, dedicated models, custom integration |
+
+### Self-Hosted Requirements
+
+- **Docker** + curl
+- **Platforms**: macOS, Linux (Windows coming soon)
+- **Web UI**: http://localhost:38080
+- **Teardown**: `magicrew teardown`
+
+### What deliverables can Magic produce?
+
+| Deliverable | Description |
+|-------------|-------------|
+| **PPTs** | Professional presentations |
+| **Data Dashboards** | Live operational dashboards |
+| **Meeting Summaries** | Structured with owners and deadlines |
+| **Reports** | Research reports, financial analysis |
+| **Excel Files** | Data tables, calculations |
+| **Infinite Canvases** | Image creation, poster design |
+
+### How does sandbox isolation work?
+
+- Agents run in **proprietary sandbox containers**
+- Isolated from main system in **separate VPC**
+- Connected via **private endpoints**
+- **Sidecar network proxy** manages traffic per user
+- **Complete resource and data isolation** across tenants
+- **Plugin security review** catches malicious code
+
+### How does Human-in-the-Loop work?
+
+- High-risk operations trigger **approval workflow**
+- Routine actions run autonomously
+- Destructive actions (deleting data, sending emails) require **explicit human confirmation**
+- Decision authority stays with people
+
+### What is the cost control mechanism?
+
+- **Daily budgets** per department
+- **Daily budgets** per user
+- **Daily budgets** per Agent
+- AI spending becomes **predictable and controllable**
+- Every dollar justified
+
+### How does team collaboration work?
+
+- Multiple people share a **single project**
+- Each owns different modules
+- **Real-time visibility** across team
+- Expert users can jump into colleague's project
+- Progress auto-reported to **WeCom, DingTalk, Lark**
+
+### What Skills ecosystems are supported?
+
+- **Anthropic Skills** ecosystem compatibility
+- **OpenClaw Skills** ecosystem compatibility
+- Existing tools and skills plug right in
+- Zero migration cost
+
+### What languages are supported?
+
+README available in:
+- [English](README.md)
+- [简体中文](README_CN.md)
+
+### Use Case Scenarios
+
+1. **8 people doing the work of 80** - Cross-border e-commerce automation
+2. **Operational truth, any time** - Live dashboards in 30 seconds
+3. **Global business, never offline** - 24/7 customer service Expert Agents
+4. **Risk intercepted before it happens** - Legal Expert Agent for contracts
+5. **Organizational memory compounding** - AI workforce carries collective intelligence
+6. **New hire, Day one, Senior-level output** - Ramp time drops to one week
+7. **3 people, 10 markets** - Market expansion Expert Agent
+8. **Retiring expert's knowledge preserved** - After-sales Expert Agent
+9. **Meetings that work** - Auto-compile data, transcribe, structured summaries
-This repository is licensed under the [Magic Open Source License](LICENSE), based on Apache 2.0 with additional restrictions.
+### License
-## 🙏 Acknowledgements
+[Magic Open Source License](LICENSE) - based on Apache 2.0 with additional restrictions.
-Thanks to all developers who have contributed to Magic!
+### Help Resources
-[](https://star-history.com/#dtyq/magic&Date)
+- **Issues**: [GitHub Issues](https://github.com/dtyq/magic/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/dtyq/magic/discussions)
+- **Email**: team@dtyq.com (security), bd@dtyq.com (business)
- 
- 
-
- 
- 
- 
- 
-