> ## Documentation Index > Fetch the complete documentation index at: https://agent.minimax.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Troubleshoot MiniMax Code CLI installation, sign-in, configuration, automation, and terminal issues. Start with the installed version and command help to identify whether an issue is related to installation, authentication, configuration, or task execution: ```bash theme={null} mcode --version mcode --help mcode --help ``` ## Installation and environment > [accordion] 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. > [accordion] 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. > [accordion] 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. > [accordion] 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. ## Sign-in and authentication > [accordion] How do I sign in to a mainland China or Global account? > > For a mainland China account, run `mcode login`. For a Global account, run `mcode login --region global`. After sign-in, use `/status` in the TUI to check account, model, and runtime status. You can also run `mcode acp login --region ` under the ACP command. > [accordion] 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: > > ```bash theme={null} > 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: > > ```bash theme={null} > ssh -N -L :127.0.0.1: > ``` > > Each login may use a different port; do not permanently reuse the example port. > [accordion] The browser login finished, but the localhost callback page does not load > > Keep the login process running. Copy the complete callback URL from the browser and request it from a second terminal: > > ```bash theme={null} > curl 'http://127.0.0.1:/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 `. > > A callback URL can contain a temporary credential. Do not share, screenshot, or commit it. > [accordion] 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 `. ## Data directory, configuration, and proxy > [accordion] Where does the CLI store configuration and sessions? > > The default data root is `~/.minimax`, and the configuration file is `/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. > > ```bash theme={null} > export MINIMAX_DATA_DIR=/path/to/mcode-data > ``` > [accordion] How do I set a default model and permission mode? > > Add values such as these to `config.yaml`: > > ```yaml theme={null} > 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`. > [accordion] 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 > [accordion] How do I use a MiniMax API key? > > Set the key and then run `mcode provider set-minimax-key`: > > ```bash theme={null} > 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 ` for another variable. The CLI reads the key but does not print it. > [accordion] How do I add an OpenAI- or Anthropic-compatible provider? > > Run `mcode provider add` with at least one model: > > ```bash theme={null} > 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`, `openai-responses`, and `google-generative-ai` (Google Gemini). Use `mcode provider list`, `mcode provider test `, and `mcode provider remove --yes` to manage the provider. ## Headless and CI > [accordion] How do I run one task from a script? > > Use `mcode exec`; it does not launch the TUI: > > ```bash theme={null} > mcode exec --cwd ./repo --output-format json "Run the smallest test set and fix failures" > ``` > > Read from stdin explicitly with `--input -`: > > ```bash theme={null} > cat task.txt | mcode exec --input - > printf '%s\n' '{"prompt":"Analyze the build failure"}' \ > | mcode exec --input - --input-format json --output-format json > ``` > [accordion] Which mcode exec options are available? > > Common options are: > > * `--cwd `: workspace directory; > * `--file `: repeatable attachments, up to 10 files and 100 MB total; > * `--model `: override the model for this run; > * `--effort `: override reasoning effort for this run using a supported level; > * `--session ` or `--continue`: continue an existing session; > * `--config `: use an explicit Runtime configuration; > * `--permission smart|full|off`: Headless permission policy, default `smart`; > * `--timeout `: timeout such as `30s` or `2m`; > * `--max-steps `: maximum Assistant steps; > * `--output-format text|json|stream-json`: output format; > * `--output-schema `: inline or file JSON Schema; > * `-o, --output-last-message `: write the final message after success. > > `--input -` cannot be combined with a positional prompt. Headless rejects `--permission ask` because it has no interactive host. > [accordion] 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. > [accordion] 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 | > [accordion] 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 > [accordion] 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. > [accordion] What should I do when a plugin install or refresh fails? > > Run `mcode plugin marketplace list` and `mcode plugin list --available` first. Specify `@official` or `@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 > [accordion] 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`. > [accordion] 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. > [accordion] Can I use Browser or Computer Use in the CLI? > > The interactive TUI on macOS and Windows can use Computer Use through the official plugin; see [Computer Use](https://agent.minimax.io/docs/cli/computer-use.md). Non-interactive entry points such as `mcode exec` and ACP do not support it. Browser, desktop panels, and desktop shortcuts belong to the desktop app and are not available in the CLI. > [accordion] Computer Use says the computer is busy > > Only one desktop conversation or TUI session can control the computer at a time. Wait for the other one to finish, or stop its current action, then try again. > [accordion] 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 ` for an attachment.