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.
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.

# 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:

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.

# 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:

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

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 page. Download the installer for your platform and run it.

To build from source:

# 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

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

Provider Keys

Base URLs

Each provider has a corresponding {PROVIDER}_URL variable.

Model Customization

Advanced

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

Model Defaults

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 ：):

4.3 URL Query Parameters

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

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:

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.
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

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

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.)

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

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.
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

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.
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.

8. Data & Storage

NextChat stores all data locally in your browser.

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.