> ## Documentation Index
> Fetch the complete documentation index at: https://platform.minimax.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# One-click setup wizard

To use MiniMax in Claude Code, Codex, or OpenCode, you do not need to find and edit each tool's configuration first. Run the one-click setup wizard, choose your tools and service region, and the wizard verifies your API Key, offers to install compatible tools that are missing, and configures MiniMax M3.

The following AI coding tools are currently supported:

* **Claude Code**
* **Codex CLI**
* **OpenCode**
* **Grok CLI**
* **Hermes Agent**
* **Pi**

## Before you begin

Make sure you have:

* Node.js 18 or newer, with `npx` available in your terminal
* A valid MiniMax API Key
* Network access to npm, MiniMax services, and the tools' official download sources

<Accordion title="How to install Node.js">
  Visit the [Node.js website](https://nodejs.org/en/download), then download and install the current LTS version.

  When installation finishes, reopen your terminal and run:

  ```bash theme={null}
  node --version
  npx --version
  ```

  If both commands show a version number, the installation was successful.
</Accordion>

## Bring MiniMax into your coding workflow

<Steps>
  <Step title="Get an API Key">
    * [Get a Token Plan Subscription Key](https://platform.minimax.io/user-center/payment/token-plan)
    * [Get a pay-as-you-go API Key](https://platform.minimax.io/user-center/basic-information/interface-key)

    <Note>
      Token Plan keys (`sk-cp-...`) and pay-as-you-go keys (`sk-api-...`) use separate quotas. The wizard accepts both and asks you to select the key type.
    </Note>
  </Step>

  <Step title="Let the wizard handle setup">
    ```bash theme={null}
    npx -y mmx-cli@latest agent setup
    ```

    Select the tools you want to use. If a selected tool is not detected on `PATH`, a second multi-select asks which tools to install. Then choose the service region and API Key type, and paste your key.

    After confirmation, the wizard verifies the key, then shows and runs the official package or installer script. It checks each installed tool with `--version` before writing the MiniMax configuration. If installation fails, you can skip installation and continue with configuration.
  </Step>

  <Step title="Return to your usual workflow">
    After setup succeeds, start the selected tool, such as `claude`, `codex`, or `opencode`. MiniMax M3 is now its default model.
  </Step>
</Steps>

Automatic installation supports macOS, Linux, and Windows. All tools except Pi currently require an arm64 or x64 system.

<Accordion title="View installer sources and commands">
  <Tabs sync={false}>
    <Tab title="macOS / Linux">
      **Claude Code**

      ```bash theme={null}
      curl -fsSL https://claude.ai/install.sh | bash
      ```

      **Codex CLI**

      ```bash theme={null}
      npm install -g @openai/codex
      ```

      **Grok CLI**

      ```bash theme={null}
      curl -fsSL https://x.ai/cli/install.sh | bash
      ```

      **OpenCode**

      ```bash theme={null}
      npm install -g opencode-ai
      ```

      **Pi**

      ```bash theme={null}
      npm install -g --ignore-scripts --engine-strict @earendil-works/pi-coding-agent
      ```

      For Hermes Agent, mmx runs the non-interactive core CLI stages from the [official installer](https://hermes-agent.nousresearch.com/install.sh) and skips optional flows such as `setup` and `gateway`.
    </Tab>

    <Tab title="Windows">
      **Claude Code**

      ```powershell theme={null}
      irm https://claude.ai/install.ps1 | iex
      ```

      **Codex CLI**

      ```powershell theme={null}
      npm install -g @openai/codex
      ```

      **Grok CLI**

      ```powershell theme={null}
      irm https://x.ai/cli/install.ps1 | iex
      ```

      **OpenCode**

      ```powershell theme={null}
      npm install -g opencode-ai
      ```

      **Pi**

      ```powershell theme={null}
      npm install -g --ignore-scripts --engine-strict @earendil-works/pi-coding-agent
      ```

      For Hermes Agent, mmx runs the non-interactive core CLI stages from the [official PowerShell installer](https://hermes-agent.nousresearch.com/install.ps1) and skips Computer Use and other optional flows.
    </Tab>
  </Tabs>
</Accordion>

## Bring setup into your scripts

Passing any command option switches the setup command to non-interactive mode. Non-interactive mode only writes configuration and does not install tools. You must specify the tools, API Key, and service region:

```bash theme={null}
npx -y mmx-cli@latest agent setup \
  --agent claude-code \
  --agent codex \
  --api-key "$MINIMAX_API_KEY" \
  --region global
```

Configure every supported tool:

```bash theme={null}
npx -y mmx-cli@latest agent setup \
  --all \
  --api-key "$MINIMAX_API_KEY" \
  --region global
```

Preview the files that would change:

```bash theme={null}
npx -y mmx-cli@latest agent setup \
  --agent codex \
  --api-key "$MINIMAX_API_KEY" \
  --region global \
  --dry-run
```

`--dry-run` does not make network requests, install tools, or write files.

| Option                | Description                                        |
| --------------------- | -------------------------------------------------- |
| `--agent <name>`      | Select one tool; repeat to select more             |
| `--all`               | Select every supported tool                        |
| `--api-key <key>`     | MiniMax API Key                                    |
| `--region cn\|global` | Mainland China or global service region            |
| `--model <model>`     | Default model; defaults to `MiniMax-M3`            |
| `--dry-run`           | Preview only; do not verify the key or write files |
| `--output json`       | Return JSON for scripts                            |

Available models are `MiniMax-M3`, `MiniMax-M2.7`, and `MiniMax-M2.7-highspeed`.

## See which files the wizard changes

<Accordion title="View configuration file paths">
  | Tool         | Configuration files                                       |
  | ------------ | --------------------------------------------------------- |
  | Claude Code  | `~/.claude/settings.json`                                 |
  | Codex        | `~/.codex/config.toml`, `~/.codex/mmx-model-catalog.json` |
  | Grok CLI     | `~/.grok/config.toml`                                     |
  | OpenCode     | `~/.config/opencode/opencode.json` or `opencode.jsonc`    |
  | Hermes Agent | `~/.hermes/config.yaml`, `~/.hermes/.env`                 |
  | Pi           | `~/.pi/agent/models.json`, `~/.pi/agent/settings.json`    |
</Accordion>

When writing configuration, the wizard:

* Keeps settings unrelated to MiniMax
* Creates a timestamped `.bak` backup before changing an existing file
* Restricts configuration files to the current user, except on Windows
* Restores files changed during the current run if a later write fails

<Info>
  Setup updates the MiniMax provider for each selected tool and changes its default model to the model you selected. Other providers and unrelated settings are preserved.
</Info>

## If something goes wrong

<AccordionGroup>
  <Accordion title="The agent setup command is missing">
    Make sure Node.js 18 or newer is installed, then run `npx -y mmx-cli@latest agent setup` again. If a local `mmx` command is outdated, you can use this npx command instead.
  </Accordion>

  <Accordion title="A tool shows not detected on PATH">
    The wizard did not find the tool in the current terminal's `PATH`. In interactive mode, it checks the installer requirements and asks whether to install each eligible tool.
  </Accordion>

  <Accordion title="The installation choices do not appear">
    The install list is skipped when the tool is already present, the command is running non-interactively, or the current environment does not meet the installer requirements. The wizard lists missing commands or unsupported architectures; Pi also requires Node.js 22.19 or newer.
  </Accordion>

  <Accordion title="Installation fails">
    The wizard shows the command and error. For npm permission errors with Codex, OpenCode, or Pi, see the [npm documentation](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). You can also skip installation and continue writing the configuration.
  </Accordion>

  <Accordion title="The tool still connects to another service">
    Check for environment variables that override configuration files. Examples include `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_BASE_URL` for Claude Code, or `OPENAI_API_KEY` and `OPENAI_BASE_URL` for Grok CLI.
  </Accordion>

  <Accordion title="Codex already uses a custom model catalog">
    If `model_catalog_json` in `~/.codex/config.toml` points to a custom file, the wizard stops without changing any files. Keep the catalog and follow the [manual Codex setup](/docs/token-plan/codex), or remove that setting and try again.
  </Accordion>
</AccordionGroup>