Configuration
All plugin options, engine settings, and environment variables for @robojs/ai.
The AI plugin is configured through a file at config/plugins/robojs/ai.mjs (or .ts). You only need to specify the options you want to change.
export default {
instructions: 'You are Sage, a helpful community assistant.'
}export default {
instructions: 'You are Sage, a helpful community assistant.'
}Plugin options
Prop
Type
Channel behavior
restrict and whitelist control where the bot listens:
- restrict limits the bot to specific channels. Messages in all other channels are ignored, even if the bot is mentioned.
- whitelist enables ambient chat (no mention needed) in the listed channels.
- If both are set,
restrictwins. The bot only responds in restricted channels, and whitelisted channels outside the restrict list are ignored.
export default {
restrict: { channelIds: ['345678901234567890'] },
whitelist: { channelIds: ['456789012345678901', '567890123456789012'] }
}export default {
restrict: { channelIds: ['345678901234567890'] },
whitelist: { channelIds: ['456789012345678901', '567890123456789012'] }
}Command tools
The commands option controls which of your registered slash commands the AI can invoke via natural language.
export default {
// Only allow these commands to be called by the AI
commands: ['ban', 'kick', 'ai log']
}export default {
// Only allow these commands to be called by the AI
commands: ['ban', 'kick', 'ai log']
}Set to false to disable command execution entirely. Omit or set to true to expose all commands.
Context depth
When someone mentions the bot in a busy channel, the plugin fetches surrounding messages to give the AI conversational context. Control this with the context option.
export default {
context: {
enabled: true,
depth: 12
}
}export default {
context: {
enabled: true,
depth: 12
}
}Set enabled: false to disable context fetching. The depth value controls how many surrounding messages are included.
Engine configuration
The default OpenAiEngine accepts these constructor options.
clientOptions
Pass-through to the OpenAI SDK. Use this for API key overrides, custom base URLs, or fetch configuration.
new OpenAiEngine({
clientOptions: {
apiKey: process.env.OPENAI_API_KEY,
baseURL: 'https://custom-proxy.example.com/v1',
organization: process.env.OPENAI_ORG_ID
}
})new OpenAiEngine({
clientOptions: {
apiKey: process.env.OPENAI_API_KEY,
baseURL: 'https://custom-proxy.example.com/v1',
organization: process.env.OPENAI_ORG_ID
}
})chat
Model configuration for text conversations.
Prop
Type
voice
Model configuration for realtime voice sessions.
Prop
Type
webSearch
Enable live web search with automatic citation formatting.
Prop
Type
mcp
Engine-level MCP error handling. Same structure as the plugin-level mcp option.
Complete config example
import { OpenAiEngine } from '@robojs/ai/engines/openai'
export default {
instructions: 'You are Sage, a concise community mentor. Answer questions directly.',
commands: ['ban', 'kick', 'warn'],
insight: true,
restrict: { channelIds: ['345678901234567890'] },
whitelist: { channelIds: ['456789012345678901'] },
context: {
enabled: true,
depth: 10
},
engine: new OpenAiEngine({
clientOptions: {
apiKey: process.env.OPENAI_API_KEY,
organization: process.env.OPENAI_ORG_ID
},
chat: {
model: 'gpt-4.1',
temperature: 0.5,
maxOutputTokens: 1000
},
voice: {
model: 'gpt-realtime',
transcription: {
model: 'gpt-4o-transcribe-latest',
language: 'en'
}
},
webSearch: true
}),
voice: {
endpointing: 'server-vad',
maxConcurrentChannels: 3,
playbackVoice: 'alloy',
instructions: 'Keep spoken replies under 10 seconds.',
capture: {
sampleRate: 24000,
silenceDurationMs: 300,
vadThreshold: 0.01
},
transcript: {
enabled: true,
targetChannelId: '987654321098765432'
}
},
usage: {
limits: {
perModel: {
'gpt-4o': { window: 'month', maxTokens: 500_000, mode: 'block' },
'gpt-4.1-mini': { window: 'month', maxTokens: 800_000, mode: 'block' }
}
}
}
}import { OpenAiEngine } from '@robojs/ai/engines/openai'
export default {
instructions: 'You are Sage, a concise community mentor. Answer questions directly.',
commands: ['ban', 'kick', 'warn'],
insight: true,
restrict: { channelIds: ['345678901234567890'] },
whitelist: { channelIds: ['456789012345678901'] },
context: {
enabled: true,
depth: 10
},
engine: new OpenAiEngine({
clientOptions: {
apiKey: process.env.OPENAI_API_KEY,
organization: process.env.OPENAI_ORG_ID
},
chat: {
model: 'gpt-4.1',
temperature: 0.5,
maxOutputTokens: 1000
},
voice: {
model: 'gpt-realtime',
transcription: {
model: 'gpt-4o-transcribe-latest',
language: 'en'
}
},
webSearch: true
}),
voice: {
endpointing: 'server-vad',
maxConcurrentChannels: 3,
playbackVoice: 'alloy',
instructions: 'Keep spoken replies under 10 seconds.',
capture: {
sampleRate: 24000,
silenceDurationMs: 300,
vadThreshold: 0.01
},
transcript: {
enabled: true,
targetChannelId: '987654321098765432'
}
},
usage: {
limits: {
perModel: {
'gpt-4o': { window: 'month', maxTokens: 500_000, mode: 'block' },
'gpt-4.1-mini': { window: 'month', maxTokens: 800_000, mode: 'block' }
}
}
}
}Environment variables
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY | Yes (unless custom engine) | OpenAI API key used by the default OpenAiEngine. |
OPENAI_REALTIME_API_KEY | No | Separate key for voice sessions. Falls back to OPENAI_API_KEY if not set. |
DEBUG | No | Set to ai:voice for verbose voice debug logs. |
OPENAI_API_KEY="sk-..."If you're using a custom engine that doesn't rely on OpenAI, you can skip OPENAI_API_KEY entirely. The engine handles its own authentication.