Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuaiZai233/FrostAgent/llms.txt

Use this file to discover all available pages before exploring further.

FrostAgent reads its entire configuration from environment variables at startup. The recommended approach is to maintain a .env file in the project root; the godotenv library loads this file automatically before the engine initialises. Variables already present in the system environment take precedence over those defined in .env, so you can override individual settings in containerised or CI deployments without modifying the file. Create your local configuration file from the provided template: 
cp .env.example .env
Then open .env in your editor and fill in the values for your environment. The sections below document every supported variable.

​
Complete .env reference

The following is the canonical annotated .env.example from the repository, showing all variables and their defaults: 
# Upstream API base URL — supports any OpenAI-compatible service
UPSTREAM_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1

# Primary upstream API authentication key
UPSTREAM_API_KEY=sk-your-api-key-here

# API key used by the sub-agent / coder tool (may be the same as above)
CODER_API_KEY=sk-your-api-key-here

# HTTP management panel + ConnectRPC listen address
LISTEN_ADDR=:8080

# OneBot WebSocket server listen address
WS_LISTEN_ADDR=:1234

# System prompt injected at the start of every session
SYSTEM_PROMPT=你是一个乐于助人的助手。

# Primary chat model identifier (leave blank to use the provider default)
MODEL_NAME=

# Vision/multimodal model identifier (leave blank to fall back to MODEL_NAME)
VISUAL_MODEL_NAME=

# Context trimming: maximum number of messages to keep (including system prompt)
MAX_CONTEXT_MESSAGES=20

# Context trimming: approximate character limit before older messages are dropped
MAX_CONTEXT_CHARS=24000

# Comma-separated list of allowed WebSocket Origin headers (empty = allow all)
WS_ALLOWED_ORIGINS=

# Whether to prefix group-chat replies with @<sender>
ENABLE_AT_IN_GROUP_MSG=true

​
LLM provider

​
UPSTREAM_ENDPOINT
string
required
The base URL of your OpenAI-compatible chat completions API. FrostAgent appends the appropriate path (/chat/completions) automatically.Example: https://dashscope.aliyuncs.com/compatible-mode/v1Default: https://dashscope.aliyuncs.com/compatible-mode/v1Requires restart to take effect.
​
UPSTREAM_API_KEY
string
required
Bearer token used to authenticate against UPSTREAM_ENDPOINT. Passed as Authorization: Bearer <key> on every LLM request.Default: sk-your-api-key-here (must be replaced)Requires restart to take effect.
​
CODER_API_KEY
string
A separate API key used by the built-in sub-agent / coder tool. This allows you to route sub-agent calls to a different account or a more powerful model tier without affecting the primary engine key.Default: same placeholder as UPSTREAM_API_KEYRequires restart to take effect.
​
MODEL_NAME
string
The model identifier string sent in every chat completion request. The exact value depends on your provider (e.g. qwen-turbo, gpt-4o, deepseek-chat). Leave blank to use your provider’s default model.Default: (empty — provider default)Requires restart to take effect.
​
VISUAL_MODEL_NAME
string
Model identifier for multimodal / vision requests. When set, image-containing messages are routed to this model instead of MODEL_NAME. Leave blank to send all requests through MODEL_NAME.Default: (empty — falls back to MODEL_NAME)Requires restart to take effect.

​
Network

​
LISTEN_ADDR
string
The host:port on which the HTTP server listens. This server hosts both the ConnectRPC management API and the embedded frontend SPA.Default: :8080Requires restart to take effect.
​
WS_LISTEN_ADDR
string
The host:port on which the OneBot v11 WebSocket server listens. Your OneBot client should connect to ws://<host>:<port>/ws/frostagent.Default: 0.0.0.0:1234 (the .env.example template uses :1234, which binds all interfaces on most systems; the code-level fallback when the variable is absent is explicitly 0.0.0.0:1234)Requires restart to take effect.
​
WS_ALLOWED_ORIGINS
string
Comma-separated list of Origin header values that are permitted to open a WebSocket connection. An empty value disables origin checking and allows connections from any origin — suitable for local development but not recommended for production.Example: https://mybot.example.com,https://staging.example.comDefault: (empty — all origins allowed)Requires restart to take effect.

​
Context window

​
MAX_CONTEXT_MESSAGES
integer
The maximum number of messages retained in a session’s context window, including the system prompt. When the session exceeds this limit, the oldest non-system messages are dropped to stay within bounds.Default: 20Takes effect immediately — no restart required.
​
MAX_CONTEXT_CHARS
integer
An approximate upper bound on the total character count of all messages in a session context. If the accumulated text exceeds this threshold, older messages are trimmed before the next LLM call. This acts as a secondary guard in addition to MAX_CONTEXT_MESSAGES.Default: 24000Takes effect immediately — no restart required.

​
Agent behaviour

​
SYSTEM_PROMPT
string
The system-role message injected at position zero of every session context. This is your primary mechanism for giving the agent a persona, constraining its behaviour, or providing background knowledge.Default: 你是一个乐于助人的助手。 (“You are a helpful assistant.”)Takes effect immediately — no restart required.
​
ENABLE_AT_IN_GROUP_MSG
boolean
When true, FrostAgent prepends @<sender_user_id> to every reply sent in a group chat, making it clear which user the bot is responding to. Set to false if your group chat client handles threading differently.Default: trueTakes effect immediately — no restart required.

​
Hot-reload vs. restart

Some configuration changes are picked up without restarting FrostAgent; others require a full process restart because the value is read only once at initialisation.
VariableHot-reload?
SYSTEM_PROMPT✅ Immediate
MAX_CONTEXT_MESSAGES✅ Immediate
MAX_CONTEXT_CHARS✅ Immediate
ENABLE_AT_IN_GROUP_MSG✅ Immediate
UPSTREAM_ENDPOINT🔄 Restart required
UPSTREAM_API_KEY🔄 Restart required
CODER_API_KEY🔄 Restart required
MODEL_NAME🔄 Restart required
VISUAL_MODEL_NAME🔄 Restart required
LISTEN_ADDR🔄 Restart required
WS_LISTEN_ADDR🔄 Restart required
WS_ALLOWED_ORIGINS🔄 Restart required
UPSTREAM_API_KEY and CODER_API_KEY are sensitive credentials. FrostAgent’s management UI masks these values in the settings editor so they are not exposed in plaintext to anyone with browser access to the management panel.

​
Using system environment variables

If you prefer not to use a .env file — for example in a Docker container or a systemd service — you can export variables directly in the environment where FrostAgent runs: 
export UPSTREAM_ENDPOINT=https://api.openai.com/v1
export UPSTREAM_API_KEY=sk-...
export MODEL_NAME=gpt-4o
./frostagent
System environment variables always take precedence over the .env file, so you can use the file for defaults and override specific keys at the process level.

Build docs developers (and LLMs) love

Get started for freeTalk to us