# NextChat User Guide

NextChat (formerly ChatGPT-Next-Web) is a cross-platform AI chat interface that connects to 16 different LLM providers through a single, polished UI. Built with Next.js and React, it runs as a web app, a PWA, or a native desktop application via Tauri. Whether you want a private ChatGPT-style interface backed by your own API keys or a shared deployment for your team, NextChat delivers multi-model chat with masks (personas), plugins, image generation, text-to-speech, realtime audio, and data sync — all in 20 languages.

---

## 1. Quick Start

Get chatting in under five minutes with Vercel's one-click deploy:

1. Fork or clone the repository at `https://github.com/ChatGPTNextWeb/NextChat`.
2. Import the project into [Vercel](https://vercel.com).
3. Set the environment variable `OPENAI_API_KEY` to your OpenAI key.
4. Optionally set `CODE` to a comma-separated list of access codes (e.g., `CODE=mypass1,mypass2`).
5. Deploy. Vercel assigns a `.vercel.app` URL — open it and start chatting.

> [!TIP]
> You can skip Vercel entirely and run locally with Docker in one command — see the Docker section below.

### First-time setup in the UI

1. Open the app in your browser.
2. If an access code was configured, enter it on the auth screen.
3. Click the gear icon (bottom-left) to open **Settings**.
4. Choose your **Model Provider** (OpenAI, Google, Anthropic, etc.).
5. If the deployment admin did not set a server-side API key, paste your own key into the provider's API Key field.
6. Pick a model from the dropdown and send your first message.

---

## 2. Installation

NextChat supports five deployment methods. Pick whichever fits your infrastructure.

### 2.1 Vercel (Recommended for Most Users)

**Requirements:** A Vercel account (free tier works), an API key for at least one LLM provider.

```bash
# Option A: Use the "Deploy with Vercel" button in the repo README.
# Option B: CLI
npm i -g vercel
git clone https://github.com/ChatGPTNextWeb/NextChat.git
cd NextChat
vercel
```

Set environment variables in the Vercel dashboard under **Settings → Environment Variables**:

| Variable | Required | Example |
|---|---|---|
| `OPENAI_API_KEY` | Yes (or another provider key) | `sk-abc123...` |
| `CODE` | Recommended | `pass1,pass2,pass3` |
| `BASE_URL` | Only for proxies | `https://my-proxy.example.com/v1` |

> [!IMPORTANT]
> Without a `CODE` value, anyone with your deployment URL can use your API key and rack up charges. Always set access codes for public-facing deployments.

### 2.2 Docker

**Requirements:** Docker Engine 20+ or Docker Desktop.

```bash
# Minimal — OpenAI only
docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY=sk-your-key \
  -e CODE=your-access-code \
  yidadaa/chatgpt-next-web

# With proxy and multiple providers
docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY=sk-your-key \
  -e GOOGLE_API_KEY=AIza-your-key \
  -e ANTHROPIC_API_KEY=sk-ant-your-key \
  -e CODE=code1,code2 \
  -e HIDE_USER_API_KEY=1 \
  yidadaa/chatgpt-next-web
```

Open `http://localhost:3000` in your browser.

### 2.3 Docker Compose

Create a `docker-compose.yml`:

```yaml
version: "3"
services:
  chatgpt-next-web:
    image: yidadaa/chatgpt-next-web
    ports:
      - "3000:3000"
    environment:
      OPENAI_API_KEY: sk-your-key
      CODE: your-access-code
    restart: unless-stopped
```

```bash
docker compose up -d
```

### 2.4 Cloudflare Pages

1. Fork the repository on GitHub.
2. In the Cloudflare dashboard, go to **Pages → Create a project → Connect to Git**.
3. Select your fork. Set the build command to `npx next build` and the output directory to `.next`.
4. Add environment variables (`OPENAI_API_KEY`, `CODE`, etc.) under **Settings → Environment Variables**.
5. Deploy.

### 2.5 Desktop App (Tauri)

Pre-built desktop binaries for Windows, macOS, and Linux are available on the [GitHub Releases](https://github.com/ChatGPTNextWeb/NextChat/releases) page. Download the installer for your platform and run it.

To build from source:

```bash
# Prerequisites: Rust toolchain, Node.js 18+
git clone https://github.com/ChatGPTNextWeb/NextChat.git
cd NextChat
yarn install
yarn tauri build
```

The compiled binary appears in `src-tauri/target/release/`.

### 2.6 Local Development

```bash
git clone https://github.com/ChatGPTNextWeb/NextChat.git
cd NextChat
yarn install
# Create .env.local with your keys
echo "OPENAI_API_KEY=sk-your-key" > .env.local
yarn dev
```

The dev server starts at `http://localhost:3000` with hot reload.

---

## 3. Configuration

### 3.1 Environment Variables (Server-Side)

These are set on the hosting platform (Vercel, Docker, etc.) and control the deployment for all users.

#### Access Control

| Variable | Default | Description |
|---|---|---|
| `CODE` | *(empty)* | Comma-separated access codes. Hashed with MD5 internally. |
| `HIDE_USER_API_KEY` | `0` | Set to `1` to remove the API key input from settings — forces use of server key. |
| `DISABLE_GPT4` | `0` | Set to `1` to block all GPT-4 models from the model list. |
| `DISABLE_FAST_LINK` | `0` | Set to `1` to disable URL-based settings import (the `?settings=` query param). |
| `ENABLE_BALANCE_QUERY` | `0` | Set to `1` to show API key balance information in settings. |

#### Provider Keys

| Variable | Provider |
|---|---|
| `OPENAI_API_KEY` | OpenAI (supports multiple comma-separated keys with random rotation) |
| `GOOGLE_API_KEY` | Google Gemini |
| `ANTHROPIC_API_KEY` | Anthropic Claude |
| `BAIDU_API_KEY` / `BAIDU_SECRET_KEY` | Baidu Ernie |
| `BYTEDANCE_API_KEY` | ByteDance Doubao |
| `ALIBABA_API_KEY` | Alibaba Qwen |
| `TENCENT_API_KEY` / `TENCENT_SECRET_KEY` | Tencent Hunyuan |
| `MOONSHOT_API_KEY` | Moonshot |
| `IFLYTEK_API_KEY` / `IFLYTEK_API_SECRET` | iFlytek Spark |
| `DEEPSEEK_API_KEY` | DeepSeek |
| `XAI_API_KEY` | xAI Grok |
| `CHATGLM_API_KEY` | ChatGLM |
| `SILICONFLOW_API_KEY` | SiliconFlow |

#### Base URLs

| Variable | Default | Description |
|---|---|---|
| `BASE_URL` | `https://api.openai.com` | OpenAI-compatible API base URL |
| `GOOGLE_URL` | *(provider default)* | Google Gemini API URL |
| `ANTHROPIC_URL` | *(provider default)* | Anthropic API URL |
| `DEEPSEEK_URL` | *(provider default)* | DeepSeek API URL |

Each provider has a corresponding `{PROVIDER}_URL` variable.

#### Model Customization

| Variable | Example | Description |
|---|---|---|
| `CUSTOM_MODELS` | `+llama3,+codellama,-gpt-4` | Add models with `+`, remove with `-`. Comma-separated. |
| `DEFAULT_MODEL` | `gpt-4o` | Model selected by default for new conversations. |
| `VISION_MODELS` | `gpt-4o,gemini-pro-vision` | Comma-separated list of models that support image input. |
| `DEFAULT_INPUT_TEMPLATE` | `{{input}}` | Custom template wrapping every user message. |

#### Advanced

| Variable | Default | Description |
|---|---|---|
| `ENABLE_MCP` | `false` | Set to `"true"` to enable Model Context Protocol support. |
| `WHITE_WEBDAV_ENDPOINTS` | *(empty)* | Additional WebDAV endpoints to whitelist for data sync. |
| `STABILITY_API_KEY` | *(empty)* | Stability AI key for Stable Diffusion image generation. |

> [!NOTE]
> For the full environment variable reference with internal/advanced options, see the Admin Guide.

### 3.2 In-App Settings

Open **Settings** via the gear icon in the sidebar. All settings persist in your browser's `localStorage`.

#### General

| Setting | Default | Description |
|---|---|---|
| Theme | Auto | `Auto`, `Light`, or `Dark`. Auto follows system preference. |
| Language | Auto-detected | 20 languages available (see Localization section). |
| Font Size | 14 | Text size in chat messages. |
| Submit Key | Enter | `Enter` sends; use `Shift+Enter` for newlines. Change to `Ctrl+Enter` if you prefer. |
| Sidebar Width | 300px | Drag or set numerically. |

#### Model Defaults

| Setting | Default | Description |
|---|---|---|
| Model | `gpt-4o-mini` | Default model for new chats. |
| Temperature | 0.5 | Creativity dial: 0 = deterministic, 1 = creative. |
| Top P | 1 | Nucleus sampling. Usually leave at 1 unless you know what you want. |
| Max Tokens | 4000 | Maximum response length. |
| History Messages | 4 | Number of previous messages sent as context. |
| Compress Threshold | 1000 | Character count that triggers conversation compression. |
| Send Memory | Enabled | Includes compressed conversation summary in context. |

#### Artifacts

Enabled by default. When a model returns HTML in a code block, NextChat renders it as a live interactive preview (sandboxed iframe). Toggle in Settings under **Artifacts**.

#### Code Folding

Enabled by default. Long code blocks in responses are collapsed with a click-to-expand toggle. Toggle in Settings.

---

## 4. Core Usage

### 4.1 Chatting

Click **New Chat** (or use the `:new` command) to start a conversation. Type your message and press **Enter** to send.

**Multi-line input:** Press `Shift+Enter` to add a newline without sending. Or change the submit key to `Ctrl+Enter` in Settings.

**Image input:** For vision-capable models (GPT-4o, Gemini Pro Vision, Claude 3, etc.), click the attachment icon to upload an image, or paste an image from your clipboard.

**Streaming:** Responses stream in real-time by default. You can stop generation mid-stream by clicking the stop button.

### 4.2 Chat Commands

Type these commands directly in the chat input box (prefixed with `:` or the full-width `：`):

| Command | Action |
|---|---|
| `:new` | Start a new conversation |
| `:newm` | Start a new conversation with a mask (persona) selection |
| `:next` | Switch to the next conversation |
| `:prev` | Switch to the previous conversation |
| `:clear` | Clear the current conversation history |
| `:fork` | Fork (duplicate) the current conversation |
| `:del` | Delete the current conversation |

### 4.3 URL Query Parameters

Share pre-configured chat links by appending query parameters to the app URL:

| Parameter | Example | Description |
|---|---|---|
| `?fill=Hello` | Pre-fills the input box | Message is placed but not sent |
| `?submit=1` | Combined with `fill`, auto-sends | `?fill=Hello&submit=1` sends immediately |
| `?mask=maskId` | Opens with a specific mask | Load a persona by its ID |
| `?code=mypass` | Pre-fills access code | Useful for sharing with team members |
| `?settings=...` | Import settings via URL | JSON-encoded settings (disabled if `DISABLE_FAST_LINK=1`) |

### 4.4 Conversation Management

- **Rename:** Click the conversation title in the sidebar to edit it.
- **Pin:** Right-click a conversation to pin it to the top of the sidebar.
- **Search:** Use the search bar at the top of the sidebar to find conversations by content.
- **Export:** Open a conversation, click the share/export icon to download as Markdown, image, or share via link.
- **Delete:** Swipe left (mobile) or right-click → Delete (desktop).

### 4.5 Multi-Model Support

Switch models mid-conversation by clicking the model name at the top of the chat window. Each conversation remembers its own model selection independently.

**Supported providers and popular models:**

| Provider | Notable Models |
|---|---|
| OpenAI | GPT-4o, GPT-4o-mini, o1, o1-mini |
| Google | Gemini 1.5 Pro, Gemini 1.5 Flash |
| Anthropic | Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku |
| DeepSeek | DeepSeek-V3, DeepSeek-R1 |
| xAI | Grok-2 |
| Moonshot | moonshot-v1-8k, moonshot-v1-32k |
| Alibaba | Qwen-Max, Qwen-Turbo |
| ByteDance | Doubao-Pro |
| SiliconFlow | Various open-source models |

> [!TIP]
> Use `CUSTOM_MODELS` to add any OpenAI-compatible model endpoint. For example, `+my-local-llama` adds a custom model to the dropdown.

---

## 5. Features & Workflows

### 5.1 Masks (Personas)

Masks are pre-configured chat personas that set the system prompt, model, temperature, and other parameters before the conversation starts.

**Using a built-in mask:**
1. Click **New Chat** or type `:newm`.
2. Browse or search the mask gallery.
3. Click a mask to start a conversation with that persona active.

**Creating a custom mask:**
1. Go to **Settings → Mask** (or click the mask icon in the sidebar).
2. Click **Create Mask**.
3. Configure:
   - **Name** and **Avatar** (emoji or text).
   - **Context:** One or more system/user/assistant messages that prime the conversation.
   - **Model Config:** Override model, temperature, top_p, max_tokens for this mask.
   - **Language:** Restrict the mask to a specific locale or leave as "All".
4. Save. The mask appears in your gallery for future use.

**Sharing masks:** Export a mask as JSON from the mask editor. Others can import it.

### 5.2 Plugins (Function Calling)

NextChat supports OpenAPI-based plugins that extend model capabilities through function calling.

**Setting up a plugin:**
1. Go to **Settings → Plugin** or access the plugin store.
2. Click **Create Plugin**.
3. Paste a YAML-formatted OpenAPI specification. The spec must define `paths`, `operationId`, and parameter schemas.
4. Configure authentication if the API requires it:
   - **None** — no auth headers.
   - **Bearer** — sends `Authorization: Bearer <token>`.
   - **Basic** — sends `Authorization: Basic <base64>`.
   - **Custom Header** — arbitrary header name and value.
5. Save the plugin.

During chat, the model can invoke your plugin's endpoints as tool calls. The results are injected back into the conversation context.

> [!NOTE]
> Plugin support requires a model that supports function calling (GPT-4o, GPT-3.5-turbo, Claude 3, Gemini 1.5, etc.).

### 5.3 MCP (Model Context Protocol)

MCP enables the model to interact with external tools and data sources through a standardized protocol.

**To enable MCP:**
1. Set the environment variable `ENABLE_MCP=true` on your deployment.
2. In **Settings → MCP**, configure your MCP server endpoints.
3. The model can then access tools provided by the MCP servers during conversation.

> [!IMPORTANT]
> MCP is experimental. It requires compatible MCP server implementations and a model that supports tool use.

### 5.4 Text-to-Speech (TTS)

NextChat can read responses aloud using two TTS engines.

**OpenAI TTS:**
- Models: `tts-1` (fast), `tts-1-hd` (higher quality).
- Voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`.
- Requires an OpenAI API key with TTS access.

**Edge TTS:**
- Uses Microsoft Edge's browser-based TTS engine.
- Free, but requires network connectivity.
- Broader language coverage.

**Configuration:**
1. Open **Settings**.
2. Under **TTS**, toggle it on.
3. Select the engine (OpenAI or Edge).
4. Choose model and voice.
5. A speaker icon appears on each assistant message — click to hear it read aloud.

### 5.5 Realtime Audio Chat

For live voice conversations with the AI:

1. Enable **Realtime** in Settings.
2. Select a provider (OpenAI or Azure) and a realtime-capable model.
3. Configure voice preference and temperature.
4. In a conversation, click the microphone icon to start a voice session.

> [!WARNING]
> Realtime audio uses OpenAI's realtime API, which has separate pricing from standard chat completions. Monitor usage carefully.

### 5.6 Stable Diffusion (Image Generation)

Generate images directly in chat using Stability AI:

1. Set `STABILITY_API_KEY` in your environment variables.
2. In chat, describe the image you want. The model invokes Stable Diffusion via the `v2beta/stable-image/generate` endpoint.
3. Generated images appear inline in the conversation.

Access your generation history via the **SD** panel in the sidebar.

### 5.7 Data Sync

Sync your chat history, masks, and settings across devices using WebDAV or Upstash.

#### WebDAV Setup

1. Open **Settings → Sync**.
2. Select **WebDAV** as the sync provider.
3. Enter your WebDAV endpoint URL, username, and password.

**Pre-approved WebDAV services** (hardcoded whitelist):
- Jianguoyun (坚果云)
- DropDAV
- Box
- TeraCloud (nanao.teracloud.jp / bora.teracloud.jp)
- 4shared
- iDriveSync
- Yandex Disk
- Koofr

To use a WebDAV provider not on this list, the deployment admin must add it via the `WHITE_WEBDAV_ENDPOINTS` environment variable.

#### Upstash (Redis) Setup

1. Create a free Redis database at [Upstash](https://upstash.com).
2. Open **Settings → Sync**.
3. Select **Upstash** as the sync provider.
4. Enter:
   - **Endpoint:** Your Upstash Redis REST URL.
   - **Username:** Defaults to `chatgpt-next-web`.
   - **API Key:** Your Upstash REST token.
5. Click **Sync** to push/pull data.

### 5.8 PWA Installation

NextChat works as a Progressive Web App. On supported browsers:

1. Visit your NextChat deployment URL.
2. Look for the "Install" prompt in the browser address bar (Chrome/Edge) or use **Share → Add to Home Screen** (Safari/iOS).
3. The app installs as a standalone window with offline caching of the UI shell.

### 5.9 Artifacts (Live HTML Preview)

When a model returns HTML inside a code block, NextChat renders it as a live, interactive preview in a sandboxed iframe. This is useful for:

- Quick prototypes and UI mockups
- Interactive charts and visualizations
- Mini web apps

Toggle artifacts on/off in **Settings → Artifacts**. Artifacts are enabled by default.

> [!CAUTION]
> Artifacts execute HTML/JS in a sandboxed iframe. While sandboxed, always review generated code before interacting with artifacts that handle sensitive data.

---

## 6. Common Tasks & Recipes

### Recipe 1: Set Up a Team Deployment with Shared Access

```bash
docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY=sk-your-org-key \
  -e CODE=team-alpha-2024,team-beta-2024 \
  -e HIDE_USER_API_KEY=1 \
  -e DISABLE_GPT4=0 \
  -e DEFAULT_MODEL=gpt-4o-mini \
  yidadaa/chatgpt-next-web
```

Distribute the access codes to team members. They cannot see or override the API key.

### Recipe 2: Use Multiple OpenAI Keys for Load Balancing

```bash
OPENAI_API_KEY=sk-key1,sk-key2,sk-key3
```

NextChat randomly selects one key per request, spreading rate limits across keys.

### Recipe 3: Connect to a Local LLM (Ollama, LM Studio, etc.)

```bash
docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY=not-needed \
  -e BASE_URL=http://host.docker.internal:11434/v1 \
  -e CUSTOM_MODELS=+llama3,+codellama,-gpt-4,-gpt-4o,-gpt-3.5-turbo \
  -e DEFAULT_MODEL=llama3 \
  yidadaa/chatgpt-next-web
```

The `BASE_URL` points to your local OpenAI-compatible server. Use `CUSTOM_MODELS` to add your local models and remove cloud ones.

### Recipe 4: Multi-Provider Setup

```bash
docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY=sk-openai-key \
  -e GOOGLE_API_KEY=AIza-google-key \
  -e ANTHROPIC_API_KEY=sk-ant-anthropic-key \
  -e DEEPSEEK_API_KEY=sk-deepseek-key \
  -e CODE=mycode \
  yidadaa/chatgpt-next-web
```

Users can switch between providers and models freely within the same interface.

### Recipe 5: Create a Customer Support Persona

1. Create a new mask named "Support Agent".
2. Add a system context message:
   ```
   You are a helpful customer support agent for Acme Corp.
   Be professional, concise, and empathetic. If you don't know
   the answer, say so and offer to escalate. Never make up
   product features.
   ```
3. Set temperature to `0.3` for consistent responses.
4. Set the model to `gpt-4o-mini` for cost efficiency.
5. Save and share the mask JSON with your team.

### Recipe 6: Set Up WebDAV Sync with Jianguoyun

1. Register at [jianguoyun.com](https://www.jianguoyun.com).
2. Go to **Account → Security → Third-party app management** and create an app password.
3. In NextChat Settings → Sync → WebDAV:
   - Endpoint: `https://dav.jianguoyun.com/dav/`
   - Username: your Jianguoyun email
   - Password: the app password (not your account password)
4. Click Sync.

### Recipe 7: Hide All Model Options for End Users

```bash
HIDE_USER_API_KEY=1
CUSTOM_MODELS=-gpt-4,-gpt-4o,-o1,-o1-mini
DEFAULT_MODEL=gpt-4o-mini
```

This locks users to `gpt-4o-mini` only, with no ability to enter their own keys.

### Recipe 8: Enable Text-to-Speech by Default

1. In Settings → TTS, toggle on.
2. Select engine: **OpenAI TTS**.
3. Model: `tts-1` (or `tts-1-hd` for quality).
4. Voice: `nova` (natural-sounding female) or `onyx` (male).
5. Each response now has a speaker icon for playback.

### Recipe 9: Generate Images in Chat

1. Set `STABILITY_API_KEY` in your deployment environment.
2. Start a conversation and ask the model to generate an image. For example: "Generate a watercolor painting of a mountain lake at sunset."
3. The model calls the Stability AI endpoint and renders the result inline.

### Recipe 10: Fork a Conversation to Explore Alternatives

Mid-conversation, type `:fork` to duplicate the entire conversation. Continue the fork in a different direction while preserving the original. This is useful for A/B testing prompts or exploring "what if" branches.

### Recipe 11: Bulk Import Masks

1. Collect mask JSON objects into an array.
2. Navigate to your NextChat URL with `?masks=[{...},{...}]` (URL-encoded).
3. Or paste the JSON into the mask import dialog in Settings → Mask → Import.

### Recipe 12: Use NextChat as a Desktop App

1. Download the Tauri binary from [GitHub Releases](https://github.com/ChatGPTNextWeb/NextChat/releases).
2. Install and launch.
3. The desktop app runs the same UI but as a native window — no browser required, better system tray integration, and local storage stays on your machine.

---

## 7. Localization

NextChat supports 20 languages. The interface language is auto-detected from your browser locale, or you can set it manually in **Settings → Language**.

| Code | Language |
|---|---|
| `cn` | 简体中文 (Simplified Chinese) |
| `tw` | 繁體中文 (Traditional Chinese) |
| `en` | English |
| `ja` | 日本語 (Japanese) |
| `ko` | 한국어 (Korean) |
| `fr` | Français (French) |
| `es` | Español (Spanish) |
| `it` | Italiano (Italian) |
| `de` | Deutsch (German) |
| `pt` | Português (Portuguese) |
| `ru` | Русский (Russian) |
| `tr` | Türkçe (Turkish) |
| `vi` | Tiếng Việt (Vietnamese) |
| `ar` | العربية (Arabic) |
| `cs` | Čeština (Czech) |
| `no` | Nynorsk (Norwegian) |
| `id` | Indonesia (Indonesian) |
| `da` | Dansk (Danish) |
| `bn` | বাংলা (Bengali) |
| `sk` | Slovensky (Slovak) |

---

## 8. Data & Storage

NextChat stores all data locally in your browser.

| Store | Backend | Key | Contents |
|---|---|---|---|
| Chat history | IndexedDB | `chat-next-web-store` | All conversations and messages |
| App config | localStorage | `app-config` | Theme, model defaults, TTS settings |
| Access control | localStorage | `access-control` | Access code state |
| Masks | localStorage | `mask-store` | Custom and built-in masks |
| Prompts | localStorage | `prompt-store` | Saved prompt templates |
| Sync config | localStorage | `sync` | WebDAV/Upstash credentials |
| Plugins | localStorage | `chat-next-web-plugin` | Plugin definitions |
| SD history | localStorage | `sd-list` | Stable Diffusion generation log |
| MCP config | localStorage | `mcp-store` | MCP server configurations |

> [!WARNING]
> Clearing your browser data deletes all conversations and settings. Use Data Sync (WebDAV or Upstash) to back up your data. There is no server-side storage.

### Exporting Data

- **Single conversation:** Open the chat → click the share/export icon → choose Markdown or image.
- **All data:** Settings → Danger Zone → Export All Data → downloads a JSON backup.
- **Import:** Settings → Danger Zone → Import Data → upload a previously exported JSON file.

---

## 9. Troubleshooting

### Error: `Failed to fetch`

**Cause:** The browser cannot reach the API endpoint. Common when running behind a corporate proxy, with DNS issues, or when the `BASE_URL` is misconfigured.

**Solution:**
1. Verify your internet connection.
2. If using a custom `BASE_URL`, confirm it is reachable: `curl https://your-base-url/v1/models`.
3. Check for CORS issues in the browser console (F12 → Console).
4. If running Docker behind a reverse proxy, ensure the proxy forwards WebSocket connections.

**Prevention:** Test API connectivity before deploying to users.

---

### Error: `Invalid API Key`

**Cause:** The API key is missing, expired, revoked, or does not have the required permissions.

**Solution:**
1. Verify the key on the provider's dashboard (OpenAI, Anthropic, etc.).
2. Check that the key matches the provider — an OpenAI key will not work with the Anthropic provider.
3. If using `OPENAI_API_KEY` with multiple comma-separated keys, ensure none have trailing spaces.
4. Regenerate the key if it may have been compromised.

**Prevention:** Use environment variables rather than pasting keys into the UI, especially for shared deployments.

---

### Error: `Access Code Required` or blank screen on first load

**Cause:** The `CODE` environment variable is set, but the user has not entered a valid access code.

**Solution:**
1. Enter a valid access code on the auth screen.
2. If you are the admin, verify the codes in your `CODE` environment variable.
3. Access codes are case-sensitive. Double-check for typos.

**Prevention:** Share access codes through a secure channel.

---

### Error: `You exceeded your current quota`

**Cause:** The API key has hit its spending limit or rate limit with the provider.

**Solution:**
1. Check your usage dashboard on the provider's website.
2. Increase your spending limit or upgrade your plan.
3. If using multiple keys (`OPENAI_API_KEY=key1,key2`), ensure all keys have sufficient quota.
4. Reduce `max_tokens` in Settings to lower per-request cost.

**Prevention:** Set up billing alerts on your provider dashboard. Use `ENABLE_BALANCE_QUERY=1` to monitor balance from within NextChat.

---

### Issue: Responses are slow or laggy

**Cause:** Network latency, large conversation context, or a slow model.

**Solution:**
1. Reduce **History Messages** in Settings (default 4) to send less context.
2. Switch to a faster model (e.g., `gpt-4o-mini` instead of `gpt-4o`).
3. Lower the **Compress Threshold** to trigger summarization earlier.
4. If self-hosting, ensure the server has low latency to the API provider.

---

### Issue: Input lag when typing long messages

**Cause:** Known performance issue (#5799) with very long text in the input textarea, caused by React re-renders.

**Solution:**
1. Draft long prompts in an external text editor and paste them in.
2. Keep individual messages under ~5,000 characters; split into multiple messages if needed.

---

### Issue: Conversations disappeared after browser update

**Cause:** Browser cleared IndexedDB or localStorage during the update or a storage cleanup sweep.

**Solution:**
1. Check if the data exists in another browser or incognito session.
2. If you had sync configured, click **Sync** in Settings to pull data from WebDAV/Upstash.
3. If you have a JSON backup, go to Settings → Import Data.

**Prevention:** Always configure data sync (WebDAV or Upstash) as an automatic backup.

---

### Issue: WebDAV sync fails with "endpoint not allowed"

**Cause:** The WebDAV endpoint is not in the hardcoded whitelist.

**Solution:**
1. Verify your endpoint URL matches one of the approved services (Jianguoyun, DropDAV, Box, TeraCloud, 4shared, iDriveSync, Yandex, Koofr).
2. If using a different provider, the deployment admin must add it via `WHITE_WEBDAV_ENDPOINTS`.

---

### Issue: Custom models do not appear in the dropdown

**Cause:** Incorrect `CUSTOM_MODELS` syntax or a deployment that has not been restarted after the change.

**Solution:**
1. Verify syntax: `CUSTOM_MODELS=+model-name-1,+model-name-2` (prefix with `+` to add).
2. Redeploy or restart the container after changing environment variables.
3. Hard-refresh the browser (`Ctrl+Shift+R`) to clear cached model lists.

---

### Issue: TTS playback produces no sound

**Cause:** Browser autoplay policy blocking audio, missing API key, or wrong TTS engine configuration.

**Solution:**
1. Click somewhere on the page first (browsers require user interaction before audio playback).
2. If using OpenAI TTS, verify your API key has TTS access.
3. If using Edge TTS, confirm network connectivity (it streams from Microsoft servers).
4. Check browser console for errors (F12 → Console).

---

### Issue: Docker container exits immediately

**Cause:** Missing required environment variables or port conflict.

**Solution:**
1. Check logs: `docker logs <container-id>`.
2. Ensure port 3000 is not in use: `lsof -i :3000` (Linux/Mac) or `netstat -ano | findstr 3000` (Windows).
3. Verify environment variable syntax — no quotes needed in Docker `-e` flags, but YAML values in `docker-compose.yml` may need quoting.

---

### Issue: Artifacts render as blank iframes

**Cause:** Content Security Policy (CSP) blocking iframe content, or the generated HTML has errors.

**Solution:**
1. Check that Artifacts are enabled in Settings.
2. Open browser developer tools (F12) and check the Console tab for CSP or JavaScript errors.
3. If behind a strict reverse proxy, ensure the CSP headers allow `blob:` and `data:` URIs.
4. Try a simpler HTML prompt to test: "Create an HTML page with a red button."

---

### Issue: Realtime audio does not connect

**Cause:** Missing realtime API access, unsupported browser, or microphone permissions denied.

**Solution:**
1. Verify your OpenAI API key has access to the realtime API (it is a separate product).
2. Use Chrome or Edge (realtime audio requires WebRTC support).
3. Grant microphone permission when the browser prompts.
4. Check that no other application is exclusively using the microphone.

---

## 10. FAQ

**Q: Is my data sent to NextChat's servers?**

No. NextChat is a pure frontend application. Your messages go directly from your browser to the LLM provider's API (OpenAI, Google, etc.). The NextChat server only serves static files and proxies API requests. No conversation data is stored server-side.

---

**Q: Can I use NextChat without an API key?**

Only if the deployment admin has configured a server-side API key. For personal use, you need at least one provider API key (OpenAI, Google, Anthropic, etc.).

---

**Q: How do I update to the latest version?**

- **Vercel:** Sync your fork with upstream on GitHub, then Vercel auto-deploys.
- **Docker:** Pull the latest image and restart: `docker pull yidadaa/chatgpt-next-web && docker compose up -d`.
- **Desktop:** Download the latest release from GitHub Releases.

---

**Q: Which model should I use?**

For most users: `gpt-4o-mini` offers the best balance of speed, quality, and cost. For complex reasoning: `gpt-4o`, `claude-3.5-sonnet`, or `deepseek-r1`. For speed: `gpt-4o-mini` or `gemini-1.5-flash`.

---

**Q: Can I use NextChat with Azure OpenAI?**

Yes. Set the Azure-specific environment variables (`AZURE_URL`, `AZURE_API_KEY`, `AZURE_API_VERSION`) and select Azure as the provider in Settings.

---

**Q: Does NextChat support file uploads?**

NextChat supports image uploads for vision-capable models. General file uploads (PDFs, documents) are not natively supported in the base app, though plugins can extend this capability.

---

**Q: How do I limit which models users can access?**

Use the `CUSTOM_MODELS` environment variable. Prefix models with `-` to remove them: `CUSTOM_MODELS=-gpt-4,-gpt-4o,-o1` removes those models from the dropdown. Set `DEFAULT_MODEL` to the one you want users to use.

---

**Q: Can I run multiple instances synced together?**

Yes. Configure all instances to sync via the same WebDAV folder or Upstash Redis database. Each device pulls the latest state on sync. Note that sync is manual (click the sync button) — it is not automatic real-time sync.

---

**Q: What is the difference between masks and system prompts?**

A mask is a complete configuration package: it includes system prompt context messages, model selection, temperature, and other parameters. A system prompt is just one part of a mask. Masks let you switch between entire "personalities" with different models and settings in one click.

---

**Q: How do I completely reset the app?**

Clear your browser's site data for the NextChat domain. In Chrome: F12 → Application → Storage → Clear site data. This removes all conversations, settings, masks, and plugins. There is no undo — back up first via Settings → Export Data.

---

**Q: Can multiple users share one deployment without seeing each other's chats?**

Yes. Each user's data is stored in their own browser's local storage. Users on the same deployment URL cannot see each other's conversations. They share the API key and access codes, but not chat data.

---

**Q: Why does the app show "Unauthorized" when I enter my access code?**

Access codes in the `CODE` environment variable are hashed with MD5 internally. If you recently changed the codes, redeploy the application. Also verify that the code is entered exactly as specified — codes are case-sensitive with no leading or trailing spaces.

---

**Q: Is there a mobile app?**

There is no dedicated iOS/Android app, but NextChat works excellently as a PWA. Install it via your mobile browser's "Add to Home Screen" option for a near-native experience with offline UI caching and full-screen mode.

---

_Generated May 2026 from ChatGPTNextWeb/NextChat at c3b8c15. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._