Tutorials, FAQ, and troubleshooting — find the answers you need here
First time here? Check the beginner tutorials
No matching questions found
Try different keywords, or browse the categories below
From download to in-game in just a few steps
Download the installer from the official download page, then double-click to install. The launcher will open automatically once installation is complete.
Go to the API page in the launcher, enter your LLM provider's address, API Key, and model name, then click "Apply All".
Not sure what an API is? See API questions below
Go to the Profile page. First fill in "About Me" with your own details, then go to "My Companion" to create and customize your companion character — appearance, personality, backstory, and more.
Go back to the home page and click any game icon to open its panel. Click "Auto-install mod files" in the top bar to complete setup. The server starts automatically and settings sync on their own — just launch the game and they'll be waiting for you.
Common questions about API addresses, keys, and model selection
An API (Application Programming Interface) is a "communication channel" — KOA sends what you say through this channel to a large language model (like DeepSeek, GPT, or Gemini), which processes it and sends your companion's reply back.
Think of it this way: KOA is their body, and the API is their brain connection. Without an API, they can't think.
KOA requires you to provide your own API because each conversation consumes computing resources from the model provider (billed per token), and you pay the provider directly. The upside: you're free to choose any model you like, and your conversations only travel through your own API channel — never through KOA's servers.
You'll need to sign up at an LLM provider's website and create an API Key in their dashboard. Common providers:
Once registered, you'll have two things: an API address (the provider's endpoint URL) and an API Key (a secret string). Enter both in the KOA launcher's API page.
An API Key is your "pass" — a string of letters and numbers (like sk-xxxxxxxx). The provider uses it to identify who is calling the API and charges your account accordingly.
Keep your Key safe — don't share it with anyone, or they could use up your balance.
In most cases, no. When you select a provider on KOA's API page, the address is auto-filled.
You only need to enter your API Key and choose a model name.
You'd only need to manually change the address if you're using a niche provider or a self-hosted proxy.
Consider cost-effectiveness and language quality:
Note: To send photos in the virtual phone, use "Look Together" screen sharing, or send images in offline scenes, you'll need a model with multimodal (image recognition) capability. The API page lets you save multiple configurations and switch anytime.
Different models have varying "personality expressiveness" — try a few to find the one you like best. KOA lets you switch models at any time without losing memories or settings.
Costs depend on the model you choose and how often you chat. With DeepSeek, for example, daily casual chatting typically costs just a few cents.
KOA has a built-in memory summarization system that periodically compresses conversation history to control token usage, so the context never grows endlessly.
We recommend starting with a small top-up to get a feel for your usage, then adding more as needed.
Launcher installation, game mod setup, and system requirements
KOA itself is lightweight and won't consume many resources. The local speech recognition model is also bundled with the launcher.
It's very simple — open the panel for the game you want, then click "Auto-install mod files" in the top bar. The launcher will automatically locate your game directory and complete the installation.
If you use a third-party launcher (like PCL2, HMCL, etc.), you may need to manually select your game directory. See the instructions page inside the launcher for details.
When launching the game, make sure to select the NeoForge profile — not vanilla 1.21.1.
Multiplayer dedicated servers are not currently supported — you'll need to host a local game.
You can get an activation code by supporting us on Aifadian. It's a one-time purchase with lifetime updates.
Once you receive your code, enter it in the launcher to activate.
The launcher has an auto-update feature: when a new version is detected, it will prompt you and install with one click — no manual download needed.
In-game mods are also automatically checked and updated to the latest version on launch.
Controls, companion behavior, and in-game interactions
Text: Press T to open the chat box and type your message. Any message that doesn't start with / will be heard by your companion.
Voice: Two trigger modes are supported — "Smart Detection" (automatically recognizes when you speak) and "Push to Talk" (hold V). You can choose the trigger mode and recognition language on the API page. Recognition runs locally — no extra key or network request needed.
Check the following in order:
/koa summon to manually summon themMinecraft: Shift + right-click on them to open their inventory. You can store items, equip armor, and give gifts. Press K to open the in-game management panel (or right-click them with an empty hand) — summon, stay, and more are all accessible from there.
Don't Starve Together: Press B to open their backpack (rebindable in mod config); right-click on them also works. Hold food and right-click on them to feed them.
Stardew Valley: Press F7 to open the in-game panel where you can view their inventory, pause LLM calls, or put them on standby. If your keyboard lacks F7, open Mods\WhispersMod\config.json and change "CompanionPanelKey" to a key that works for you.
You can upload a skin image directly in the launcher — it will handle renaming and placement automatically.
Or do it manually: rename a standard 64x64 MC skin to companion.png, place it in the .minecraft\koamc\ directory, and restart the game.
Most actions can be done by simply talking to them in natural language — no commands needed. In Minecraft, you can also press K to open the in-game panel. Here are common commands:
/koa summon — Summon them to your side/koa stay — Have them stay in place/koa despawn — Temporarily dismiss them/koa quiet — Pause LLM calls (saves tokens)/koa strong — Cheat mode, maxed-out combat power/koa weak — Return to normal mode/koa undo_build — Undo the most recent buildCompanionship features beyond games
The virtual phone is a standalone phone window — the idea is that you and your companion stay in touch through a phone. Click "Virtual Phone" on the home page to open it.
It includes: chat (text messages), voice calls, social feed, diary, music recommendations, and more.
There are two buttons next to the input field: the kiwi button is "Queue" — it adds the message to a queue without sending, so you can write several messages before sending them all at once; the blue send button is the actual send.
If messages are stuck as pending, tap the blue button to send them all.
An immersive text narrative space where you can be with your companion without launching any game. Click "Offline Scenes" on the home page to enter.
You'll chat, interact, and live together in a shared world. You can adjust reply length, narrative perspective, and language preferences.
Yes. In-game, offline scenes, and the virtual phone all share the same memories and character settings.
Adventures in Minecraft, nights survived in Don't Starve Together, conversations in the phone — they remember it all, no matter which entry point you use.
Use KOA on the go from your phone
The mobile web app is KOA's Progressive Web App (PWA). Open app.koasystem.com in your phone's browser to use it — no app store download needed.
We recommend adding it to your home screen for a native app-like experience (fullscreen, no address bar, its own icon).
The mobile app is not free — it runs on KOA's cloud servers, which have operational costs.
However, it's currently in a free open beta, so you can experience all mobile features at no charge during this period.
For pricing after the beta, check the latest info on our Aifadian page.
No. The mobile app is a companion feature of the PC version — not a standalone product, and it won't be sold separately.
Before your first use, you need to complete these steps on your PC:
Once that's done, open app.koasystem.com on your phone, log in with the same account, and your data will sync over.
The mobile app includes KOA's core companionship features:
In-game features (Minecraft, Don't Starve Together, Stardew Valley, etc.) require the PC — the mobile app doesn't handle those. Major, complex features are PC-first.
Speech recognition (STT) and text-to-speech (TTS)
No. The speech recognition model is bundled with the launcher and runs locally — no extra key or network request required.
You can choose the recognition language and trigger mode on the API page. Two trigger modes are available: Smart Detection (automatically recognizes when you speak) and Push to Talk (hold V to speak).
If you're using the mobile version and speech recognition captures audio but produces no results, the most common cause is: the browser's built-in speech recognition (Web Speech API) depends on Google's servers, which may be unreachable from certain network environments.
The logs may show the engine registered successfully (provider set to: Browser), but actual recognition requests can't reach Google's servers.
Solutions:
Choose a text-to-speech service on the TTS page in your character settings:
Local TTS engines like GPT-SoVITS share GPU resources with your game. Running both at once can cause TTS to silently fail due to insufficient VRAM — no error message, just no audio.
Solutions: Limit TTS VRAM usage, lower your game's graphics settings, or switch to a cloud-based TTS that doesn't use your GPU.
Run into a problem? Start here
Common API errors:
Check the launcher's "Log" page for detailed error messages — the cause is usually right there.
This almost always means the microphone isn't picking up any audio: it's unplugged, plugged into the wrong jack, the system selected the wrong input device, or it's muted. When the recognition model receives a silent recording, it outputs a string of periods or punctuation — it looks broken, but it simply "heard nothing."
The launcher has a dedicated "Log" page where you can view real-time server output with category filters.
If you encounter an issue you can't resolve on your own, you can export a diagnostic package to send to the developer for support.
The launcher supports both manual one-click backup and automatic backup. Your character settings, memories, and chat history are all saved.
If you reinstall the launcher, as long as your data folder is intact, just import the backup to restore everything.
Yes — use the launcher's built-in backup and restore:
Chat history, memories, character cards, Storybook, API config, phone data, and game data will all be restored.
For more details, see the Data & Maintenance tutorial.
Open the launcher, go to the "Log" page, describe your issue, and send a diagnostic package with one click. The developer will receive your full logs and environment info to help pinpoint the problem faster.