智虾助手 MCP Agent

一、配置文件

MCP Server、系统提示词、终端类型等高级配置均通过 TOML 配置文件管理。

配置文件查找顺序：

1. --config-file 指定的路径
2. 当前目录下的 mcp-agent.toml
3. ~/.mcp-agent/mcp-agent.toml

配置文件包含以下顶层节（section），均为可选：

[agent]        # Agent 身份信息（可选）
[llm]          # 大语言模型配置（可选）
[prompt]       # 系统提示词配置（可选）
[mcp]          # MCP Server 配置（可选）
[[terminals]]  # 终端配置（可多个，数组）

1.1 Agent 身份信息

用于标识当前 Agent，主要影响终端标题显示和子智能体（subagent）的描述。

字段	类型	说明
name	string	Agent 名称，会作为终端标题前缀
description	string	Agent 描述，用于子智能体介绍

[agent]
name        = "my-assistant"
description = "我的私人助手"

1.2 LLM 配置

支持任何兼容 OpenAI 格式的大模型，包括 DeepSeek-V3、Qwen、GPT-4o 等在线服务， 也可通过 Ollama 在本地运行开源模型。

字段	类型	默认值	说明
base_url	string	http://127.0.0.1:11434/v1	API 基础 URL
api_key	string	-	API 密钥；本地模型（如 Ollama）可用 "-"
model	string	qwen3.5	模型名称
vision	bool	false	是否启用视觉（图片）能力
stream	bool	false	是否启用流式响应
temperature	float	0.0	采样温度，省略则使用 API 默认值
auto_compact_threshold	int	102400	对话历史自动压缩阈值（字节），超过则触发压缩
max_iterations	int	10	单轮对话中工具调用的最大迭代次数，超过会暂停并询问用户
retry_count	int	0	LLM 调用失败重试次数：0=不重试，-1=无限重试，>0=重试 N 次（指数退避）

[llm]

# OpenAI
# base_url = "https://api.openai.com/v1"
# api_key  = "sk-xxx"
# model    = "gpt-4o"

# Ollama（本地部署）
base_url = "http://127.0.0.1:11434/v1"  # 默认值，适用于本地 Ollama
api_key  = "-"                           # 本地模型可使用 "-"
model    = "qwen3.5"

# 高级选项
vision                 = false
stream                 = true
temperature            = 0.7
auto_compact_threshold = 102400   # 100KB
max_iterations         = 15
retry_count            = 3

1.3 系统提示词

系统提示词用于设定 Agent 的角色和行为准则。支持三种方式，优先级从高到低：

1. 内联提示词（system 字段）
2. 文件加载（file 字段）
3. 自动回退：配置文件同目录下的 PROMPT.md

[prompt]

# 内联提示词（优先于文件）
system = """
你是用户的私人助手，请按用户指示进行回复，语言尽可能精简。
调用危险工具（如:删除）一定要请示用户，得到肯定后才执行。
当你要完成复杂任务，请先拆解成几个子任务，分而治之。
"""

# 或从文件加载
# file = "PROMPT.md"

二、终端配置

智虾助手 Chat 模式，每个终端拥有独立的会话（共享同一个 MCP 客户端）， 用户提问，Agent 回答。

2.1 console — 命令行终端（默认）

[[terminals]]
type = "console"

2.2 web — Web 浏览器终端

通过 WebSocket 提供浏览器交互界面。

字段	类型	默认值	说明
type	string	-	固定为 web
host	string	127.0.0.1	监听地址
port	int	8088	监听端口
base_url	string	-	对外访问基础 URL

[[terminals]]
type    = "web"
host    = "127.0.0.1"
port    = 8088

2.3 qq — QQ 机器人

字段	类型	说明
app_id	string	QQ 机器人 AppID
app_secret	string	QQ 机器人 AppSecret
user_open_id	string	可选，仅响应此 C2C 用户
group_id	string	可选，仅响应此群
media_proxy_url	string	可选，媒体下载代理，如 socks5://127.0.0.1:1080

[[terminals]]
type            = "qq"
app_id          = "your_app_id"
app_secret      = "your_app_secret"
user_open_id    = "ou_xxx"              # 可选
group_id        = "group_xxx"           # 可选
media_proxy_url = "socks5://127.0.0.1:1080"  # 可选

2.4 feishu — 飞书机器人

需申请 飞书应用，至少需要 im: 开头的所有权限，并配置长连接事件订阅。

字段	类型	说明
app_id	string	飞书应用 App ID
app_secret	string	飞书应用 App Secret
user_open_id	string	可选，限定仅响应特定用户

[[terminals]]
type         = "feishu"
app_id       = "cli_xxxxxxxxxx"
app_secret   = "your_app_secret"
user_open_id = "ou_xxxxxxxxxx"   # 可选

2.5 weixin — 微信机器人

需 node 执行 weixin-clawbot-toml.js，获取配置。

字段	类型	说明
base_url	string	微信 API 网关地址（默认 https://ilinkai.weixin.qq.com）
cdn_base_url	string	CDN 图片下载地址（默认 https://novac2c.cdn.weixin.qq.com/c2c）
bot_token	string	登录后获得的 bot_token
ilink_bot_id	string	ilink_bot_id
ilink_user_id	string	可选，仅响应此用户

[[terminals]]
type          = "weixin"
base_url      = "https://ilinkai.weixin.qq.com"
bot_token     = "your_bot_token"
ilink_bot_id  = "your_bot_id"
ilink_user_id = "your_user_id"   # 可选

2.6 多终端并发

可同时配置多个终端，它们会并发运行，每个终端拥有独立的会话。当 console 终端退出时， 其他终端也会停止。

[[terminals]]
type = "console"

[[terminals]]
type         = "feishu"
app_id       = "cli_xxx"
app_secret   = "xxx"

三、MCP Server 配置

通过 [[mcp.servers]] 数组定义多个 MCP Server。内置 MCP Server 有：filesystem、time、skill、subagent、 command、git、nodejs。 在 Chat 模式下，weixin、feishu、qq 等通讯渠道以 [[terminals]] 终端形式接入（见上文「二、终端配置」），每个渠道拥有独立的会话。

字段	类型	说明
name	string	Server 名称（为空时使用 endpoint）
description	string	人类可读的描述，会注入到系统提示词中供模型参考
endpoint	string	Server 端点：内置名称 / 可执行命令 / HTTP(S) URL / sse <url>
args	[]string	额外参数（与 endpoint 中内嵌的参数合并）
env	map[string]string	子进程环境变量（仅对 stdio 子进程生效）
allowed_tools	[]string	工具白名单：非空时仅暴露这些工具
denied_tools	[]string	工具黑名单：这些工具始终被排除（优先级高于白名单）

3.1 endpoint 类型说明

endpoint 字段支持四种形式，程序自动识别：

endpoint 形式	传输方式	说明
filesystem、time 等内置名	内置实现	见下方「内置 MCP Server」
npx -y @playwright/mcp@latest	stdio 子进程	以命令行方式启动外部 MCP Server
https://example.com/mcp	Streamable HTTP	以 http:// 或 https:// 开头的 URL

3.2 通讯渠道

在 Chat 模式下，QQ、飞书、微信ClawBot 等通讯渠道以 [[terminals]] 终端形式接入， 每个渠道拥有独立的会话，用户在这些渠道发送消息，Agent 一问一答地回复。 具体配置方式见上文 二、终端配置。

3.3 内置 MCP Server

多个终端可同时接入，每个终端拥有独立的会话，共享同一个 MCP 客户端，真正做到「一个大脑，多只手」。

[[mcp.servers]]
name        = "filesystem"
description = "文件系统读取操作等"
endpoint    = "filesystem"
# args = ['~', 'D:\', 'E:\']  # ~ 代表用户主目录， 默认为当前目录

[[mcp.servers]]
name        = "time"
description = "获取当前时间时区,查看设置定时任务等"
endpoint    = "time --with-timer"

[[mcp.servers]]
name        = "skill"
description = "技能指南，可以学习如何做事情"
endpoint    = "skill"
# args = ["./skills", "~/my-skills"]  # 自定义 skills 目录
# 默认：当前目录的 skills 或 ~/.mcp-agent/skills

[[mcp.servers]]
name        = "subagent"
description = "子智能体，适合处理目标清晰而上下文可能很长的小任务"
endpoint    = "subagent"
# args = []  # 自定义 agents 目录
# 默认：当前目录的 subagents 或 ~/.mcp-agent/subagents

[[mcp.servers]]
name        = "command"
description = "命令行执行工具（不走 shell）"
endpoint    = "command --workdir=. --allow=go,git,pnpm --deny=rm,powershell"

[[mcp.servers]]
name        = "git"
description = "支持执行各种git命令"
endpoint    = "git"
args = [
    "--write-access",
    "--discover-level=1",   # 扫描深度：0=不扫描，1=一级子目录，2=二级，以此类推
    "~/data/code",          # ~ 代表用户目录，也可指定绝对路径如 D:\my-projects
]

[[mcp.servers]]
name        = "nodejs"
description = "nodejs环境，可以运行JavaScript代码"
endpoint    = "nodejs"

通过 allowed_tools 和 denied_tools 控制每个 Server 暴露的工具：

[[mcp.servers]]
name          = "filesystem"
endpoint      = "filesystem"
allowed_tools = ["read_file", "list_directory"]  # 仅暴露这两个工具
denied_tools  = ["delete_file"]                  # 始终排除

对 stdio 子进程类型的 Server，可通过 env 注入环境变量：

[[mcp.servers]]
name     = "my-server"
endpoint = "node my-mcp-server.js"
env = { API_KEY = "xxx", DEBUG = "true" }

需要 Node.js v24.14.0 LTS 以及 Microsoft Edge 或 Firefox。

[[mcp.servers]]
name = "playwright"
description = """
常用网址：
天气 https://tianqi.qq.com/
新闻 https://www.msn.cn/zh-cn/...
搜索引擎 https://cn.bing.com/search?q=%s
"""
endpoint = "npx -y @playwright/mcp@latest --browser=msedge"
# endpoint = "npx -y @playwright/mcp@latest --browser=firefox"
# endpoint = "npx -y @playwright/mcp@latest --browser=msedge --headless"

申请 API Key：高德开放平台

[[mcp.servers]]
name="gaode-map"
description="高德地图服务：基础LBS服务（含路径规划、地理编码等）、基础地图定位服务和基础搜索服务"
endpoint="https://mcp.amap.com/mcp?key=xxx"

申请 API Key：腾讯位置服务

[[mcp.servers]]
name="tencent-map"
description="腾讯地图服务：基础LBS服务（含路径规划、地理编码等）、基础地图定位服务和基础搜索服务"
endpoint="https://mcp.map.qq.com/mcp?key=xxx&format=0"

四、完整配置示例

完整的配置文件示例请参考： mcp-agent.example.zip

# ===== Agent 身份 =====
[agent]
name        = "my-assistant"
description = "我的私人助手"

# ===== LLM 配置 =====
[llm]
base_url = "http://127.0.0.1:11434/v1"
api_key  = "-"
model    = "qwen3.5"
stream   = true
retry_count = 3

# ===== 系统提示词 =====
[prompt]
system = """
你是用户的私人助手，请按用户指示进行回复，语言尽可能精简。
调用危险工具（如:删除）一定要请示用户，得到肯定后才执行。
"""

# ===== 终端 =====
# Chat 模式：多终端多会话并发
[[terminals]]
type = "web"
host = "127.0.0.1"
port = 8088

# ===== MCP Servers =====
[[mcp.servers]]
name        = "time"
description = "获取当前时间时区,查看设置定时任务等"
endpoint    = "time --with-timer"

[[mcp.servers]]
name        = "filesystem"
description = "文件系统读取操作等"
endpoint    = "filesystem ~"

[[mcp.servers]]
name        = "skill"
description = "技能指南，可以学习如何做事情"
endpoint    = "skill"

[[mcp.servers]]
name        = "subagent"
description = "子智能体，适合处理目标清晰而上下文可能很长的小任务"
endpoint    = "subagent"

[[mcp.servers]]
name        = "git"
description = "支持执行各种git命令"
endpoint    = "git"
args = ["--write-access", "--discover-level=1", "~/data/code"]

[[mcp.servers]]
name        = "nodejs"
description = "nodejs环境，可以运行JavaScript代码"
endpoint    = "nodejs"

# 远程 MCP Server（HTTP）
[[mcp.servers]]
name        = "gaode-map"
description = "高德地图服务：路径规划、地理编码、定位、搜索等"
endpoint    = "https://mcp.amap.com/mcp?key=YOUR_API_KEY"

# stdio 子进程 MCP Server
[[mcp.servers]]
name        = "playwright"
description = "浏览器自动化"
endpoint    = "npx -y @playwright/mcp@latest --browser=msedge --headless"

五、Autopilot 模式（自主模式）

除上文介绍的 Chat 模式（一问一答）外，智虾助手还支持 Autopilot 模式（自主模式）：Agent 像人一样持续在线运行， 接收来自 Web、QQ、微信、飞书、定时器等各种渠道的事件，自主决定是否调用工具以及如何回复。

6.1 与 Chat 模式的区别

对比项	Chat 模式	Autopilot 模式
交互方式	一问一答	事件驱动，自主处理
终端 / 会话	多终端并发，每终端独立会话	单终端单会话
渠道接入	作为 [[terminals]] 终端	作为 [[mcp.servers]] 推送事件
定时任务	到期提醒	到期作为事件触发 Agent 主动处理
监控界面	Web 聊天界面	Autopilot 监控界面 + POST /event

6.2 Autopilot 终端配置

配置 host / port 后，会额外暴露 Autopilot 监控界面（实时查看事件与处理过程） 与 POST /event 事件推送接口；留空则为无头模式（仅响应 MCP Server 推送的事件）。

字段	类型	默认值	说明
type	string	-	固定为 autopilot
host	string	127.0.0.1	监控界面 / 事件接口监听地址
port	int	8088	监控界面 / 事件接口监听端口

[[terminals]]
type = "autopilot"
host = "127.0.0.1"
port = 8088

6.3 通讯渠道接入

在 Autopilot 模式下，QQ、飞书、微信ClawBot 等通讯渠道以 [[mcp.servers]] 形式接入， 携带 --with-receiver 参数后，这些渠道收到的消息会作为事件推送到 Autopilot 的 Inbox，触发 Agent 处理； Agent 亦可通过它们提供的 send_message 等工具主动回复。

QQ 机器人

[[mcp.servers]]
name        = "qq"
description = "QQ收发消息"
endpoint    = "qq"
args        = [
    "--with-receiver",
    "--app-id=your_app_id",
    "--app-secret=your_app_secret",
]

飞书机器人

需申请 飞书应用，获取 app_id 和 app_secret。

[[mcp.servers]]
name        = "feishu"
description = "飞书收发消息、云文档、多维表格、日历等"
endpoint    = "feishu"
args        = [
    "--app-id=cli_xxxxxxxxxx",
    "--app-secret=your_app_secret",
    "--with-receiver",
    "--with-all-tools",
]

微信 ClawBot

需 node 执行 weixin-clawbot-toml.js，获取配置。

[[mcp.servers]]
name        = "weixin"
description = "微信收发消息"
endpoint    = "weixin"
args        = [
    "--with-receiver",
    "--base-url=https://ilinkai.weixin.qq.com",
    "--cdn-base-url=https://novac2c.cdn.weixin.qq.com/c2c",
    "--bot-token=xxx@im.bot:xxx",
    "--ilink-bot-id=xx@im.bot",
    "--ilink-user-id=xxxk@im.wechat",   # 可选，仅响应此用户
]

6.4 Autopilot 完整配置示例

完整的 Autopilot 模式配置文件示例：

# ===== Agent 身份 =====
[agent]
name        = "my-assistant"
description = "我的私人助手"

# ===== LLM 配置 =====
[llm]
base_url = "http://127.0.0.1:11434/v1"
api_key  = "-"
model    = "qwen3.5"
stream   = true
retry_count = 3

# ===== 系统提示词 =====
[prompt]
system = """
你是用户的私人助手，请按用户指示进行回复，语言尽可能精简。
调用危险工具（如:删除）一定要请示用户，得到肯定后才执行。
"""

# ===== 终端 =====
# Autopilot：单终端 + 单会话，持续运行接收事件
[[terminals]]
type = "autopilot"
host = "127.0.0.1"
port = 8088

# ===== MCP Servers =====
[[mcp.servers]]
name        = "time"
description = "获取当前时间时区,查看设置定时任务等"
endpoint    = "time --with-timer"

[[mcp.servers]]
name        = "filesystem"
description = "文件系统读取操作等"
endpoint    = "filesystem ~"

[[mcp.servers]]
name        = "skill"
description = "技能指南，可以学习如何做事情"
endpoint    = "skill"

[[mcp.servers]]
name        = "subagent"
description = "子智能体，适合处理目标清晰而上下文可能很长的小任务"
endpoint    = "subagent"

# 通讯渠道（携带 --with-receiver 推送事件到 Autopilot Inbox）
[[mcp.servers]]
name        = "weixin"
description = "微信收发消息"
endpoint    = "weixin"
args        = [
    "--with-receiver",
    "--base-url=https://ilinkai.weixin.qq.com",
    "--bot-token=xxx@im.bot:xxx",
    "--ilink-bot-id=xx@im.bot",
]

[[mcp.servers]]
name        = "feishu"
description = "飞书收发消息、云文档、多维表格、日历等"
endpoint    = "feishu"
args        = [
    "--app-id=cli_xxxxxxxxxx",
    "--app-secret=your_app_secret",
    "--with-receiver",
    "--with-all-tools",
]

[[mcp.servers]]
name        = "qq"
description = "QQ收发消息"
endpoint    = "qq"
args        = [
    "--with-receiver",
    "--app-id=your_app_id",
    "--app-secret=your_app_secret",
]

# 远程 MCP Server（HTTP）
[[mcp.servers]]
name        = "gaode-map"
description = "高德地图服务：路径规划、地理编码、定位、搜索等"
endpoint    = "https://mcp.amap.com/mcp?key=YOUR_API_KEY"

# stdio 子进程 MCP Server
[[mcp.servers]]
name        = "playwright"
description = "浏览器自动化"
endpoint    = "npx -y @playwright/mcp@latest --browser=msedge --headless"