AI Coding Assistant Setup and Model Switching Guide

    This article provides a comprehensive guide to setting up AI coding assistants and switching models. It covers runtime environment preparation, assistant installation, secure model provider configuration, API key management, and connectivity troubleshooting to ensure a smooth integration process.

    1. Prerequisites and Scope

    Before starting, ensure you have three things: an accessible runtime installation source, a model service account that supports a compatible interface protocol, and write permissions to your local user directory.

    This article uses Node.js and Python as examples. The minimum versions, package names, command names, and configuration file locations required by the coding assistant should follow the official documentation of the chosen tool. The API endpoint, model identifier, billing rules, and quota policies of the model service should also follow the service provider’s official documentation. Replace the placeholders in this article’s examples with the actual values from the documentation.

    2. Stage 1: Confirm Runtime and Configure Registry

    1. Check the runtime version to confirm the command executes correctly:
    1. node -v
    2. npm -v
    3. python3 --version
    4. pip3 --version
    1. Switch npm to an accessible registry mirror, and verify the change:
    1. npm config set registry <accessible-npm-registry-url>
    2. npm config get registry

    To restore the official source, execute npm config set registry https://registry.npmjs.org.

    1. Switch pip to an accessible registry mirror, and view the configuration list:
    1. pip3 config set global.index-url <accessible-pypi-registry-url>
    2. pip3 config list
    1. After downloading the runtime package, verify its SHA256 hash. The hash should match the checksum file provided on the official release page.

    Linux or macOS:

    1. sha256sum node-vX.Y.Z-linux-x64.tar.xz

    Windows PowerShell:

    1. Get-FileHash .\node-vX.Y.Z-win-x64.zip -Algorithm SHA256
    1. Handle enterprise proxies and certificate issues. If the proxy uses an enterprise root certificate, you need to import the certificate into the system trust store and allow the runtime to read it:
    • Linux: Place the .crt file in /usr/local/share/ca-certificates/, and run sudo update-ca-certificates.
    • macOS: Import the certificate in “Keychain Access” and set it to “Always Trust”.
    • Windows: Run certlm.msc and import it into “Trusted Root Certification Authorities”.
    • Node.js: Set export NODE_EXTRA_CA_CERTS=/path/to/corp-root-ca.pem.
    • Python: Set export REQUESTS_CA_BUNDLE=/path/to/corp-root-ca.pem.
    1. Check the system time. HTTPS certificate validation relies on accurate time; significant time deviations will cause certificate errors. On Linux or macOS, use date to check; on Windows, enable automatic time synchronization in settings.

    The recommended troubleshooting sequence for common issues is: first confirm the runtime version, then confirm the registry URL is reachable, and finally proceed to the installation phase. If the runtime version is lower than required, upgrade the runtime first instead of repeatedly reinstalling the assistant.

    3. Stage 2: Install Assistant and Confirm Executable Entry

    There are two installation methods; prioritize the one with better reachability.

    Path A: Global installation via package manager.

    1. npm install -g <package-name-from-official-docs>@<locked-version>
    2. which <command-name-from-official-docs>
    3. <command-name-from-official-docs> --version

    On Windows, replace which with where. In team environments, it is recommended to lock the version number to avoid incompatible changes from automatic upgrades.

    Path B: Installation via official install script. Do not execute curl ... | bash directly; download, inspect, and then execute:

    1. curl -fsSL -o install.sh <official-install-script-url>
    2. less install.sh
    3. sha256sum install.sh
    4. bash install.sh

    If the official page provides a checksum for the script, compare it with the output from step three.

    After installation, confirm three things sequentially: the executable entry is in the PATH, the configuration directory has been generated, and the version query returns normally. Do not log in or activate a subscription yet.

    Troubleshooting “command not found” issues:

    1. Execute npm config get prefix to check the global installation directory.
    2. Confirm that the bin directory under it (or the directory itself on Windows) has been added to the PATH.
    3. Close and reopen the terminal, then execute the version query again.

    Troubleshooting missing dependencies issues:

    1. Execute npm config get registry to confirm there are no typos in the registry URL.
    2. Execute npm cache verify to check the local cache.
    3. If the registry has not yet synced a specific version, temporarily install using the official source, or wait for the mirror to sync and retry.

    When encountering permission errors during global installation, it is not recommended to use sudo npm install -g. A safer approach is to switch the global directory to the user directory:

    1. npm config set prefix ~/.npm-global
    2. export PATH="$HOME/.npm-global/bin:$PATH"

    4. Stage 3: Configure Model Provider and API Key

    The location of the configuration file depends on the chosen tool. The following JSON is only used to illustrate the field structure; the path and field names must be replaced with the actual content from the official documentation:

    1. {
    2. "activeProfile": "default",
    3. "profiles": {
    4. "default": {
    5. "provider": "<provider-identifier>",
    6. "baseUrl": "<compatible-api-endpoint-from-official-docs>",
    7. "model": "<model-identifier-from-official-docs>",
    8. "apiKeyEnv": "ASSISTANT_API_KEY"
    9. }
    10. }
    11. }

    Field meanings are as follows:

    • provider is used to distinguish the service source; name it for easy identification.
    • baseUrl must match the service provider’s documentation, usually only up to the root path of the compatible interface.
    • model must be copied from the official documentation; do not guess or type manually.
    • apiKeyEnv only stores the environment variable name, not the key itself.

    The configuration file should only be readable and writable by the current user:

    1. chmod 600 ~/.config/<tool-directory>/profiles.json

    Choose the key injection method based on the usage scenario:

    • Local terminal: Write the key to a file with 600 permissions, and read it into an environment variable before starting. Do not write it directly into .bashrc or .zshrc to avoid long-term plaintext retention.
    1. chmod 600 ~/.secrets/assistant_key
    2. export ASSISTANT_API_KEY="$(cat ~/.secrets/assistant_key)"
    • systemd service: Write ASSISTANT_API_KEY=... in /etc/<service-name>/env, set the file permission to 600, and reference it using EnvironmentFile= in the unit file.
    • IDE: IDEs usually inherit the environment variables of the terminal that launches them, so they should be launched from a terminal with the variables set. If the IDE has a built-in key storage feature, use it first.
    • Windows PowerShell current session: $env:ASSISTANT_API_KEY = $key. This method is only valid for the current session and will not be written to the registry.

    Key rotation steps:

    1. Create a new key in the service provider’s console.
    2. Update the value in the key file or environment variable.
    3. Restart the assistant or IDE to make the new variable take effect.
    4. Execute the verification command in Section 5.
    5. Disable the old key in the console.
    6. Record the rotation time and operator.

    Before switching model providers, back up the current configuration for easy rollback:

    1. cp ~/.config/<tool-directory>/profiles.json ~/.config/<tool-directory>/profiles.json.bak.$(date +%Y%m%d%H%M%S)

    Then modify activeProfile, or add a new profile and point to it. After switching, restart or reload the client to confirm the new configuration takes effect.

    5. Stage 4: Connectivity Verification and Troubleshooting

    Verification should be conducted in four layers: runtime version, client entry, key authentication, and model request. After the first three layers pass, test features like completion, Q&A, and refactoring.

    To create a minimal request example, first confirm the compatible interface path from the official documentation. Here we use the common Chat Completions path as an example:

    1. curl -sS --connect-timeout 10 -w "\nHTTP %{http_code}\n" \
    2. "$ASSISTANT_BASE_URL/chat/completions" \
    3. -H "Authorization: Bearer $ASSISTANT_API_KEY" \
    4. -H "Content-Type: application/json" \
    5. -d '{"model":"<model-identifier-from-official-docs>","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

    Two things to note about this command. Do not add -v, otherwise the Authorization in the request header will be printed to the terminal and logs. The key is referenced as $ASSISTANT_API_KEY, so the shell history records the variable name, not the key plaintext.

    HTTP status code reference:

    Status Code or Phenomenon Common Cause Troubleshooting Direction
    401 Invalid key, or not passed to the client process Confirm the variable exists in the process that started the client
    403 Insufficient account permissions, or service not activated Check the service activation status and permissions in the console
    404 Incorrect interface path or model identifier Correct baseUrl and model according to the official documentation
    429 Rate limit, or quota exhausted Check usage and quota, reduce concurrency
    5xx Server-side exception Retry later, record request time
    Timeout or no response Network, proxy, or DNS issue Check proxy settings, execute curl -sI "$ASSISTANT_BASE_URL" to judge reachability

    The recommended troubleshooting sequence is: whether the configuration is loaded, whether the environment variables are effective, whether the interface is reachable, whether the model identifier is correct, whether the quota is sufficient, and whether the system time and certificates are normal. Eliminating them one by one in this order is faster than repeatedly modifying the configuration.

    Credentials in logs must be redacted before sharing. The following command can replace the Bearer token with a placeholder:

    1. sed -E 's/Bearer [A-Za-z0-9._-]+/Bearer ***/g' client.log > client.redacted.log

    6. Rollback and Security Points

    For rollback, overwrite the current configuration with the backup file, then restart the client:

    1. cp ~/.config/<tool-directory>/profiles.json.bak.<timestamp> ~/.config/<tool-directory>/profiles.json

    Security considerations to note:

    • Key files and credential files in the configuration should be added to .gitignore, and verified with git check-ignore -v <filename>.