Connecting Open-Source Coding Assistants to Chinese Open-Source Models: A Practical Guide

    This guide explains how to connect open-source coding assistants such as Aider and Qwen Code to OpenAI-compatible Chinese open-source models. It covers tool selection, credential handling, environment and configuration file setup, connectivity verification with curl, common error troubleshooting, safe Agent workflows, and options after free quotas expire.

    1. Choose a Coding Assistant That Supports Custom Endpoints

    The prerequisite for connecting a third-party model is that the tool allows you to specify a model endpoint. When selecting a tool, check three things: whether it supports a custom Base URL, whether the official documentation explains how to configure it, and whether the project is still maintained. Open the project’s Releases page or its latest commit to judge its maintenance status.

    The following two open-source tools support OpenAI-compatible interfaces and can serve as starting points:

    • Aider: a terminal-based pair-programming tool. Changes are recorded as Git commits. Install it with pip install aider-chat; a local Python environment is required.
    • Qwen Code: an open-source terminal coding assistant installed globally via npm. For the installation command and runtime requirements, refer to the project README.

    Tools and versions change quickly. Before installing, refer to the official documentation.

    2. Obtain Model Access Credentials

    Create a project and an API Key in the model provider’s console, and record three pieces of information:

    1. The endpoint address (Base URL), usually ending in /v1.
    2. The API Key.
    3. The model name. Copy it from the model list in the console; do not type it from memory.

    Free quotas and limited-time offer terms may change. Review the usage and billing rules before activation. It is recommended to set a usage cap or alert for the key to avoid unexpected pay-as-you-go charges after the quota is exhausted.

    Store the key only in environment variables or a system key manager. Do not write it into a code repository, and do not paste it into chat logs, tickets, or screenshots.

    3. Configure the Tools

    Configure Aider

    1. export OPENAI_API_BASE="https://<provider-endpoint>/v1"
    2. export OPENAI_API_KEY="<your-api-key>"
    3. aider --model openai/<model-name>

    The openai/ prefix tells Aider to call the model through the OpenAI-compatible protocol. The part after it is the model name provided by the service provider.

    Configure Qwen Code

    1. export OPENAI_BASE_URL="https://<provider-endpoint>/v1"
    2. export OPENAI_API_KEY="<your-api-key>"
    3. export OPENAI_MODEL="<model-name>"
    4. qwen

    For the startup command, refer to the project documentation; it is usually qwen.

    Watch for Variable Name Differences

    Different tools read different environment variable names. Aider reads OPENAI_API_BASE, while Qwen Code reads OPENAI_BASE_URL. If the variable name is wrong, the tool will silently use the default endpoint, which appears as the model not switching. Before configuring, check the tool documentation and confirm the variable name it actually reads.

    Use Configuration Files

    For tools that support configuration files, the provider-related fields usually contain the protocol type, endpoint, model name, and similar information. Use the field names specified in the tool’s documentation. Do not put plaintext keys in configuration files. If the tool supports reading from environment variables, reference the environment variable. If it does not, add the configuration file to .gitignore to avoid committing it.

    4. Verify Connectivity

    Connectivity verification has three steps. Run them in order.

    Step 1: Check the Model List

    1. curl -s https://<endpoint>/v1/models \
    2. -H "Authorization: Bearer $OPENAI_API_KEY"

    Normally, the data array in the returned JSON includes the model ID you want to use.

    Step 2: Send a Minimal Chat Request

    1. curl -s https://<endpoint>/v1/chat/completions \
    2. -H "Authorization: Bearer $OPENAI_API_KEY" \
    3. -H "Content-Type: application/json" \
    4. -d '{"model":"<model-name>","messages":[{"role":"user","content":"Reply in one sentence: connection successful"}],"max_tokens":32}'

    Normally, the choices[0].message.content field contains returned text.

    Step 3: Run a Real Task in the Coding Assistant

    Enter the following into the tool: Write a Python function that reads a CSV and counts missing values in each column. The expected result is generated code that uses the pandas or csv module and can run on a sample file. You can prepare a sample.csv containing null values and test it yourself.

    Troubleshooting Common Errors

    Symptom Possible Cause What to Do
    401 or 403 Wrong key, or the key does not have permission for that model Check the key length with echo ${#OPENAI_API_KEY}; do not print the full key. Confirm model permissions in the console.
    404 Wrong endpoint path, often a missing /v1, or the model name does not exist Check the model name and endpoint against the model list.
    429 Rate limiting triggered, or quota exhausted Check usage in the console, retry later, or adjust the plan.
    Timeout or connection failure Network unreachable, or corporate intranet proxy not configured Run curl -I https://<endpoint> to check network access, and set HTTPS_PROXY if necessary.
    Model not switched Wrong variable name, or the terminal cached an old environment Check variable names with env | grep -E ‘^OPENAI_(BASE_URL|API_BASE|MODEL)’, then reopen the terminal.
    Poor output quality Task too large, irrelevant files mixed into context, or missing standards/constraints Narrow the task, clean up context, and specify the language version and coding standards in the prompt.

    When output quality is poor, some tools support a temperature parameter. For coding tasks, it is usually set to a lower value to reduce randomness.

    5. Safe Agent Workflows

    Agent mode lets the model automatically read files, modify code, and execute commands. Improper permission settings can cause accidental file deletion or key leakage. Follow these rules.

    1. Work on a separate branch. After each change, review it with git diff and commit only after confirming it is correct.
    2. Set a command allowlist. Allow only tests, linting, and read-only commands, such as pytest, npm test, and git status. Forbid rm, sudo, and network commands that could exfiltrate data.
    3. Read-only first, write later. Disable write permissions during exploration, and enable them only after the plan is confirmed.
    4. Use a sandbox. Run the Agent in a container or under a separate system user, and limit the files and network ranges it can access.
    5. Isolate secrets. Pass only the necessary environment variables to the Agent process; do not expose the entire shell’s secrets to it.
    6. Merge only after tests pass. Run tests after changes are complete, and merge to the main branch only when all tests pass.

    Context Management Checklist

    • Add only module files relevant to the current task to the context.
    • Split large tasks into multiple subtasks, each using a separate session.
    • Before each task, write down the goal and acceptance criteria so you can judge whether the model output meets them.

    6. What to Do After Free Quotas Expire

    After the free quota ends, you can choose an alternative as follows.

    • Switch to pay-as-you-go. First measure one month’s token consumption, then multiply it by the provider’s published unit price to estimate the monthly cost. When usage is stable, pay-as-you-go is usually the simplest option.
    • Change providers. As long as the provider offers an OpenAI-compatible interface, the configuration method is basically unchanged; you only need to replace the endpoint, key, and model name.
    • Use private deployment. Code data does not leave your domain, which suits teams with compliance requirements. However, it requires GPU resources and operations investment, and is suitable for scenarios with stable usage and larger scale.
    • Use a local small model. This suits lightweight tasks such as code completion and simple Q&A; complex refactoring still requires a more capable model.

    For individual developers with low usage and low code sensitivity, prioritize cloud pay-as-you-go. For teams with high usage and sensitive code, evaluate private deployment.

    7. Summary

    Connecting open-source coding assistants to domestic open-source models generally involves five steps: choose a tool, obtain a key, configure, verify, and set safety boundaries. In the configuration step, pay special attention to variable names and endpoint paths. In the verification step, use three layers of checks: the model list, a minimal request, and a real task. In Agent mode, branches, allowlists, and sandboxes can effectively control risk. Following this process makes model switching and migration fast.