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.

This guide walks you through cloning, building, configuring, and running FrostAgent so that you end up with a live OneBot v11 WebSocket endpoint backed by an LLM of your choice. By the end you will have a management panel running on port 8080 and a bot ready to accept connections on port 1234.

​
Prerequisites

Before you begin, make sure you have the following:
  • Go 1.25.3+ installed and available on your PATH (go version to verify)
  • A running OpenAI-compatible API endpoint — for example, Alibaba Cloud DashScope, the OpenAI API, or any self-hosted compatible service
  • An API key for that endpoint

​
Steps

1

Clone and build

Clone the repository and compile a self-contained binary:
git clone https://github.com/GuaiZai233/FrostAgent.git
cd FrostAgent
go build -o frostagent ./cmd/app
The go build step downloads all dependencies listed in go.mod and produces a single frostagent executable in the current directory.
2

Configure environment variables

Copy the provided example file and open it in your editor:
cp .env.example .env
Edit .env and fill in at least UPSTREAM_ENDPOINT, UPSTREAM_API_KEY, and MODEL_NAME:
# OpenAI-compatible upstream API base URL
UPSTREAM_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1

# Primary LLM API key
UPSTREAM_API_KEY=sk-your-api-key-here

# API key used by the sub-agent / coder tool
CODER_API_KEY=sk-your-api-key-here

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

# OneBot WebSocket listen address
WS_LISTEN_ADDR=:1234

# System prompt sent to the LLM at the start of every session
SYSTEM_PROMPT=You are a helpful assistant.

# Model identifier recognised by your upstream provider
MODEL_NAME=qwen-turbo
All other variables have sensible defaults and can be left blank for now. See the full configuration reference for details.
3

Start the service

Run the binary you just built:
./frostagent
FrostAgent starts two servers:
ServerDefault addressPurpose
HTTP (ConnectRPC + SPA)http://localhost:8080Management panel, RPC API, log streaming
OneBot WebSocketws://0.0.0.0:1234Receives and replies to OneBot v11 events
You should see startup log lines confirming both servers are listening. If either port is already in use, adjust LISTEN_ADDR or WS_LISTEN_ADDR in your .env file and restart.
4

Connect your OneBot v11 client

Point your OneBot v11 compatible client (such as Lagrange, go-cqhttp, or NapCatQQ) at the following WebSocket URL:
ws://<host>:1234/ws/frostagent
Replace <host> with the IP address or hostname of the machine running FrostAgent (localhost if running locally).Message routing behaviour:
  • Private messages — FrostAgent responds directly to every private message it receives.
  • Group messages — By default, FrostAgent replies to all group messages. When ENABLE_AT_IN_GROUP_MSG=true, replies are prefixed with @<sender> so the response is clearly directed at the right user in a busy group chat.
5

Verify in the management panel

Open your browser and navigate to:
http://localhost:8080
The embedded single-page application shows you live bot status (uptime, version, engine state), a real-time log stream, and a settings editor. If you see the FrostAgent dashboard, everything is working correctly.You can also hit the health-adjacent ConnectRPC endpoint directly:
curl http://localhost:8080/frostagent.v1.BotStatusService/GetOverview \
  -H "Content-Type: application/json" \
  -d '{}'
The .env variables shown above cover the most common setup. For the complete list of options — including context window limits, vision model configuration, and allowed WebSocket origins — see the Configuration reference.

​
Next steps

Configuration reference

Explore every environment variable, their defaults, and which ones take effect without a restart.

Tool system

Learn how the built-in tool registry works and how the engine decides which tool to call.

OneBot adapter

Understand group vs. private message handling, event filtering, and the WebSocket lifecycle.

Custom tools

Extend FrostAgent with your own tools by implementing the Tool interface in Go.

Build docs developers (and LLMs) love

Get started for freeTalk to us