converse-mcp-server 1.18.0-beta.5 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +90 -90
- package/docs/PROVIDERS.md +261 -261
- package/package.json +1 -1
- package/src/providers/codex.js +9 -5
- package/src/providers/index.js +96 -96
- package/src/tools/chat.js +4 -4
- package/src/tools/consensus.js +4 -4
- package/src/utils/pathUtils.js +223 -199
package/docs/PROVIDERS.md
CHANGED
|
@@ -1,262 +1,262 @@
|
|
|
1
|
-
# AI Provider Configuration Guide
|
|
2
|
-
|
|
3
|
-
This guide documents all supported AI providers in the Converse MCP Server and their configuration options.
|
|
4
|
-
|
|
5
|
-
## Supported Providers
|
|
6
|
-
|
|
7
|
-
### OpenAI
|
|
8
|
-
- **API Key Format**: `sk-proj-...` (starts with `sk-`)
|
|
9
|
-
- **Get Key**: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
|
|
10
|
-
- **Environment Variable**: `OPENAI_API_KEY`
|
|
11
|
-
- **Supported Models**:
|
|
12
|
-
- `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-pro` - GPT-5 family with advanced reasoning
|
|
13
|
-
- `o3`, `o3-mini`, `o3-pro` - Advanced reasoning models
|
|
14
|
-
- `o4-mini` - Latest fast reasoning model
|
|
15
|
-
- `gpt-4.1` - Large context (1M tokens)
|
|
16
|
-
- `gpt-4o`, `gpt-4o-mini` - Multimodal models
|
|
17
|
-
|
|
18
|
-
### Google (Gemini)
|
|
19
|
-
- **API Key Format**: `AIzaSy...` (varies)
|
|
20
|
-
- **Get Key**: [makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey)
|
|
21
|
-
- **Environment Variable**: `GOOGLE_API_KEY`
|
|
22
|
-
- **Supported Models**:
|
|
23
|
-
- `gemini-2.5-pro` - Deep reasoning with thinking mode
|
|
24
|
-
- `gemini-2.5-flash` - Ultra-fast model
|
|
25
|
-
- `gemini-2.0-flash`, `gemini-2.0-flash-lite` - Latest generation
|
|
26
|
-
|
|
27
|
-
### X.AI (Grok)
|
|
28
|
-
- **API Key Format**: `xai-...` (starts with `xai-`)
|
|
29
|
-
- **Get Key**: [console.x.ai](https://console.x.ai/)
|
|
30
|
-
- **Environment Variable**: `XAI_API_KEY`
|
|
31
|
-
- **Supported Models**:
|
|
32
|
-
- `grok-4-0709` - Latest with image support and web search
|
|
33
|
-
- `grok-code-fast-1` - Speedy and economical reasoning model that excels at agentic coding
|
|
34
|
-
|
|
35
|
-
### Anthropic (Claude)
|
|
36
|
-
- **API Key Format**: `sk-ant-...` (starts with `sk-ant-`)
|
|
37
|
-
- **Get Key**: [console.anthropic.com](https://console.anthropic.com/)
|
|
38
|
-
- **Environment Variable**: `ANTHROPIC_API_KEY`
|
|
39
|
-
- **Supported Models**:
|
|
40
|
-
- `claude-opus-4-1-20250805` - Highest intelligence with extended thinking (32K output)
|
|
41
|
-
- `claude-sonnet-4-20250514` - Balanced performance with extended thinking (64K output)
|
|
42
|
-
- `claude-3-7-sonnet-20250219` - Enhanced 3.x generation with thinking (64K output)
|
|
43
|
-
- `claude-3-5-sonnet-20241022` - Fast and intelligent model (8K output)
|
|
44
|
-
- `claude-3-5-haiku-20241022` - Fastest Claude model (8K output)
|
|
45
|
-
- `claude-3-opus-20240229`, `claude-3-sonnet-20240229`, `claude-3-haiku-20240307` - Previous generation
|
|
46
|
-
|
|
47
|
-
### Mistral
|
|
48
|
-
- **API Key Format**: 32+ character string
|
|
49
|
-
- **Get Key**: [console.mistral.ai](https://console.mistral.ai/)
|
|
50
|
-
- **Environment Variable**: `MISTRAL_API_KEY`
|
|
51
|
-
- **Supported Models**:
|
|
52
|
-
- `mistral-large-latest` - Most capable model
|
|
53
|
-
- `mistral-medium-latest` - Balanced performance
|
|
54
|
-
- `mistral-small-latest` - Fast and efficient
|
|
55
|
-
- `open-mistral-7b`, `open-mixtral-8x7b`, `open-mixtral-8x22b` - Open-source models
|
|
56
|
-
|
|
57
|
-
### DeepSeek
|
|
58
|
-
- **API Key Format**: 32+ character string
|
|
59
|
-
- **Get Key**: [platform.deepseek.com](https://platform.deepseek.com/)
|
|
60
|
-
- **Environment Variable**: `DEEPSEEK_API_KEY`
|
|
61
|
-
- **Supported Models**:
|
|
62
|
-
- `deepseek-chat` - Advanced conversational model
|
|
63
|
-
- `deepseek-coder` - Specialized for code generation
|
|
64
|
-
|
|
65
|
-
### OpenRouter
|
|
66
|
-
- **API Key Format**: `sk-or-...` (starts with `sk-or-`)
|
|
67
|
-
- **Get Key**: [openrouter.ai/keys](https://openrouter.ai/keys)
|
|
68
|
-
- **Environment Variables**:
|
|
69
|
-
- `OPENROUTER_API_KEY` - Your API key
|
|
70
|
-
- `OPENROUTER_REFERER` - Required referer URL (e.g., your GitHub repo)
|
|
71
|
-
- `OPENROUTER_TITLE` - Optional title for request tracking
|
|
72
|
-
- `OPENROUTER_DYNAMIC_MODELS` - Enable dynamic model discovery (default: false, required for `provider/model` format)
|
|
73
|
-
- **Static Models**: Pre-configured models available without dynamic discovery
|
|
74
|
-
- `qwen/qwen3-235b-a22b-thinking-2507` - Qwen3 235B with thinking capabilities
|
|
75
|
-
- `qwen/qwen3-coder` - Qwen3 specialized for coding
|
|
76
|
-
- `moonshotai/kimi-k2` - Kimi K2 with 200K context window
|
|
77
|
-
- `openrouter/auto` - Auto-selects best model using NotDiamond routing
|
|
78
|
-
- **Dynamic Models**: Requires `OPENROUTER_DYNAMIC_MODELS=true` to use any model in `provider/model` format
|
|
79
|
-
- `anthropic/claude-3.5-sonnet`
|
|
80
|
-
- `openai/gpt-4-turbo`
|
|
81
|
-
- `google/gemini-pro`
|
|
82
|
-
- `mistralai/mistral-large`
|
|
83
|
-
- `meta-llama/llama-3.1-405b-instruct`
|
|
84
|
-
- And many more - see [openrouter.ai/models](https://openrouter.ai/models)
|
|
85
|
-
|
|
86
|
-
### Codex
|
|
87
|
-
- **API Key Format**: Optional (uses ChatGPT login by default)
|
|
88
|
-
- **Authentication**: ChatGPT login (system-wide) OR `CODEX_API_KEY`
|
|
89
|
-
- **Environment Variables**:
|
|
90
|
-
- `CODEX_API_KEY` - Optional API key for headless deployments
|
|
91
|
-
- `CODEX_SANDBOX_MODE` - Filesystem access control (default: read-only)
|
|
92
|
-
- `CODEX_SKIP_GIT_CHECK` - Skip Git repository validation (default: true)
|
|
93
|
-
- `CODEX_APPROVAL_POLICY` - Command approval behavior (default: never)
|
|
94
|
-
- `CODEX_DEFAULT_MODEL` - Default model (default: gpt-5-codex)
|
|
95
|
-
- **Supported Models**:
|
|
96
|
-
- `codex` - OpenAI Codex agentic coding assistant
|
|
97
|
-
- Thread-based sessions with persistent context
|
|
98
|
-
- Direct filesystem access from working directory
|
|
99
|
-
- Typical response time: 6-20 seconds (longer for complex tasks)
|
|
100
|
-
|
|
101
|
-
**Key Features:**
|
|
102
|
-
- **Thread-Based Sessions**: Maintains full conversation history across requests
|
|
103
|
-
- **Local File Access**: Reads files directly from working directory
|
|
104
|
-
- **Sandbox Modes**: Configurable filesystem access (read-only, workspace-write, danger-full-access)
|
|
105
|
-
- **Approval Policies**: Control command execution behavior
|
|
106
|
-
- **Performance**: Slower than API-based providers (6-20 seconds typical, minutes for complex tasks)
|
|
107
|
-
|
|
108
|
-
**Best Practices:**
|
|
109
|
-
- Use `async: true` for Codex requests (long response times)
|
|
110
|
-
- Set `CODEX_SANDBOX_MODE=read-only` for safe exploration
|
|
111
|
-
- Use `CODEX_APPROVAL_POLICY=never` for headless server deployments
|
|
112
|
-
- Always use `continuation_id` for thread continuation
|
|
113
|
-
|
|
114
|
-
## Configuration Examples
|
|
115
|
-
|
|
116
|
-
### Basic Configuration (.env file)
|
|
117
|
-
```bash
|
|
118
|
-
# Choose one or more providers
|
|
119
|
-
OPENAI_API_KEY=sk-proj-your_key_here
|
|
120
|
-
ANTHROPIC_API_KEY=sk-ant-your_key_here
|
|
121
|
-
MISTRAL_API_KEY=your_mistral_key_here
|
|
122
|
-
DEEPSEEK_API_KEY=your_deepseek_key_here
|
|
123
|
-
|
|
124
|
-
# OpenRouter requires both API key and referer
|
|
125
|
-
OPENROUTER_API_KEY=sk-or-your_key_here
|
|
126
|
-
OPENROUTER_REFERER=https://github.com/YourUsername/YourApp
|
|
127
|
-
# Optional: Enable dynamic model discovery to use any OpenRouter model
|
|
128
|
-
OPENROUTER_DYNAMIC_MODELS=true
|
|
129
|
-
# Optional: Add title for request tracking
|
|
130
|
-
OPENROUTER_TITLE=Converse
|
|
131
|
-
|
|
132
|
-
# Codex - Optional API key (uses ChatGPT login by default)
|
|
133
|
-
CODEX_API_KEY=your_codex_api_key_here # Optional if ChatGPT login available
|
|
134
|
-
CODEX_SANDBOX_MODE=read-only # read-only (default), workspace-write, danger-full-access
|
|
135
|
-
CODEX_SKIP_GIT_CHECK=true # true (default), false
|
|
136
|
-
CODEX_APPROVAL_POLICY=never # never (default), untrusted, on-failure, on-request
|
|
137
|
-
CODEX_DEFAULT_MODEL=gpt-5-codex # Default: gpt-5-codex
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
### Claude Configuration (claude_desktop_config.json)
|
|
141
|
-
```json
|
|
142
|
-
{
|
|
143
|
-
"mcpServers": {
|
|
144
|
-
"converse": {
|
|
145
|
-
"command": "npx",
|
|
146
|
-
"args": ["FallDownTheSystem/converse"],
|
|
147
|
-
"env": {
|
|
148
|
-
"OPENAI_API_KEY": "your_key_here",
|
|
149
|
-
"ANTHROPIC_API_KEY": "your_key_here",
|
|
150
|
-
"MISTRAL_API_KEY": "your_key_here",
|
|
151
|
-
"DEEPSEEK_API_KEY": "your_key_here",
|
|
152
|
-
"OPENROUTER_API_KEY": "your_key_here",
|
|
153
|
-
"OPENROUTER_REFERER": "https://github.com/YourUsername/YourApp",
|
|
154
|
-
"OPENROUTER_DYNAMIC_MODELS": "true",
|
|
155
|
-
"OPENROUTER_TITLE": "Converse"
|
|
156
|
-
}
|
|
157
|
-
}
|
|
158
|
-
}
|
|
159
|
-
}
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
## Provider-Specific Features
|
|
163
|
-
|
|
164
|
-
### Streaming Support
|
|
165
|
-
All providers support streaming responses for real-time output.
|
|
166
|
-
|
|
167
|
-
### Image Support
|
|
168
|
-
- **Full Support**: OpenAI, Google, X.AI (Grok-4), Anthropic (Claude-3.5-Sonnet, Claude-3-Opus)
|
|
169
|
-
- **Via OpenRouter**: Depends on the underlying model
|
|
170
|
-
- **No Support**: DeepSeek, Mistral (except Large), Claude-3.5-Haiku, Codex
|
|
171
|
-
|
|
172
|
-
### Web Search
|
|
173
|
-
- **Native Support**: OpenAI, Google, X.AI (Grok-4)
|
|
174
|
-
- **No Support**: Anthropic, Mistral, DeepSeek, OpenRouter, Codex
|
|
175
|
-
|
|
176
|
-
### Thinking/Reasoning Modes
|
|
177
|
-
- **OpenAI**: O3 series models support `reasoning_effort` parameter
|
|
178
|
-
- **Google**: Gemini Pro/Flash support thinking mode with configurable budget
|
|
179
|
-
- **Anthropic**: Claude 4 and 3.7 models support extended thinking with `reasoning_effort`
|
|
180
|
-
- **Codex**: Thread-based agentic reasoning with persistent context
|
|
181
|
-
- **Others**: Standard inference only
|
|
182
|
-
|
|
183
|
-
### Local Execution
|
|
184
|
-
- **Codex**: Runs locally with direct filesystem access and thread-based sessions
|
|
185
|
-
- **All Others**: API-based remote execution
|
|
186
|
-
|
|
187
|
-
## Model Selection in Tools
|
|
188
|
-
|
|
189
|
-
When using the chat or consensus tools, specify models using their identifiers:
|
|
190
|
-
|
|
191
|
-
### Model Routing Logic
|
|
192
|
-
|
|
193
|
-
1. **Simple Names**: Models without "/" are routed by keyword matching:
|
|
194
|
-
- Contains "gpt", "o1", "o3", "o4" → OpenAI
|
|
195
|
-
- Contains "claude", "opus", "sonnet", "haiku" → Anthropic
|
|
196
|
-
- Contains "gemini", "flash", "pro" → Google
|
|
197
|
-
- Contains "grok" → X.AI
|
|
198
|
-
- Contains "mistral", "magistral" → Mistral
|
|
199
|
-
- Contains "deepseek", "reasoner", "r1" → DeepSeek
|
|
200
|
-
- Contains "qwen", "kimi", "k2" → OpenRouter
|
|
201
|
-
|
|
202
|
-
2. **Slash Format**: Models with "/" check native providers first:
|
|
203
|
-
- If exact model exists in a native provider → Routes to that provider
|
|
204
|
-
- If not found in any native provider → Routes to OpenRouter
|
|
205
|
-
- This allows using models like "anthropic/claude-3.5-sonnet" via OpenRouter
|
|
206
|
-
|
|
207
|
-
3. **OpenRouter Auto**: Special aliases route to OpenRouter's auto-selection:
|
|
208
|
-
- "openrouter/auto", "openrouter auto", "auto router", "auto-router"
|
|
209
|
-
|
|
210
|
-
```javascript
|
|
211
|
-
// Chat tool examples
|
|
212
|
-
{
|
|
213
|
-
"model": "gpt-4o", // OpenAI (keyword match)
|
|
214
|
-
"model": "claude-opus-4", // Anthropic (keyword match, auto-resolves)
|
|
215
|
-
"model": "sonnet", // Anthropic (keyword match)
|
|
216
|
-
"model": "gemini-2.5-pro", // Google (keyword match)
|
|
217
|
-
"model": "grok-4", // X.AI (keyword match)
|
|
218
|
-
"model": "mistral-large", // Mistral (keyword match)
|
|
219
|
-
"model": "deepseek-chat", // DeepSeek (keyword match)
|
|
220
|
-
"model": "anthropic/claude-3.5-sonnet", // OpenRouter (slash format, not in Anthropic)
|
|
221
|
-
"model": "qwen/qwen3-coder", // OpenRouter (static model)
|
|
222
|
-
"model": "openrouter/auto" // OpenRouter auto-selection
|
|
223
|
-
}
|
|
224
|
-
|
|
225
|
-
// Consensus tool with multiple providers
|
|
226
|
-
{
|
|
227
|
-
"models": [
|
|
228
|
-
{"model": "o3"},
|
|
229
|
-
{"model": "claude-3-5-sonnet"},
|
|
230
|
-
{"model": "gemini-2.5-pro"}
|
|
231
|
-
]
|
|
232
|
-
}
|
|
233
|
-
```
|
|
234
|
-
|
|
235
|
-
## Troubleshooting
|
|
236
|
-
|
|
237
|
-
### Invalid API Key Errors
|
|
238
|
-
- Ensure your API key matches the expected format for each provider
|
|
239
|
-
- Check that environment variables are properly set
|
|
240
|
-
- Verify API keys are active and have available quota
|
|
241
|
-
|
|
242
|
-
### Model Not Found
|
|
243
|
-
- Use exact model identifiers as listed above
|
|
244
|
-
- Some providers support aliases (e.g., "claude" → "claude-3-5-sonnet")
|
|
245
|
-
- Check provider documentation for model availability in your region
|
|
246
|
-
|
|
247
|
-
### Rate Limits
|
|
248
|
-
- Each provider has different rate limits
|
|
249
|
-
- OpenRouter provides unified rate limiting across providers
|
|
250
|
-
- Consider using multiple providers for better availability
|
|
251
|
-
|
|
252
|
-
### OpenRouter Compliance
|
|
253
|
-
- The `OPENROUTER_REFERER` header is **required**
|
|
254
|
-
- Use your application URL or GitHub repository
|
|
255
|
-
- This helps OpenRouter track usage for compliance
|
|
256
|
-
|
|
257
|
-
### OpenRouter Dynamic Models
|
|
258
|
-
- Enable with `OPENROUTER_DYNAMIC_MODELS=true`
|
|
259
|
-
- First request to a new model may be slower (fetches capabilities)
|
|
260
|
-
- Model capabilities are cached for 24 hours
|
|
261
|
-
- Use any model from [openrouter.ai/models](https://openrouter.ai/models)
|
|
1
|
+
# AI Provider Configuration Guide
|
|
2
|
+
|
|
3
|
+
This guide documents all supported AI providers in the Converse MCP Server and their configuration options.
|
|
4
|
+
|
|
5
|
+
## Supported Providers
|
|
6
|
+
|
|
7
|
+
### OpenAI
|
|
8
|
+
- **API Key Format**: `sk-proj-...` (starts with `sk-`)
|
|
9
|
+
- **Get Key**: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
|
|
10
|
+
- **Environment Variable**: `OPENAI_API_KEY`
|
|
11
|
+
- **Supported Models**:
|
|
12
|
+
- `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-pro` - GPT-5 family with advanced reasoning
|
|
13
|
+
- `o3`, `o3-mini`, `o3-pro` - Advanced reasoning models
|
|
14
|
+
- `o4-mini` - Latest fast reasoning model
|
|
15
|
+
- `gpt-4.1` - Large context (1M tokens)
|
|
16
|
+
- `gpt-4o`, `gpt-4o-mini` - Multimodal models
|
|
17
|
+
|
|
18
|
+
### Google (Gemini)
|
|
19
|
+
- **API Key Format**: `AIzaSy...` (varies)
|
|
20
|
+
- **Get Key**: [makersuite.google.com/app/apikey](https://makersuite.google.com/app/apikey)
|
|
21
|
+
- **Environment Variable**: `GOOGLE_API_KEY`
|
|
22
|
+
- **Supported Models**:
|
|
23
|
+
- `gemini-2.5-pro` - Deep reasoning with thinking mode
|
|
24
|
+
- `gemini-2.5-flash` - Ultra-fast model
|
|
25
|
+
- `gemini-2.0-flash`, `gemini-2.0-flash-lite` - Latest generation
|
|
26
|
+
|
|
27
|
+
### X.AI (Grok)
|
|
28
|
+
- **API Key Format**: `xai-...` (starts with `xai-`)
|
|
29
|
+
- **Get Key**: [console.x.ai](https://console.x.ai/)
|
|
30
|
+
- **Environment Variable**: `XAI_API_KEY`
|
|
31
|
+
- **Supported Models**:
|
|
32
|
+
- `grok-4-0709` - Latest with image support and web search
|
|
33
|
+
- `grok-code-fast-1` - Speedy and economical reasoning model that excels at agentic coding
|
|
34
|
+
|
|
35
|
+
### Anthropic (Claude)
|
|
36
|
+
- **API Key Format**: `sk-ant-...` (starts with `sk-ant-`)
|
|
37
|
+
- **Get Key**: [console.anthropic.com](https://console.anthropic.com/)
|
|
38
|
+
- **Environment Variable**: `ANTHROPIC_API_KEY`
|
|
39
|
+
- **Supported Models**:
|
|
40
|
+
- `claude-opus-4-1-20250805` - Highest intelligence with extended thinking (32K output)
|
|
41
|
+
- `claude-sonnet-4-20250514` - Balanced performance with extended thinking (64K output)
|
|
42
|
+
- `claude-3-7-sonnet-20250219` - Enhanced 3.x generation with thinking (64K output)
|
|
43
|
+
- `claude-3-5-sonnet-20241022` - Fast and intelligent model (8K output)
|
|
44
|
+
- `claude-3-5-haiku-20241022` - Fastest Claude model (8K output)
|
|
45
|
+
- `claude-3-opus-20240229`, `claude-3-sonnet-20240229`, `claude-3-haiku-20240307` - Previous generation
|
|
46
|
+
|
|
47
|
+
### Mistral
|
|
48
|
+
- **API Key Format**: 32+ character string
|
|
49
|
+
- **Get Key**: [console.mistral.ai](https://console.mistral.ai/)
|
|
50
|
+
- **Environment Variable**: `MISTRAL_API_KEY`
|
|
51
|
+
- **Supported Models**:
|
|
52
|
+
- `mistral-large-latest` - Most capable model
|
|
53
|
+
- `mistral-medium-latest` - Balanced performance
|
|
54
|
+
- `mistral-small-latest` - Fast and efficient
|
|
55
|
+
- `open-mistral-7b`, `open-mixtral-8x7b`, `open-mixtral-8x22b` - Open-source models
|
|
56
|
+
|
|
57
|
+
### DeepSeek
|
|
58
|
+
- **API Key Format**: 32+ character string
|
|
59
|
+
- **Get Key**: [platform.deepseek.com](https://platform.deepseek.com/)
|
|
60
|
+
- **Environment Variable**: `DEEPSEEK_API_KEY`
|
|
61
|
+
- **Supported Models**:
|
|
62
|
+
- `deepseek-chat` - Advanced conversational model
|
|
63
|
+
- `deepseek-coder` - Specialized for code generation
|
|
64
|
+
|
|
65
|
+
### OpenRouter
|
|
66
|
+
- **API Key Format**: `sk-or-...` (starts with `sk-or-`)
|
|
67
|
+
- **Get Key**: [openrouter.ai/keys](https://openrouter.ai/keys)
|
|
68
|
+
- **Environment Variables**:
|
|
69
|
+
- `OPENROUTER_API_KEY` - Your API key
|
|
70
|
+
- `OPENROUTER_REFERER` - Required referer URL (e.g., your GitHub repo)
|
|
71
|
+
- `OPENROUTER_TITLE` - Optional title for request tracking
|
|
72
|
+
- `OPENROUTER_DYNAMIC_MODELS` - Enable dynamic model discovery (default: false, required for `provider/model` format)
|
|
73
|
+
- **Static Models**: Pre-configured models available without dynamic discovery
|
|
74
|
+
- `qwen/qwen3-235b-a22b-thinking-2507` - Qwen3 235B with thinking capabilities
|
|
75
|
+
- `qwen/qwen3-coder` - Qwen3 specialized for coding
|
|
76
|
+
- `moonshotai/kimi-k2` - Kimi K2 with 200K context window
|
|
77
|
+
- `openrouter/auto` - Auto-selects best model using NotDiamond routing
|
|
78
|
+
- **Dynamic Models**: Requires `OPENROUTER_DYNAMIC_MODELS=true` to use any model in `provider/model` format
|
|
79
|
+
- `anthropic/claude-3.5-sonnet`
|
|
80
|
+
- `openai/gpt-4-turbo`
|
|
81
|
+
- `google/gemini-pro`
|
|
82
|
+
- `mistralai/mistral-large`
|
|
83
|
+
- `meta-llama/llama-3.1-405b-instruct`
|
|
84
|
+
- And many more - see [openrouter.ai/models](https://openrouter.ai/models)
|
|
85
|
+
|
|
86
|
+
### Codex
|
|
87
|
+
- **API Key Format**: Optional (uses ChatGPT login by default)
|
|
88
|
+
- **Authentication**: ChatGPT login (system-wide) OR `CODEX_API_KEY`
|
|
89
|
+
- **Environment Variables**:
|
|
90
|
+
- `CODEX_API_KEY` - Optional API key for headless deployments
|
|
91
|
+
- `CODEX_SANDBOX_MODE` - Filesystem access control (default: read-only)
|
|
92
|
+
- `CODEX_SKIP_GIT_CHECK` - Skip Git repository validation (default: true)
|
|
93
|
+
- `CODEX_APPROVAL_POLICY` - Command approval behavior (default: never)
|
|
94
|
+
- `CODEX_DEFAULT_MODEL` - Default model (default: gpt-5-codex)
|
|
95
|
+
- **Supported Models**:
|
|
96
|
+
- `codex` - OpenAI Codex agentic coding assistant
|
|
97
|
+
- Thread-based sessions with persistent context
|
|
98
|
+
- Direct filesystem access from working directory
|
|
99
|
+
- Typical response time: 6-20 seconds (longer for complex tasks)
|
|
100
|
+
|
|
101
|
+
**Key Features:**
|
|
102
|
+
- **Thread-Based Sessions**: Maintains full conversation history across requests
|
|
103
|
+
- **Local File Access**: Reads files directly from working directory
|
|
104
|
+
- **Sandbox Modes**: Configurable filesystem access (read-only, workspace-write, danger-full-access)
|
|
105
|
+
- **Approval Policies**: Control command execution behavior
|
|
106
|
+
- **Performance**: Slower than API-based providers (6-20 seconds typical, minutes for complex tasks)
|
|
107
|
+
|
|
108
|
+
**Best Practices:**
|
|
109
|
+
- Use `async: true` for Codex requests (long response times)
|
|
110
|
+
- Set `CODEX_SANDBOX_MODE=read-only` for safe exploration
|
|
111
|
+
- Use `CODEX_APPROVAL_POLICY=never` for headless server deployments
|
|
112
|
+
- Always use `continuation_id` for thread continuation
|
|
113
|
+
|
|
114
|
+
## Configuration Examples
|
|
115
|
+
|
|
116
|
+
### Basic Configuration (.env file)
|
|
117
|
+
```bash
|
|
118
|
+
# Choose one or more providers
|
|
119
|
+
OPENAI_API_KEY=sk-proj-your_key_here
|
|
120
|
+
ANTHROPIC_API_KEY=sk-ant-your_key_here
|
|
121
|
+
MISTRAL_API_KEY=your_mistral_key_here
|
|
122
|
+
DEEPSEEK_API_KEY=your_deepseek_key_here
|
|
123
|
+
|
|
124
|
+
# OpenRouter requires both API key and referer
|
|
125
|
+
OPENROUTER_API_KEY=sk-or-your_key_here
|
|
126
|
+
OPENROUTER_REFERER=https://github.com/YourUsername/YourApp
|
|
127
|
+
# Optional: Enable dynamic model discovery to use any OpenRouter model
|
|
128
|
+
OPENROUTER_DYNAMIC_MODELS=true
|
|
129
|
+
# Optional: Add title for request tracking
|
|
130
|
+
OPENROUTER_TITLE=Converse
|
|
131
|
+
|
|
132
|
+
# Codex - Optional API key (uses ChatGPT login by default)
|
|
133
|
+
CODEX_API_KEY=your_codex_api_key_here # Optional if ChatGPT login available
|
|
134
|
+
CODEX_SANDBOX_MODE=read-only # read-only (default), workspace-write, danger-full-access
|
|
135
|
+
CODEX_SKIP_GIT_CHECK=true # true (default), false
|
|
136
|
+
CODEX_APPROVAL_POLICY=never # never (default), untrusted, on-failure, on-request
|
|
137
|
+
CODEX_DEFAULT_MODEL=gpt-5-codex # Default: gpt-5-codex
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Claude Configuration (claude_desktop_config.json)
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"converse": {
|
|
145
|
+
"command": "npx",
|
|
146
|
+
"args": ["FallDownTheSystem/converse"],
|
|
147
|
+
"env": {
|
|
148
|
+
"OPENAI_API_KEY": "your_key_here",
|
|
149
|
+
"ANTHROPIC_API_KEY": "your_key_here",
|
|
150
|
+
"MISTRAL_API_KEY": "your_key_here",
|
|
151
|
+
"DEEPSEEK_API_KEY": "your_key_here",
|
|
152
|
+
"OPENROUTER_API_KEY": "your_key_here",
|
|
153
|
+
"OPENROUTER_REFERER": "https://github.com/YourUsername/YourApp",
|
|
154
|
+
"OPENROUTER_DYNAMIC_MODELS": "true",
|
|
155
|
+
"OPENROUTER_TITLE": "Converse"
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Provider-Specific Features
|
|
163
|
+
|
|
164
|
+
### Streaming Support
|
|
165
|
+
All providers support streaming responses for real-time output.
|
|
166
|
+
|
|
167
|
+
### Image Support
|
|
168
|
+
- **Full Support**: OpenAI, Google, X.AI (Grok-4), Anthropic (Claude-3.5-Sonnet, Claude-3-Opus)
|
|
169
|
+
- **Via OpenRouter**: Depends on the underlying model
|
|
170
|
+
- **No Support**: DeepSeek, Mistral (except Large), Claude-3.5-Haiku, Codex
|
|
171
|
+
|
|
172
|
+
### Web Search
|
|
173
|
+
- **Native Support**: OpenAI, Google, X.AI (Grok-4)
|
|
174
|
+
- **No Support**: Anthropic, Mistral, DeepSeek, OpenRouter, Codex
|
|
175
|
+
|
|
176
|
+
### Thinking/Reasoning Modes
|
|
177
|
+
- **OpenAI**: O3 series models support `reasoning_effort` parameter
|
|
178
|
+
- **Google**: Gemini Pro/Flash support thinking mode with configurable budget
|
|
179
|
+
- **Anthropic**: Claude 4 and 3.7 models support extended thinking with `reasoning_effort`
|
|
180
|
+
- **Codex**: Thread-based agentic reasoning with persistent context
|
|
181
|
+
- **Others**: Standard inference only
|
|
182
|
+
|
|
183
|
+
### Local Execution
|
|
184
|
+
- **Codex**: Runs locally with direct filesystem access and thread-based sessions
|
|
185
|
+
- **All Others**: API-based remote execution
|
|
186
|
+
|
|
187
|
+
## Model Selection in Tools
|
|
188
|
+
|
|
189
|
+
When using the chat or consensus tools, specify models using their identifiers:
|
|
190
|
+
|
|
191
|
+
### Model Routing Logic
|
|
192
|
+
|
|
193
|
+
1. **Simple Names**: Models without "/" are routed by keyword matching:
|
|
194
|
+
- Contains "gpt", "o1", "o3", "o4" → OpenAI
|
|
195
|
+
- Contains "claude", "opus", "sonnet", "haiku" → Anthropic
|
|
196
|
+
- Contains "gemini", "flash", "pro" → Google
|
|
197
|
+
- Contains "grok" → X.AI
|
|
198
|
+
- Contains "mistral", "magistral" → Mistral
|
|
199
|
+
- Contains "deepseek", "reasoner", "r1" → DeepSeek
|
|
200
|
+
- Contains "qwen", "kimi", "k2" → OpenRouter
|
|
201
|
+
|
|
202
|
+
2. **Slash Format**: Models with "/" check native providers first:
|
|
203
|
+
- If exact model exists in a native provider → Routes to that provider
|
|
204
|
+
- If not found in any native provider → Routes to OpenRouter
|
|
205
|
+
- This allows using models like "anthropic/claude-3.5-sonnet" via OpenRouter
|
|
206
|
+
|
|
207
|
+
3. **OpenRouter Auto**: Special aliases route to OpenRouter's auto-selection:
|
|
208
|
+
- "openrouter/auto", "openrouter auto", "auto router", "auto-router"
|
|
209
|
+
|
|
210
|
+
```javascript
|
|
211
|
+
// Chat tool examples
|
|
212
|
+
{
|
|
213
|
+
"model": "gpt-4o", // OpenAI (keyword match)
|
|
214
|
+
"model": "claude-opus-4", // Anthropic (keyword match, auto-resolves)
|
|
215
|
+
"model": "sonnet", // Anthropic (keyword match)
|
|
216
|
+
"model": "gemini-2.5-pro", // Google (keyword match)
|
|
217
|
+
"model": "grok-4", // X.AI (keyword match)
|
|
218
|
+
"model": "mistral-large", // Mistral (keyword match)
|
|
219
|
+
"model": "deepseek-chat", // DeepSeek (keyword match)
|
|
220
|
+
"model": "anthropic/claude-3.5-sonnet", // OpenRouter (slash format, not in Anthropic)
|
|
221
|
+
"model": "qwen/qwen3-coder", // OpenRouter (static model)
|
|
222
|
+
"model": "openrouter/auto" // OpenRouter auto-selection
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
// Consensus tool with multiple providers
|
|
226
|
+
{
|
|
227
|
+
"models": [
|
|
228
|
+
{"model": "o3"},
|
|
229
|
+
{"model": "claude-3-5-sonnet"},
|
|
230
|
+
{"model": "gemini-2.5-pro"}
|
|
231
|
+
]
|
|
232
|
+
}
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Troubleshooting
|
|
236
|
+
|
|
237
|
+
### Invalid API Key Errors
|
|
238
|
+
- Ensure your API key matches the expected format for each provider
|
|
239
|
+
- Check that environment variables are properly set
|
|
240
|
+
- Verify API keys are active and have available quota
|
|
241
|
+
|
|
242
|
+
### Model Not Found
|
|
243
|
+
- Use exact model identifiers as listed above
|
|
244
|
+
- Some providers support aliases (e.g., "claude" → "claude-3-5-sonnet")
|
|
245
|
+
- Check provider documentation for model availability in your region
|
|
246
|
+
|
|
247
|
+
### Rate Limits
|
|
248
|
+
- Each provider has different rate limits
|
|
249
|
+
- OpenRouter provides unified rate limiting across providers
|
|
250
|
+
- Consider using multiple providers for better availability
|
|
251
|
+
|
|
252
|
+
### OpenRouter Compliance
|
|
253
|
+
- The `OPENROUTER_REFERER` header is **required**
|
|
254
|
+
- Use your application URL or GitHub repository
|
|
255
|
+
- This helps OpenRouter track usage for compliance
|
|
256
|
+
|
|
257
|
+
### OpenRouter Dynamic Models
|
|
258
|
+
- Enable with `OPENROUTER_DYNAMIC_MODELS=true`
|
|
259
|
+
- First request to a new model may be slower (fetches capabilities)
|
|
260
|
+
- Model capabilities are cached for 24 hours
|
|
261
|
+
- Use any model from [openrouter.ai/models](https://openrouter.ai/models)
|
|
262
262
|
- Models must use `provider/model` format (e.g., `meta-llama/llama-3.2-90b`)
|
package/package.json
CHANGED
package/src/providers/codex.js
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
|
|
16
16
|
import { debugLog, debugError } from '../utils/console.js';
|
|
17
17
|
import { ProviderError, ErrorCodes, StopReasons } from './interface.js';
|
|
18
|
+
import { normalizeExtendedPath } from '../utils/pathUtils.js';
|
|
18
19
|
|
|
19
20
|
// Supported Codex models with their configurations
|
|
20
21
|
const SUPPORTED_MODELS = {
|
|
@@ -244,7 +245,9 @@ export const codexProvider = {
|
|
|
244
245
|
|
|
245
246
|
// Read configuration values (with secure defaults)
|
|
246
247
|
// Note: Using CLIENT_CWD directly, no separate CODEX_WORKING_DIRECTORY
|
|
247
|
-
const
|
|
248
|
+
const rawWorkingDirectory = config.server?.client_cwd || process.cwd();
|
|
249
|
+
// Normalize Windows extended-length paths (\\?\C:\...) to regular paths
|
|
250
|
+
const workingDirectory = normalizeExtendedPath(rawWorkingDirectory);
|
|
248
251
|
const sandbox = config.providers?.codexsandboxmode || 'read-only';
|
|
249
252
|
const skipGitRepoCheck = config.providers?.codexskipgitcheck !== undefined ? config.providers.codexskipgitcheck : true;
|
|
250
253
|
const approvalPolicy = config.providers?.codexapprovalpolicy || 'never';
|
|
@@ -252,7 +255,6 @@ export const codexProvider = {
|
|
|
252
255
|
debugLog(`[Codex] Starting ${threadId ? 'resumed' : 'new'} thread`, {
|
|
253
256
|
model,
|
|
254
257
|
workingDirectory,
|
|
255
|
-
workingDirectoryType: workingDirectory.startsWith('\\\\?\\') ? 'extended-length' : 'normal',
|
|
256
258
|
sandbox,
|
|
257
259
|
skipGitRepoCheck,
|
|
258
260
|
approvalPolicy,
|
|
@@ -278,12 +280,14 @@ export const codexProvider = {
|
|
|
278
280
|
debugLog('[Codex] Using reasoning_effort:', reasoning_effort);
|
|
279
281
|
}
|
|
280
282
|
|
|
281
|
-
//
|
|
282
|
-
|
|
283
|
+
// WORKAROUND: Always use streaming to avoid SDK bug where thread.run() hangs
|
|
284
|
+
// The SDK's thread.run() waits indefinitely when CLI exits without emitting turn.completed
|
|
285
|
+
// Force streaming until OpenAI fixes the SDK - stream closes naturally when process exits
|
|
286
|
+
if (stream || true) {
|
|
283
287
|
return createStreamingGenerator(thread, prompt, signal, runOptions);
|
|
284
288
|
}
|
|
285
289
|
|
|
286
|
-
// Non-streaming execution
|
|
290
|
+
// Non-streaming execution (disabled due to SDK bug - see above)
|
|
287
291
|
const startTime = Date.now();
|
|
288
292
|
debugLog('[Codex] Starting thread.run()...', {
|
|
289
293
|
threadId: thread.id,
|