Troubleshooting - MiniMax Agent Docs

Start with the installed version and command help to identify whether an issue is related to installation, authentication, configuration, or task execution:

mcode --version
mcode --help
mcode <command> --help

Installation and environment

Why does the shell say mcode: command not found?

Close and reopen the terminal, then run mcode --version. If the command is still missing, check that the global npm or installer directory is in PATH. On Windows, an already-open VS Code process may retain an old environment; fully restart VS Code.

Which Node.js versions are supported?

Manual installation requires Node.js 22.19.0 or later in the 22.x line, or Node.js 24, 25, or 26. The official installer prepares a compatible runtime when needed. Alpine and other musl-based Linux distributions are not currently supported by the installer.

What should I check when installation fails?

Confirm access to the MiniMax file CDN, npm registry, and Node.js download source. Some platforms may also need GitHub for native dependencies. If you use a proxy, set HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, or NO_PROXY before retrying.

How do I update or uninstall the CLI?

Run mcode update and restart the current MCode process after it completes. For an npm installation, run npm uninstall -g @minimax-ai/code. For an installer installation, use the installer or uninstall method for that installation.

What if the browser cannot open in WSL or on a remote host?

The login command starts a temporary callback service on the local loopback address and tries to open a browser with xdg-open. On Debian or Ubuntu, install the browser opener first:

sudo apt update
sudo apt install -y xdg-utils

Keep the original mcode login process running until browser sign-in finishes. For an SSH remote host, forward the callback port printed by the login command:

ssh -N -L <port>:127.0.0.1:<port> <remote-host>

Each login may use a different port; do not permanently reuse the example port.

Keep the login process running. Copy the complete callback URL from the browser and request it from a second terminal:

curl 'http://127.0.0.1:<port>/auth/callback?...'

Keep the URL in single quotes so the shell does not split & parameters into background commands. Check the callback listener with ss -ltnp | grep <port>.A callback URL can contain a temporary credential. Do not share, screenshot, or commit it.

What if the official model is unavailable?

Run mcode login, then use /status to inspect the account and /model to select an available model. For a MiniMax API key or custom provider, follow the Provider instructions in the Features page and run mcode provider test <provider-id>.

Data directory, configuration, and proxy

Where does the CLI store configuration and sessions?

The default data root is ~/.minimax, and the configuration file is <data-dir>/config.yaml. The directory also stores sessions, logs, plugins, skills, and other runtime data. Set MINIMAX_DATA_DIR to choose another directory; MAVIS_DATA_DIR is a compatibility fallback, and MINIMAX_DATA_DIR wins when both are set.

export MINIMAX_DATA_DIR=/path/to/mcode-data

How do I set a default model and permission mode?

Add values such as these to config.yaml:

defaultModel: "provider-id/model-id"
defaultModelVariant: standard
permissionMode: auto
minimaxModelSource: token_plan

defaultModel uses provider/model and can include #variant. mcode exec --model overrides only the current run. permissionMode accepts default, auto, bypassPermissions, or off.

Which proxy variables does the CLI support?

The CLI supports HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, and lowercase variants. It always bypasses localhost, 127.0.0.1, and ::1 so login callbacks and local services remain reachable.

Providers and API keys

How do I use a MiniMax API key?

Set the key and then run mcode provider set-minimax-key:

export MCODE_PROVIDER_API_KEY="your MiniMax API key"
mcode provider set-minimax-key

The default variable is MCODE_PROVIDER_API_KEY; use --api-key-env <name> for another variable. The CLI reads the key but does not print it.

How do I add an OpenAI- or Anthropic-compatible provider?

Run mcode provider add with at least one model:

export MCODE_PROVIDER_API_KEY="your compatible-provider key"
mcode provider add \
  --name "My compatible service" \
  --base-url "https://api.example.com/v1" \
  --api-format openai-completions \
  --model "model-id" \
  --use

Supported formats are anthropic-messages, openai-completions, and openai-responses. Use mcode provider list, mcode provider test <provider-id>, and mcode provider remove <provider-id> --yes to manage the provider.

Headless and CI

How do I run one task from a script?

Use mcode exec; it does not launch the TUI:

mcode exec --cwd ./repo --output-format json "Run the smallest test set and fix failures"

Read from stdin explicitly with --input -:

cat task.txt | mcode exec --input -
printf '%s\n' '{"prompt":"Analyze the build failure"}' \
  | mcode exec --input - --input-format json --output-format json

Which mcode exec options are available?

Common options are:

--cwd <path>: workspace directory;
--file <path>: repeatable attachments, up to 10 files and 100 MB total;
--model <provider/model[#variant]>: override the model for this run;
--effort <level>: override reasoning effort for this run using a supported level;
--session <id> or --continue: continue an existing session;
--config <path>: use an explicit Runtime configuration;
--permission smart|full|off: Headless permission policy, default smart;
--timeout <duration>: timeout such as 30s or 2m;
--max-steps <count>: maximum Assistant steps;
--output-format text|json|stream-json: output format;
--output-schema <schema>: inline or file JSON Schema;
-o, --output-last-message <path>: write the final message after success.

--input - cannot be combined with a positional prompt. Headless rejects --permission ask because it has no interactive host.

How should automation parse output?

text prints the final answer, json prints one stable ExecResult, and stream-json prints newline-delimited events. Results go to stdout; diagnostics go to stderr. Check the JSON status first and treat model and usage as optional.With --output-schema, the final answer must be JSON matching the schema. Parsing or validation failures return status: failed with STRUCTURED_OUTPUT_INVALID. --output-last-message writes atomically only after a successful run and Runtime shutdown.

What are the mcode exec exit codes?

Check both the process exit code and the JSON status:

Exit code	Meaning
`0`	Success
`2`	Invocation or input error
`3`	Configuration error
`4`	Runtime or task failure
`6`	Timeout
`7`	Runtime limit exceeded
`70`	Internal error
`130`	Interrupted by Ctrl+C or another cancellation signal
`141`	Broken pipe because the downstream pipe closed

Why does Headless say that interaction is unavailable?

Headless cannot wait for a questionnaire, permission prompt, or other human input. If an existing session has a pending interaction, the run fails and asks you to use the TUI or ACP first.

ACP and plugins

Why does an ACP client receive malformed responses?

mcode acp reserves stdin/stdout for ACP protocol messages; logs and diagnostics go to stderr. Do not write natural language directly to the ACP process or mix wrapper logs into stdout. If the editor cannot find mcode, configure the absolute executable path and restart the editor.

What should I do when a plugin install or refresh fails?

Run mcode plugin marketplace list and mcode plugin list --available first. Specify <plugin>@official or <plugin>@local when names collide. Refresh marketplace snapshots with mcode plugin marketplace upgrade; the local source is the plugins directory under the data directory.

Sessions, terminals, and desktop boundaries

How do I continue a previous task?

Run mcode --continue in the original workspace, or use mcode --session to open the session manager. In the TUI, use /sessions [query]. For long conversations, use /compact; export with /export [path.md] or inspect the full history with /transcript.

What is the difference between Plan Mode and permission mode?

Plan Mode controls whether the agent plans before execution (Shift+Tab or /plan). Permission mode controls how tool actions are approved (Alt+M or /permission). They are independent settings.

Why are Browser or Computer Use features missing from the CLI?

The CLI does not depend on Electron or desktop IPC. Browser, Computer Use, desktop panels, and desktop shortcuts appear only when the current host explicitly provides them; desktop-specific behavior belongs in the desktop documentation.

Why does Ctrl+V not paste an image?

Image and video paste depends on whether the terminal emulator forwards the shortcut and clipboard file to MCode. Remote SSH sessions usually cannot read the local clipboard; use @ for a workspace file or mcode exec --file <path> for an attachment.

​Installation and environment

​Sign-in and authentication

​Data directory, configuration, and proxy

​Providers and API keys

​Headless and CI

​ACP and plugins

​Sessions, terminals, and desktop boundaries