Gemini CLI 的子代理系统让主代理可以把专项任务委托给"专家"代理——每个子代理有独立的上下文窗口、专属工具集和系统提示词。内置四种子代理：代码库侦探（codebase_investigator）、CLI 帮助（cli_help）、通才（generalist）和浏览器代理（browser_agent）。用 @代理名 可强制调用指定子代理，也可通过 .md 文件创建自定义子代理。

子代理（Subagents）

子代理是运行在 Gemini CLI 主会话内的专业化代理，用于处理需要深度上下文或特定工具集的复杂任务，同时不污染主会话的历史记录。

子代理的核心价值

• 独立上下文：子代理的对话历史单独存储，不会撑大主会话的上下文窗口
• 专属工具：可限定子代理只能访问特定工具，避免越权操作
• 专家分工：复杂任务（如代码库分析、浏览器自动化）交给专精的代理处理，质量更高

如何调用子代理

自动委托

主代理内置判断逻辑：当任务匹配某个子代理的专长时，会自动调用该子代理。例如，问"认证系统是怎么工作的？"，主代理可能会调用 codebase_investigator 来完成代码分析。

@ 语法（强制调用）

在 Prompt 开头加 @代理名，跳过主代理的决策直接调用指定子代理：

@codebase_investigator 分析 AgentRegistry 和 LocalAgentExecutor 之间的关系
@generalist 将 src/ 目录下所有 TypeScript 文件的类型注释补全
@browser_agent 打开 github.com 并提取最新的 gemini-cli 发布版本号

内置子代理

代码库侦探（codebase_investigator）

专门用于分析代码库结构、逆向工程、追踪依赖关系。

适合场景：

• "认证系统是怎么实现的？"
• "找出所有调用 sendEmail 函数的地方"
• "解释 AgentRegistry 类的设计思路"

自定义配置（在 settings.json 中）：

{
  "agents": {
    "overrides": {
      "codebase_investigator": {
        "modelConfig": { "model": "gemini-2.5-flash" },
        "runConfig": { "maxTurns": 50 }
      }
    }
  }
}

CLI 帮助（cli_help）

内置 Gemini CLI 文档知识库，回答关于 CLI 自身的配置和使用问题。

适合场景：

• "如何配置代理？"
• "/rewind 命令怎么用？"
• "settings.json 里的 tools.core 字段是什么意思？"

通才代理（generalist）

继承主会话的全部工具权限，用于在隔离上下文中执行资源密集型任务，完成后只向主会话汇报最终结果。

最适合的场景：

• 多文件修改：跨多个文件应用重构，产生大量输出
• 高密度执行：运行测试或命令产生海量终端输出
• 探索式研究：同时需要代码搜索和文件修改来找出答案

@generalist 将整个 src/ 目录的函数注释从英文翻译成中文

浏览器代理（browser_agent，实验性）

自动化操作 Chrome 浏览器——导航、填表、点击按钮、提取信息。

启用方式（默认禁用）：

{
  "agents": {
    "overrides": {
      "browser_agent": {
        "enabled": true
      }
    }
  }
}

前置条件：Chrome 144 或更新版本，无需额外安装（内置 chrome-devtools-mcp）。

会话模式：

模式	说明
persistent（默认）	保存 Cookie 和历史，复用 ~/.gemini/cli-browser-profile/
isolated	每次新建临时 Profile，结束后自动清理
existing	附加到已有 Chrome 实例（需要 chrome://inspect/#remote-debugging）

配置示例：

{
  "agents": {
    "browser": {
      "sessionMode": "isolated",
      "allowedDomains": ["github.com", "docs.google.com"],
      "maxActionsPerTask": 50
    }
  }
}

Docker 沙箱中使用浏览器代理：容器内无法启动 Chrome，必须将 sessionMode 设为 "existing" 并在宿主机启用远程调试（--remote-debugging-port=9222），再用 GEMINI_SANDBOX=docker SANDBOX_PORTS=9222 gemini 启动。

创建自定义子代理

文件位置

位置	路径	作用范围
项目级	.gemini/agents/*.md	与团队共享
用户级	~/.gemini/agents/*.md	仅个人使用

文件格式

文件必须以 YAML frontmatter 开头，正文即为该代理的系统提示词：

---
name: security-auditor
description: 专门查找代码中的安全漏洞，适合所有涉及安全审计的任务。
kind: local
tools:
  - read_file
  - grep_search
model: gemini-2.5-flash
temperature: 0.2
max_turns: 10
---

你是一名严苛的安全审计员。你的工作是分析代码中的潜在漏洞。

重点关注：
1. SQL 注入
2. XSS（跨站脚本）
3. 硬编码凭证
4. 不安全的文件操作

找到漏洞时，清晰说明问题并提出修复建议。不要自行修复，只汇报。

配置字段说明

字段	类型	必填	说明
name	string	是	唯一标识符，只允许小写字母、数字、连字符、下划线
description	string	是	主代理看这段描述决定是否调用该子代理，写得越清晰越好
kind	string	否	local（默认）或 remote
tools	array	否	可用工具列表，省略则继承主会话所有工具
model	string	否	指定模型，默认 inherit（继承主会话）
temperature	number	否	0.0 ~ 2.0，默认 1
max_turns	number	否	最大对话轮次，默认 30
timeout_mins	number	否	最长执行时间（分钟），默认 10

工具通配符

tools:
  - "*"          # 所有内置工具 + MCP 工具
  - "mcp_*"      # 所有 MCP 工具
  - "mcp_github_*"  # 特定 MCP 服务器的所有工具

注意：即使授予了 * 通配符，子代理也无法调用其他子代理（防止递归死循环）。

通过 settings.json 持久化管理

启用/禁用与覆盖运行配置

{
  "agents": {
    "overrides": {
      "security-auditor": {
        "enabled": false
      },
      "codebase_investigator": {
        "runConfig": {
          "maxTurns": 40,
          "maxTimeMinutes": 15
        }
      }
    }
  }
}

全局禁用子代理系统

{
  "experimental": {
    "enableAgents": false
  }
}

/agents 命令（交互式管理）

在 CLI 会话中运行 /agents 可以实时启用/禁用/查看子代理，无需手动编辑配置文件。

提高自定义子代理被调用的概率

主代理根据子代理的 description 字段决定是否调用它。描述越具体、越明确"什么场景用"，调用成功率越高：

# 好的 description 示例
Git 专家代理，负责所有本地和远程 Git 操作，包括：提交、bisect 查找回归、
与 GitHub 等代码托管平台交互。

# 差的 description 示例
用于 Git 相关任务

常见问题

Q: 子代理可以再调用其他子代理吗？

A: 不可以。Gemini CLI 有内置的递归保护机制，子代理无法调用其他子代理，即使拥有 * 工具权限也不行。这防止了无限循环和 Token 爆炸。

Q: 自定义子代理和 Skills 有什么区别？

A: 子代理运行在独立的上下文窗口中，有自己的对话历史和工具集；Skills 是通过 /skills 命令触发的结构化工作流，直接在主会话中运行。子代理适合复杂、独立的任务；Skills 更适合标准化的操作流程。

Q: 如何确认某个任务是被子代理执行的？

A: 在任务执行过程中，界面会显示当前使用的子代理名称。也可以在 settings.json 中给子代理设置特定模型，通过 /stats 命令看到对应的 Token 用量来确认。