Pi

Connect the Pi terminal coding agent to 魔方AI with a custom provider in models.json.

Before You Begin

Install a Node.js version supported by the current Pi release.
Create a dedicated 魔方AI API key and note the target model ID.
Use https://www.mofangai001.cn/v1 as the OpenAI-compatible Base URL.

Configuration Steps

1. Install Pi

Install the current official npm package:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

You can also use the official installer:

curl -fsSL https://pi.dev/install.sh | sh

2. Set the API Key

Linux / macOS:

export MOFANG_API_KEY="sk-your-api-key"

Windows PowerShell:

$env:MOFANG_API_KEY="sk-your-api-key"

3. Create the Model Configuration

Add 魔方AI to ~/.pi/agent/models.json:

{
    "providers": {
        "mofang": {
            "baseUrl": "https://www.mofangai001.cn/v1",
            "api": "openai-completions",
            "apiKey": "$MOFANG_API_KEY",
            "models": [
                {
                    "id": "your-model-id",
                    "name": "魔方AI Model",
                    "reasoning": false,
                    "input": ["text"],
                    "contextWindow": 128000,
                    "maxTokens": 8192
                }
            ]
        }
    }
}

Match all capability fields to the actual 魔方AI model. Do not apply one set of reasoning compatibility options to every model.

4. Select the Model

Start Pi, enter /model or press Ctrl+L, then select mofang and the target model. Pi reloads models.json when the model selector opens.

Verify the Integration

After selecting the model, send a small coding task. Normal streaming output and basic tool execution confirm the configuration.

Reasoning Models

Use the Current thinkingLevelMap

Current Pi releases replaced the old compat.reasoningEffortMap with a model-level thinkingLevelMap. Add it only after confirming that the target model accepts the mapped reasoning levels. For example:

{
    "id": "your-reasoning-model-id",
    "reasoning": true,
    "thinkingLevelMap": {
        "minimal": "low",
        "low": "low",
        "medium": "medium",
        "high": "high",
        "xhigh": null
    }
}

Do not copy the obsolete thinkingFormat: "anthropic" example. It is not among the OpenAI compatibility formats in the current Pi documentation.

FAQ

Why is the provider or model missing?

Confirm that the file is ~/.pi/agent/models.json, the JSON is valid, and MOFANG_API_KEY is set. Without usable authentication, a model can load but remain unavailable in the selector.

Why does Pi return 401?

Set the API key again and launch Pi from the same shell. Check whether the 魔方AI token is expired, disabled, or restricted.

Why does a reasoning model behave incorrectly?

Remove custom compat and thinkingLevelMap settings first and verify a normal request. Then add compatibility options one at a time according to the specific model protocol.

Can I keep using an old Pi configuration?

The old repository name, old npm package, and reasoningEffortMap are outdated. New configuration should use earendil-works/pi, @earendil-works/pi-coding-agent, and model-level thinkingLevelMap.

Security

Never put a real key in documentation, screenshots, session logs, or version control.
Pi extensions and skills can execute code. Review the source and permissions before installing third-party packages.
Use a dedicated 魔方AI token for Pi and restrict models and quota as needed.
Pi sends prompts, necessary code context, and tool-call data to 魔方AI.