How to Configure DashScope Token Plan in Pi Agent

To connect Alibaba Cloud DashScope’s Token Plan to Pi Agent, you need to register [https://coding.dashscope.aliyuncs.com/v1](https://coding.dashscope.aliyuncs.com/v1) as an OpenAI-compatible service within Pi’s local configuration files.

By default, Pi’s interactive terminal login menu (/login) only lists natively pre-configured providers. You won’t see an option to enter a custom API endpoint directly in that UI menu. The solution is straightforward: define your service configuration in a local models.json file. Once the base URL, authentication key, and model IDs are mapped correctly, restart Pi and select your custom model through the /model menu.

Here is a step-by-step guide to setting up the configuration, avoiding common pitfalls, and troubleshooting errors.

The Root Cause: Why Is Custom Endpoint Missing in /login?

Pi Agent’s CLI architecture requires local provider definitions before rendering custom options in its interactive menu. If you cannot find Use an API key or custom endpoint prompts under /login, it simply means Pi hasn’t detected a custom provider block in its configuration directory yet.

In short: Update the configuration file first, launch the client second, and switch models third.

There is also a network factor to keep in mind. The Alibaba Cloud Coding endpoint (coding.dashscope.aliyuncs.com) resides in China. If your local terminal routes traffic through a global VPN or proxy, requests sent to this endpoint might get intercepted or misrouted, resulting in 404, 500, or request timeout errors. Bypassing your proxy for this specific host prevents connectivity issues.

Step-by-Step Guide: Configuring models.json

The core task is creating or editing Pi’s global model configuration file at ~/.pi/agent/models.json.

1. Create or Open the Configuration File

Run the following commands in your terminal to ensure the target directory exists:

mkdir -p ~/.pi/agent
nano ~/.pi/agent/models.json

Feel free to use any code editor of your choice (such as VS Code) to edit this file.

2. Add DashScope Compatible Configuration

Paste the following JSON structure into the file. Replace YOUR_ACTUAL_API_KEY with the key generated from your DashScope console (typically starting with sk-sp- or sk-):

{
  "providers": {
    "dashscope-coding": {
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "api": "openai-completions",
      "apiKey": "sk-sp-YOUR_ACTUAL_API_KEY",
      "models": [
        {
          "id": "qwen3.5-plus"
        }
      ]
    }
  }
}

Field details:

3. Secure Your Key Using Environment Variables (Recommended)

Hardcoding API keys into JSON files poses a security risk, especially when syncing dots or sharing developer environments. Storing the key as an environment variable keeps your setup secure.

Add the export statement to your shell configuration file (~/.bashrc or ~/.zshrc):

export DASHSCOPE_API_KEY="sk-sp-YOUR_ACTUAL_API_KEY"

Apply the changes to your current terminal session:

source ~/.zshrc

Then reference the variable inside models.json:

{
  "providers": {
    "dashscope-coding": {
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "api": "openai-completions",
      "apiKey": "$DASHSCOPE_API_KEY",
      "models": [
        {
          "id": "qwen3.5-plus"
        }
      ]
    }
  }
}

Activation and Verification: Switching to Your Custom Model

Once your configuration file is saved, follow these steps to load and verify the model inside Pi Agent.

Step 1: Launch Pi Agent

Start the CLI client from your terminal:

pi

Step 2: Open the Model Selection Menu

Type the slash command in the Pi prompt:

/model

Step 3: Select the DashScope Node

Your custom provider dashscope-coding and its model qwen3.5-plus will now appear in the list alongside default providers. Use your arrow keys to select it and press Enter.

Troubleshooting & Common Pitfalls

If requests fail after configuration, the issue usually stems from incorrect API keys, proxy routing, or plugin conflicts.

1. Connection Timeouts or 404/500 Errors

Because the Alibaba Cloud Coding endpoint is hosted in China, terminal proxies can interfere with routing. If global proxy rules capture outgoing traffic to coding.dashscope.aliyuncs.com, the connection may time out or fail.

Solutions:

• Temporarily disable your terminal proxy settings.
• Add the DashScope host to your shell’s NO_PROXY list:

export NO_PROXY="coding.dashscope.aliyuncs.com,$NO_PROXY"
export no_proxy="coding.dashscope.aliyuncs.com,$no_proxy"

2. Model Unresponsive or Permission Denied

Verify that the model id in your JSON file (e.g., qwen3.5-plus, qwen-max, or deepseek-v3) matches the specific model tied to your active Token Plan subscription. Gateways reject requests targeting unauthorized model names.

3. Alternative Method: Using the Community Extension (pi-alibaba-models)

If you prefer to avoid editing JSON files manually, you can install the community extension pi-alibaba-models.

This package automatically injects pre-configured provider definitions for domestic and international Alibaba Cloud endpoints. Once installed, running /login displays built-in prompts for entering your API key directly in the interactive UI.

Quick Action Checklist

Use this checklist to verify your setup steps:

• [ ] Ensure coding.dashscope.aliyuncs.com is excluded from terminal proxy interception.
• [ ] Create the target directory: mkdir -p ~/.pi/agent.
• [ ] Create ~/.pi/agent/models.json with correct baseUrl, api: "openai-completions", and models arrays.
• [ ] Export DASHSCOPE_API_KEY in your shell environment or add your key directly to the JSON file.
• [ ] Launch pi, type /model, and confirm that your custom model loads successfully.

Workflow Overview

┌────────────────────────────────────────────────────────┐
│                   Configuration Flow                   │
└────────────────────────────────────────────────────────┘
                           │
                           ▼
  1. Preparation ──────► Export DASHSCOPE_API_KEY in shell
                           │
                           ▼
  2. Write Config ─────► Edit ~/.pi/agent/models.json
                         ├─ baseUrl: https://coding.dashscope.aliyuncs.com/v1
                         ├─ api: openai-completions
                         └─ models: [ { "id": "qwen3.5-plus" } ]
                           │
                           ▼
  3. Start Client ─────► Run `pi` in terminal
                           │
                           ▼
  4. Switch Model ─────► Run `/model` and select dashscope-coding / qwen3.5-plus

Frequently Asked Questions (FAQ)

1. Why isn’t there a custom endpoint option in Pi’s initial /login menu?

Pi’s interface menu populates options dynamically from its configuration files. Custom providers only appear in menu listings after they are registered inside ~/.pi/agent/models.json.

2. Why must the api field be set to openai-completions?

Alibaba Cloud DashScope’s Coding endpoint uses an OpenAI-compatible REST API interface. Setting api to openai-completions ensures Pi formats request payloads according to OpenAI standards.

3. Should the baseUrl string include a trailing slash?

No. Use [https://coding.dashscope.aliyuncs.com/v1](https://coding.dashscope.aliyuncs.com/v1) without a trailing slash at the end.

4. How do I fix connection timeouts after completing the setup?

Timeouts are usually caused by local proxy tools intercepting traffic destined for domestic Chinese hosts. Disable terminal proxying or add coding.dashscope.aliyuncs.com to your NO_PROXY environment variable.

5. Can I use any random string for the model id field?

No. The id must exactly match an active model identifier supported by your subscription tier (such as qwen3.5-plus).

6. What is the pi-alibaba-models community package?

It is a community-maintained extension that adds built-in templates for Alibaba Cloud endpoints into Pi Agent, removing the need to edit models.json manually.