Admin guide · Magento & Mage-OS

Every Mago setting, screen by screen

For whoever sets up Mago in the Magento admin. No server access needed. Where each setting lives, what it does and what we recommend, with screenshots from the Mago demo shop.

Only backend access needed Your AI provider key About 15 minutes
keep default is right for most shops change set this for your shop optional your call

Find the settings

Stores › Mago Assistant

Everything Mago has in the admin sits in its own block under Stores: Statistics, Conversations, Answer Feedback, Skills & Permissions and Configuration. The AI provider and key live one level up, in the shared Mage-OS AI settings.

Stores menu in the Magento admin with the Mago Assistant block: Statistics, Conversations, Answer Feedback, Skills and Permissions, Configuration
“Use system value”. Most fields show this checkbox. Untick it to change the field, tick it again to go back to Mago’s default. Click Save Config at the top of the page when you are done.

Add your AI provider and API key

Stores › Configuration › Mage-OS › AI Configuration › Services
  1. Click a provider below Configured Services, for example Anthropic or OpenAI. A new row appears.
  2. Paste your API Key. After saving it only shows as dots.
  3. Pick a Model. Choose a current chat model, not an image, audio or embedding model. Use ↻ to refresh the list.
  4. Click Save Config, then Test Connection. It has to answer before Mago can.
  5. Optional: click the pencil to give the service a name your team recognises, such as “OpenAI production”.
AI Configuration services: OpenAI service row with API key field, model selector and Test Connection button, plus buttons to add other providers

Greyed-out providers (Azure OpenAI, Gemini, DeepSeek, Ollama and others) say package not installed. A developer has to install them once; the box underneath shows the exact command to send them.

Use a key for this shop only and set a monthly spending limit on the provider’s own dashboard. That gives you a hard ceiling on cost, whatever happens in the admin.

Usage Tracking

same page, below Services
Report
optional
Link to the AI Token Usage report: tokens used by every module that uses this AI layer, not only Mago.
Enable Usage Tracking
keep
Yes. Needed for the cost figures in reports and in Mago’s Statistics.
Raw / Daily Usage Retention
keep
How long detailed (30 days) and daily totals (730 days) are kept. Only shown while tracking is on.
Cleanup Cron Schedule
keep
When old usage rows are removed. Default: daily at 03:00.
Usage Tracking settings with report link, enable switch, retention fields and cleanup schedule

Switch Mago on and pick the service

Stores › Mago Assistant › Configuration › General and API Settings
General group with version and Enabled set to Yes
API Settings with AI Service on Automatic, Max Tokens and Enable Streaming

General

Version
info
The installed Mago version. Handy when you report a problem.
Enabled
change
Yes. Mago is off after installation. Reload the admin afterwards and the Mago icon appears at the top right.

API Settings

AI Service store view
keep
Automatic uses the first working service from AI Configuration. Pick one explicitly only when you run several, for example a different one per store view.
Max Tokens
keep
Maximum length of one answer. Raise it only if long answers get cut off. Default 4096.
Enable Streaming
keep
Yes: answers appear while Mago writes them.

Language, system prompt and look

Stores › Mago Assistant › Configuration › Chat Settings
Chat Settings with Response Language on Auto-detect and an example system prompt filled in

Chat Settings

mostly per store view
Response Language
change
Auto-detect, so everyone gets answers in the language they write in. Choose a fixed language only when the whole team works in one.
System Prompt
change
Sent with every conversation. The single setting that improves answers most. Write a few lines about your shop: what you sell, your store views and languages, prices incl. or excl. VAT, tone of voice and house rules. Untick Use system value first.
Answer Widgets
keep
Yes: answers as stat cards, charts and tables instead of long text.
Max Tool Iterations default scope only
keep
How many lookups Mago may chain for one question. 10 handles comparisons and multi-step jobs.
Assistant Name
optional
Rename the assistant, for example after your shop.
Accent Color / Text Color on Accent
optional
Match the chat panel to your brand. Keep enough contrast between the two.

Example system prompt

We are Example Outdoor, a Dutch webshop for hiking and camping gear.
Store views: NL (default, Dutch) and BE-FR (French). Prices include VAT.
Write product texts in a friendly, practical tone, using "je" in Dutch.
Never promise delivery times in product texts.
When a request could differ per store view, ask which one I mean.

Voice input

Stores › Mago Assistant › Configuration › Voice Input
Voice Input group with Enabled set to No
Enabled
optional
Adds a microphone button next to Send. The browser turns speech into text, so audio goes to the browser maker (Google for Chrome), not to Mago. Off by default. Each admin should set Account Settings › Interface Locale to the language they speak.

Tools

Stores › Mago Assistant › Configuration › Tools
Tools group: Max Tool Response Tokens, Allow reindexing, Customer E-mail Interval
Max Tool Response Tokens
keep
Trims very large lookup results so one big list cannot crowd out the conversation. Default 4000.
Allow reindexing
keep
No, unless your developer confirms the background queue (async.operations.all) runs. A full reindex can load a large shop for a long time.
Customer E-mail Interval
keep
Mago e-mails a customer about an order at most once per 60 minutes, so a bulk request cannot flood an inbox. Never set 0 on a live shop.

Add-ons

Stores › Mago Assistant › Configuration › Add-ons
Add-ons group with Show new add-ons
Show new add-ons
optional
Shows the newest Mago add-ons in the chat panel. When an admin opens the chat, it fetches a public list from askmago.com and keeps it for a week. The request carries no information about your shop. Off by default.

Answers from the official docs

Stores › Mago Assistant › Configuration › Documentation
Documentation group: enable documentation grounding, source repository, branch, results per search, sync schedule
Enable documentation grounding
change
Yes. “How do I…” questions are then answered from the official Magento admin docs, with a link to the page used. The first index runs at the next scheduled sync; to start it right away, ask a developer to run bin/magento mago:docs:index --force.
Source repository / branch
keep
Where the docs come from. Default: the Mage-OS mirror of the Magento admin documentation, branch main. A developer can pin a commit instead.
Results per search
keep
How many doc pages Mago reads per question. 5 is a good balance; higher costs more.
Sync schedule
keep
How often the docs are refreshed. Default: monthly.

Privacy and debug

Stores › Mago Assistant › Configuration › Privacy & Data Retention and Debug & Logging
Privacy and Data Retention: Conversation History Retention 90 days
Debug and Logging: Debug Mode No, Payload Retention 30 days
Conversation History Retention
change
Chats older than this are deleted every night, together with their answer feedback and privacy codes. Match it to your privacy policy. Default 90 days. 0 keeps everything forever.
Debug Mode
change
No on a live shop. With debug on, full AI requests and answers are stored. Turn it on briefly only when you are chasing a problem.
Payload Retention
keep
How long those debug records are kept. Default 30 days. Token statistics stay.
Privacy mode is always on. Customer names, e-mail addresses, phone numbers, street addresses and review texts never go to the AI provider. You still need a data processing agreement with your provider. How Mago protects your data →

KVK Lookup

Stores › Mago Assistant › Configuration › KVK Lookup (only with the KVK add-on)
KVK Lookup group: KVK Number Attribute and Cache Lifetime
KVK Number Attribute
optional
The attribute code where your shop stores the KVK number. Mago looks at the order’s billing address first, then the customer. Leave empty if you don’t store it; then ask with the number itself.
Cache Lifetime (days)
keep
The KVK open data allows one request per minute, so answers are cached. Default 7 days.

Add-ons can add their own block here. Add-ons that call an outside service, such as the KVK and VIES lookups, need a grant on the Skills & Permissions screen before an admin can look up a number they type in. Looking up the company behind an order only needs the right to view orders.

Who may use Mago: user roles

System › Permissions › User Roles › a role › Role Resources

Mago works as the admin who is chatting. It can only see and change what that admin’s role allows elsewhere in the admin. Set Resource Access to Custom and tick what each role gets under Mago Assistant.

Role resources tree with Mago Assistant: Read Operations, Write Operations, Manage Conversations, Answer Feedback, View Statistics, Skills and Permissions, Reindex All Indexers
ResourceGives access toShop managerTeam member
Mago AssistantThe chat itselfYesYes
Read OperationsAsking questions about sales, products, customers, settingsYesYes
Write OperationsLetting Mago make changes, always after AllowYesIf needed
Manage ConversationsReading every admin’s chats; deleting them is a separate tickYesNo
Answer FeedbackReviewing answers the team marked as wrongYesNo
View StatisticsUsage and cost dashboardYesNo
Skills & PermissionsViewing and changing rights per user and skillYesNo
Reindex All IndexersLetting Mago run a full reindexOnly if neededNo
Mago Assistant ConfigurationThe Mago configuration screens (under Stores › Settings › Configuration)YesNo
Administrators with “All” resource access get everything automatically. These choices matter for every other role.

Fine-tune per person: Skills & Permissions

Stores › Mago Assistant › Skills & Permissions › Edit

The list shows every skill with its category and whether it reads or writes. Click Edit on a skill to set, per admin user: Default (ACL), Read Only, Read & Write or Disabled. Default means the user role decides. Add-on skills that call an outside service show Default (not granted) instead: nobody gets those until you grant them here.

Use it for exceptions, for example a content editor who may let Mago write product texts (content_generator) but not change settings (config_writer).

Skills and Permissions list with skill names, descriptions, categories and read or write type
Edit Skill content_generator with a permission dropdown per admin user

Statistics, conversations and feedback

Stores › Mago Assistant › Statistics / Conversations / Answer Feedback
  • Statistics: requests, tokens and estimated cost per day, per user and per skill. Check it weekly in the first month.
  • Conversations: every chat with who had it and what it cost. Read a few to learn what your team asks.
  • Answer Feedback: answers marked as not helpful. The fastest way to find what to add to the system prompt.
Mago Assistant Statistics: requests, tokens, estimated cost, daily trend, top users and popular skills
For your team

Example questions, by area

Mago answers in the language you write in. Name the period and the store view for the best answer. Every change shows an Allow / Not now card first.

Sales & reports

  • Compare revenue in October with September
  • Top 10 products this quarter
  • Which products were refunded most?

Products & catalog

  • Why is product MH03 not visible in the shop?
  • Which categories have no live products?
  • Create a simple product for…

Stock

  • Which products are running low on stock?
  • Show dead stock older than 90 days
  • Stock of SKU 24-WG080 per source

Orders & customers

  • Show order #100004521
  • How many new customers signed up last month?
  • Who are our top spenders?

Marketing

  • Which coupon codes are active?
  • Create a 10% code for the newsletter
  • List the catalog price rules

Content & SEO

  • Write a product description for the Hero Hoodie
  • Translate it for the French store view
  • Create a redirect from /sale to /outlet

Reviews

  • Which reviews are waiting for approval?
  • Approve the 5-star reviews from this week

Settings & system

  • Is guest checkout enabled?
  • Are any cron jobs failing?
  • Which version of the Mollie module is installed?

How-to

  • How do I set up a cart price rule?
  • Take me to the shipping settings
  • /cache status