💿 Install

Install with nb-cli

Open shell under the root directory of nonebot2, input the command below.

nb plugin install nonebot-plugin-marshoai

Install with pack manager

Open shell under the plugin directory of nonebot2, input corresponding command according to your pack manager.

pip

pip install nonebot-plugin-marshoai

pdm

pdm add nonebot-plugin-marshoai

poetry

poetry add nonebot-plugin-marshoai

conda

conda install nonebot-plugin-marshoai

Open the pyproject.toml file under nonebot2's root directory, Add to[tool.nonebot].

plugins = ["nonebot_plugin_marshoai"]

🤖 Get token(GitHub Models)

• Create new personal access token, and add the models permission.
• Copy the new token, add to the .env file's marshoai_token option.

WARNING

GitHub Models API comes with significant limitations and is therefore not recommended for use. For better alternatives, it's suggested to adjust the configuration MARSHOAI_ENDPOINT to use other service providers' models instead.

🎉 Usage

End marsho in order to get direction for use(If you configured the custom command, please use the configured one).

👉 Double click avatar

When nonebot linked to OneBot v11 adapter, can recieve double click and response to it. More detail in the MARSHOAI_POKE_SUFFIX option.

🛠️ MarshoTools (Deprecated)

MarshoTools is a feature added in v0.5.0, support loading external function library to provide Function Call for Marsho.

🧩 Marsho Plugin

Marsho Plugin is a feature added in v1.0.0, replacing the old MarshoTools feature. Documentation

👍 Praise list

Praise list stored in the praises.json in plugin directory（This directory will putput to log when Bot start), it'll automatically generate when option is true, include character name and advantage two basic data.

The character stored in it would be “know” and “like” by Marsho.

It's structure is similar to:

{
  "like": [
    {
      "name": "Asankilp",
      "advantages": "赋予了Marsho猫娘人格，使用vim与vscode为Marsho写了许多代码，使Marsho更加可爱"
    },
    {
      "name": "神羽(snowykami)",
      "advantages": "人脉很广，经常找小伙伴们开银趴，很会写后端代码"
    },
    ...
  ]
}

⚙️ Configurable options

Add options in the .env file from the diagram below in nonebot2 project.

plugin behaviour

Option	Type	Default	Description
MARSHOAI_USE_YAML_CONFIG	bool	false	Use YAML config format
MARSHOAI_DEVMODE	bool	true	Turn on Development Mode or not

Marsho usage

Option	Type	Default	Description
MARSHOAI_DEFAULT_NAME	str	marsho	Command to call Marsho
MARSHOAI_ALIASES	set[str]	list["小棉"]	Other name(Alias) to call Marsho
MARSHOAI_AT	bool	false	Call by @ or not
MARSHOAI_MAIN_COLOUR	str	FEABA9	Theme color, used by some tools and features

AI call

Option	Type	Default	Description
MARSHOAI_TOKEN	str		The token needed to call AI API
MARSHOAI_DEFAULT_MODEL	str	openai/gpt-4.1	The default model of Marsho
MARSHOAI_PROMPT	str	Catgirl Marsho's character prompt	Marsho's basic system prompt
MARSHOAI_SYSASUSER_PROMPT	str	好的喵~	Marsho 的 System-As-User 启用时，使用的 Assistant 消息
MARSHOAI_ADDITIONAL_PROMPT	str		Marsho's external system prompt
MARSHOAI_ENFORCE_NICKNAME	bool	true	Enforce user to set nickname or not
MARSHOAI_POKE_SUFFIX	str	揉了揉你的猫耳	When double click Marsho who connected to OneBot adapter, the chat content. When it's empty string, double click function is off. Such as, the default content is *[昵称]揉了揉你的猫耳。
MARSHOAI_ENDPOINT	str	https://models.github.ai/inference	OpenAI standard API
MARSHOAI_MODEL_ARGS	dict	{}	model arguments(such as temperature, top_p, max_tokens etc.)

| MARSHOAI_ADDITIONAL_IMAGE_MODELS | list | [] | External image-support model list, such as hunyuan-vision | | MARSHOAI_NICKNAME_LIMIT | int | 16 | Limit for nickname length | | MARSHOAI_TIMEOUT | float | 50 | AI request timeout (seconds) |

Feature Switches

Option	Type	Default	Description
MARSHOAI_ENABLE_SUPPORT_IMAGE_TIP	bool	true	When on, if user send request with photo and model don't support that, remind the user
MARSHOAI_ENABLE_NICKNAME_TIP	bool	true	When on, if user haven't set username, remind user to set
MARSHOAI_ENABLE_PRAISES	bool	true	Turn on Praise list or not
MARSHOAI_ENABLE_SYSASUSER_PROMPT	bool	false	是否启用 System-As-User 提示词
MARSHOAI_ENABLE_TIME_PROMPT	bool	true	Turn on real-time date and time (accurate to seconds) and lunar date system prompt
MARSHOAI_ENABLE_TOOLS	bool	false	Turn on Marsho Tools or not
MARSHOAI_ENABLE_PLUGINS	bool	true	Turn on Marsho Plugins or not
MARSHOAI_PLUGIN_DIRS	list[str]	[]	List of plugins directory
MARSHOAI_LOAD_BUILTIN_TOOLS	bool	true	Loading the built-in toolkit or not
MARSHOAI_TOOLSET_DIR	list	[]	List of external toolset directory
MARSHOAI_DISABLED_TOOLKITS	list	[]	List of disabled toolkits' name
MARSHOAI_ENABLE_RICHTEXT_PARSE	bool	true	Turn on auto parse rich text feature(including image, LaTeX equation)
MARSHOAI_SINGLE_LATEX_PARSE	bool	false	Render single-line equation or not
MARSHOAI_FIX_TOOLCALLS	bool	true	Fix tool calls or not
MARSHOAI_SEND_THINKING	bool	true	Send thinking chain or not
MARSHOAI_STREAM	bool	false	是否通过流式方式请求 API 开启此项后暂无法使用函数调用，无法在 Bot 用户侧聊天界面呈现出流式效果
MARSHOAI_ENABLE_MCP	bool	false	Enable MCP feature or not
MARSHOAI_ENABLE_MCP_RESULT_LOGGING	bool	false	Whether to output MCP return results in the log