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

# Aider and Zed

> Configure Aider and Zed to use NEAR AI Cloud as an OpenAI-compatible provider.

NEAR AI Cloud exposes an OpenAI-compatible API, so Aider and Zed can use NEAR AI models with a base URL, an API key, and a model ID.

Use the gateway by default:

| Setting | Value |
| - | - |
| Base URL | `https://cloud-api.near.ai/v1` |
| Model ID | `z-ai/glm-5.2` |
| API key | A NEAR AI Cloud API key |

Create an API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations). Do not paste API keys into shared files, docs, issue comments, or screenshots.

## Aider

Aider uses OpenAI-compatible endpoints through the standard OpenAI environment variables. Set them in the shell that starts Aider:

```bash theme={"dark"}
export OPENAI_API_BASE=https://cloud-api.near.ai/v1
export OPENAI_API_KEY="<your NEAR AI API key>"
```

Then run Aider with the `openai/` model prefix:

```bash theme={"dark"}
aider --model openai/z-ai/glm-5.2
```

To refresh the model, update the command-line model string. For example, after confirming a new model ID from `/v1/models`, replace `openai/z-ai/glm-5.2` with `openai/<new-model-id>`.

If Aider warns that it does not recognize a new model, first confirm the model works with the curl smoke test below. Aider may need a model metadata update before it can infer limits for a newly released model.

### Optional: set limits and enable reasoning for Aider

Aider does not auto-detect limits or reasoning for an unknown model ID, so it falls back to generic defaults and may print `Warning ...: Unknown context window size and costs, using sane defaults.` These steps are optional — basic chat and tool calls work without them — but they fix the warning and expose GLM 5.2's thinking. Both files key on the exact `--model` string, so use `openai/z-ai/glm-5.2`.

Set the limits in `.aider.model.metadata.json` and pass it with `--model-metadata-file`:

```json .aider.model.metadata.json theme={"dark"}
{
  "openai/z-ai/glm-5.2": {
    "max_input_tokens": 500000,
    "max_output_tokens": 131072,
    "max_tokens": 131072,
    "litellm_provider": "openai",
    "mode": "chat"
  }
}
```

Allow the reasoning options in `.aider.model.settings.yml` and pass it with `--model-settings-file`:

```yaml .aider.model.settings.yml theme={"dark"}
- name: openai/z-ai/glm-5.2
  accepts_settings:
    - reasoning_effort
```

`accepts_settings` only allow-lists the reasoning options for this model; it does not turn reasoning on by itself. To actually request reasoning you must also pass `--reasoning-effort` on the launch command, which Aider sends as `extra_body.reasoning_effort` for an `openai/`-prefixed model:

```bash theme={"dark"}
aider --model openai/z-ai/glm-5.2 \
  --model-metadata-file .aider.model.metadata.json \
  --model-settings-file .aider.model.settings.yml \
  --reasoning-effort high
```

The model name in both files must match the `--model` string exactly, or the entries are ignored.

## Zed

Zed supports custom OpenAI-compatible providers. Add NEAR AI Cloud to Zed from **Agent Settings** with `agent: open settings`, or add the provider to `settings.json` and keep the API key in Zed's provider settings UI, the system keychain, or an environment variable.

Do not store API keys in `settings.json`. For provider id `nearai`, Zed's generated environment variable is:

```bash theme={"dark"}
export NEARAI_API_KEY="<your NEAR AI API key>"
```

Add this provider config to Zed's `settings.json`:

```json settings.json theme={"dark"}
{
  "language_models": {
    "openai_compatible": {
      "nearai": {
        "api_url": "https://cloud-api.near.ai/v1",
        "available_models": [
          {
            "name": "z-ai/glm-5.2",
            "display_name": "GLM 5.2",
            "max_tokens": 500000,
            "max_output_tokens": 131072,
            "reasoning_effort": "xhigh"
          }
        ]
      }
    }
  }
}
```

`reasoning_effort` is what makes Zed expose GLM 5.2's thinking: if you omit it, Zed treats the model as non-thinking and shows no thinking toggle or effort variants in the agent panel. GLM 5.2 advertises `reasoning` in `/v1/models`, and it is a Z.AI model, for which Zed's docs recommend `xhigh`. Valid values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Tool calling does not need a flag here — Zed defaults `openai_compatible` model `capabilities.tools` to `true`.

To refresh models in Zed, add or update entries in `available_models`, then restart Zed or reselect the provider in the model picker. If you used Agent Settings instead of editing JSON, open the NEAR AI provider entry and update the model ID and context window there.

Use `https://cloud-api.near.ai/v1` as the provider API URL. Do not paste the full chat-completions route into Zed's API URL field.

## Curl smoke test

Verify the model is listed:

```bash theme={"dark"}
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -e '.data[] | select(.id == "z-ai/glm-5.2")'
```

Then verify a chat completion:

```bash theme={"dark"}
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

If you only set `OPENAI_API_KEY` for Aider, either export `NEARAI_API_KEY="$OPENAI_API_KEY"` before running the curl command or replace `$NEARAI_API_KEY` with `$OPENAI_API_KEY` in the `Authorization` header.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| model not listed | The client has a stale model list, or the model was not added to the manual provider config. | Run the `/v1/models` curl check, copy the exact model ID, then update Aider's `--model openai/<model-id>` string or Zed's `available_models` entry. |
| `401` | Missing, invalid, expired, or unavailable API key in the process that starts the client. | Generate or copy a NEAR AI Cloud API key, set `OPENAI_API_KEY` for Aider or `NEARAI_API_KEY` for the Zed `nearai` provider, then restart the client. |
| Wrong base URL includes `/chat/completions` | The client expects a base URL, but the full request endpoint was pasted. | Use `https://cloud-api.near.ai/v1` in Aider's `OPENAI_API_BASE` and Zed's `api_url`. The client appends `/chat/completions` itself. |

## Related guides

* [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
* [OpenAI Compatibility](/cloud/guides/openai-compatibility)
* [Available Models](/cloud/models)
* [Continue](/cloud/guides/integrations/continue)
* [Cline, Roo Code, and Kilo Code](/cloud/guides/integrations/cline-roo-kilo)

## Sources Checked

Sources checked on 2026-06-23:

* [Aider OpenAI compatible APIs](https://aider.chat/docs/llms/openai-compat.html)
* [Aider advanced model settings](https://aider.chat/docs/config/adv-model-settings.html)
* [Zed Use API Access](https://zed.dev/docs/ai/use-api-access)
* [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.