Skip to content

Open source AI coding agent. Designed for large projects and real world tasks.

Update documentation for optional OpenAI key

Dane Schneider824f0ff7eb98
diff --git a/README.md b/README.md
index 1d5be740..33c6df1c 100644
--- a/README.md
+++ b/README.md
@@ -96,7 +96,7 @@
- 🗺️ **Fast project map generation** and syntax validation with tree-sitter. Supports 30+ languages.
-- 💰 **Context caching** is used across the board for OpenAI and Anthropic models, reducing costs and latency.
+- 💰 **Context caching** is used across the board for OpenAI, Anthropic, and Google models, reducing costs and latency.
## Tight control or full autonomy—it's up to you
@@ -156,15 +156,20 @@ curl -sL https://plandex.ai/install.sh | bash
| Option | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plandex Cloud (Integrated Models)** | • No separate accounts or API keys.<br/>• Easy multi-device usage.<br/>• Centralized billing, budgeting, usage tracking, and cost reporting.<br/>• Quickest way to [get started.](https://app.plandex.ai/start?modelsMode=integrated) |
-| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) keys.<br/>• [Get started](https://app.plandex.ai/start?modelsMode=byo) |
-| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) keys.<br/>• Follow the [local-mode quickstart](https://docs.plandex.ai/hosting/self-hosting/local-mode-quickstart) to get started. |
+| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) key (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/>• [Get started](https://app.plandex.ai/start?modelsMode=byo) |
+| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) key (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/>• Follow the [local-mode quickstart](./hosting/self-hosting.md) to get started. |
## Provider keys  🔑
-If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set the `OPENROUTER_API_KEY` and `OPENAI_API_KEY` environment variables before continuing:
+If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set the `OPENROUTER_API_KEY` environment variable before continuing:
```bash
export OPENROUTER_API_KEY=...
+```
+
+You can also **optionally** set a `OPENAI_API_KEY` environment variable if you want OpenAI models to use the OpenAI API directly instead of OpenRouter (for slightly lower latency and costs):
+
+```bash
export OPENAI_API_KEY=...
```
diff --git a/docs/docs/cli-reference.md b/docs/docs/cli-reference.md
index 5d9c74dd..ed1ad448 100644
--- a/docs/docs/cli-reference.md
+++ b/docs/docs/cli-reference.md
@@ -67,7 +67,7 @@ The REPL has a few convenient flags you can use to start it with different modes
--strong Strong pack (more capable models, higher cost and slower)
--cheap Cheap pack (less capable models, lower cost and faster)
--oss Open source pack (open source models)
- --gemini-exp Gemini experimental pack (Gemini 2.5 Pro Experimental for planning and coding, default models for other roles)
+ --gemini-preview Gemini preview pack (Gemini 2.5 Pro Preview for planning and coding, default models for other roles)
```
All commands listed below can be run in the REPL by prefixing them with a backslash (`\`), e.g. `\new`.
diff --git a/docs/docs/hosting/self-hosting/local-mode-quickstart.md b/docs/docs/hosting/self-hosting/local-mode-quickstart.md
index 5f51b622..27fecf06 100644
--- a/docs/docs/hosting/self-hosting/local-mode-quickstart.md
+++ b/docs/docs/hosting/self-hosting/local-mode-quickstart.md
@@ -36,13 +36,13 @@ plandex sign-in
5. If you don't have an OpenRouter account, first [sign up here.](https://openrouter.ai/signup) Then [generate an API key here.](https://openrouter.ai/keys) Set the `OPENROUTER_API_KEY` environment variable:
```bash
-export OPENROUTER_API_KEY=<your-openrouter-api-key>
+export OPENROUTER_API_KEY=...
```
-6. If you don't have an OpenAI account, first [sign up here.](https://platform.openai.com/signup) Then [generate an API key here.](https://platform.openai.com/account/api-keys) Set the `OPENAI_API_KEY` environment variable:
+6. **Optional**: set a `OPENAI_API_KEY` environment variable if you want OpenAI models to use the OpenAI API directly instead of OpenRouter (for slightly lower latency and costs). This requires an [OpenAI account.](https://platform.openai.com/signup).
```bash
-export OPENAI_API_KEY=<your-openai-api-key>
+export OPENAI_API_KEY=...
```
7. In a project directory, start the Plandex REPL:
diff --git a/docs/docs/models/model-providers.md b/docs/docs/models/model-providers.md
index 1766368e..0ee71b8f 100644
--- a/docs/docs/models/model-providers.md
+++ b/docs/docs/models/model-providers.md
@@ -5,7 +5,7 @@ sidebar_label: Providers
# Model Providers
-By default, Plandex uses a mix of Anthropic, OpenAI, and Google models. OpenAI models call the OpenAI API directly, while all other models are called via [OpenRouter.ai](https://openrouter.ai/).
+By default, Plandex uses a mix of Anthropic, OpenAI, and Google models. If an OpenAI API key is set, OpenAI models will use the OpenAI API directly. Otherwise, all models will use [OpenRouter.ai](https://openrouter.ai/).
You can also use Plandex with models from any provider that provides an OpenAI-compatible API, like the aforementioned [OpenRouter.ai](https://openrouter.ai/), [Together.ai](https://together.ai), [Replicate](https://replicate.com/), [Ollama](https://ollama.com/), and more.
@@ -13,6 +13,12 @@ You can also use Plandex with models from any provider that provides an OpenAI-c
While you can use Plandex with many different providers and models as described above, Plandex's prompts have mainly been written and tested against the built-in models and model packs, so you should expect them to give the best results.
+### Local Models Disclaimer
+
+In particular, small models that can be run locally generally aren't strong enough to produce usable results for the [heavy-lifting roles][./roles.md] like `planner`, `architect`, `coder`, and `builder`. The prompts for these roles require very strong instruction following that is hard to achieve with small models.
+
+The strongest open source models like DeepSeek R1 and V3 _are_ capable enough for decent results, but these models are quite large for running locally without a very powerful system. This isn't meant to discourage experimentation with local models, but to set expectations for what is realistically achievable.
+
## Built-in Models and Model Packs
Plandex provides a curated set of built-in models and model packs.
@@ -49,6 +55,10 @@ Once you've created an OpenRouter account, [generate an API key here.](https://o
## OpenAI
+Note that as of v2.0.8, setting an OpenAI API key is **optional**. Plandex will use OpenRouter as a fallback for OpenAI models if no OpenAI API key is set.
+
+If you do set an OpenAI API key, Plandex will call the OpenAI API directly for OpenAI models, which offers slightly lower latency and costs about 5% less than OpenRouter.
+
### Account
If you don't have an OpenAI account, first [sign up here.](https://platform.openai.com/signup)
diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md
index e915348d..6499e9f1 100644
--- a/docs/docs/quick-start.md
+++ b/docs/docs/quick-start.md
@@ -20,13 +20,18 @@ Note that Windows is supported via [WSL](https://learn.microsoft.com/en-us/windo
| Option | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plandex Cloud (Integrated Models)** | • No separate accounts or API keys.<br/>• Easy multi-device usage.<br/>• Centralized billing, budgeting, usage tracking, and cost reporting.<br/>• Quickest way to [get started.](https://app.plandex.ai/start?modelsMode=integrated) |
-| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) keys.<br/> |
-| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) and [OpenAI](https://platform.openai.com) keys.<br/>• Follow the [local-mode quickstart](./hosting/self-hosting/local-mode-quickstart.md) to get started. |
+| **Plandex Cloud (BYO API Key)** | • Use Plandex Cloud with your own [OpenRouter.ai](https://openrouter.ai) key (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/> |
+| **Self-hosted/Local Mode** | • Run Plandex locally with Docker or host on your own server.<br/>• Use your own [OpenRouter.ai](https://openrouter.ai) (and **optionally** your own [OpenAI](https://platform.openai.com) key).<br/>• Follow the [local-mode quickstart](./hosting/self-hosting/local-mode-quickstart.md) to get started. |
-If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), you'll need to set the `OPENROUTER_API_KEY` and `OPENAI_API_KEY` environment variables before continuing:
+If you're going with a 'BYO API Key' option above (whether cloud or self-hosted), and you don't have an OpenRouter account, first [sign up here.](https://openrouter.ai/signup) Then [generate an API key here.](https://openrouter.ai/keys) Set the `OPENROUTER_API_KEY` environment variable:
```bash
export OPENROUTER_API_KEY=...
+```
+
+You can also **optionally** set a `OPENAI_API_KEY` environment variable if you want OpenAI models to use the OpenAI API directly instead of OpenRouter (for slightly lower latency and costs). This requires an [OpenAI account.](https://platform.openai.com/signup).
+
+```bash
export OPENAI_API_KEY=...
```