子代理

查看可用列表

TUI 方式：在 TUI 中输入：

/agents

/agents 面板按来源分组展示 Subagent，并支持查看详情、创建、启用/禁用、编辑自定义项和重新加载。修改 .qoder/agents/ 或 ~/.qoder-cn/agents/ 后，可以执行：

/agents reload

Headless 方式：在非交互环境中，可以使用：

qoderclicn agents list

列表会显示所有发现到的 Subagent。若同名 Subagent 被更高优先级来源覆盖，列表会标记 shadowed 项。

来源和优先级

Qoder CN CLI 会从多个来源发现 Subagent。同名定义按优先级覆盖，优先级 从低到高 如下：

实际生效的是最高优先级的同名定义；被覆盖的定义会在 qoderclicn agents list 中标记为 shadowed。

显式调用

TUI 模式：在 TUI 会话中，最稳定的方式是在输入中直接写出 Subagent 名称：

使用 api-reviewer subagent 审查这个接口设计

也可以在 TUI 输入中使用 @ 提及已经加载的 Subagent：

@api-reviewer 审查这个接口设计，只返回需要修改的点

Headless 模式：通过 qoderclicn -p 传入同样的自然语言请求：

qoderclicn -p "使用 api-reviewer subagent 审查这个接口设计"

隐式调用

使用自然语言直接输入任务内容，让 Qoder CN CLI 帮助你选择合适的 Subagent 处理任务。

TUI 模式：Qoder CN CLI 会根据可用 Subagent 的 description 判断是否有匹配的可用 Subagent：

帮我做一次接口设计审查

Headless 模式：把任务描述传给 qoderclicn -p 后 Qoder CN CLI 同样会根据 Subagent 的 description 判断使用哪个 Subagent：

qoderclicn -p "帮我做一次接口设计审查"

作为本次会话主 Agent

--agent 会把某个已加载 Subagent 作为当前会话的主 Agent。此时该定义的 initialPrompt 会作为本次会话的初始提示使用。

TUI 模式：启动 TUI 时指定 --agent：

qoderclicn --agent api-reviewer

进入 TUI 后，本次会话会使用 api-reviewer 作为主 Agent。/agents 面板中的运行入口不会切换主会话 Agent，它会通过 @agent-name 触发一次 Subagent 调用。

Headless 模式：和 -p 一起使用：

qoderclicn --agent api-reviewer -p "审查这个接口设计"

编排多个 Subagent

使用自然语言描述 Subagent 的先后执行顺序，Qoder CN CLI 会按照编排的流程处理任务。

TUI 模式：

先使用 general-purpose subagent 检查实现方案，再使用 api-reviewer subagent 审查 API 设计

Headless 模式：

qoderclicn -p "先使用 general-purpose subagent 检查实现方案，再使用 api-reviewer subagent 审查 API 设计" --max-turns 10

如果多个任务彼此独立，可以明确要求并行调度；如果有依赖关系，像上面这样说明先后顺序。--max-turns 是本次 Headless 查询的总轮次上限；要限制单个 Subagent，请在 Subagent 配置中设置 maxTurns。

创建本地持久化 Subagent 定义

> /agents
------------------------------------------------------------------------------------------
Agents:  User  [Project]  BuiltIn

-> Create new agent...

Agent list:
No project agents found.

Press Enter to select - Esc to exit - Tab to cycle tabs - Up/Down to navigate

> /agents
------------------------------------------------------------------------------------------
Agents:  User  [Project]  BuiltIn

Describe the agent:

> Help me review RESTful api design

Press Enter to select - Esc to exit - Tab to cycle tabs - Up/Down to navigate

# 项目级（Project 标签页）
.qoder/agents/

# 用户级（User 标签页）
~/.qoder-cn/agents/

# 项目级，仅当前项目生效，适合提交到仓库
.qoder/agents/api-reviewer.md

# 用户级，在当前用户的所有项目中生效
~/.qoder-cn/agents/api-reviewer.md

---
name: api-reviewer
description: Review API designs, endpoint naming, request methods, status codes, error responses, and versioning.
tools: [Read, Grep, Glob]
disallowedTools: [Write, Edit]
permissionMode: default
model: inherit
maxTurns: 8
timeoutMins: 10
color: cyan
---

You are an API design reviewer.

Focus on:
- Resource naming and URL structure
- Request method semantics
- Status code and error response consistency
- Pagination, filtering, and versioning

Return concise findings grouped by severity. Include concrete examples when possible.

isolation: worktree

用 --agents 临时注入

--agents 适合 Headless、脚本和一次性自动化。它接收一个 JSON 对象，键是 Subagent 名称，值是定义内容。通过 --agents 注入的 Subagent 只对当前进程生效，并且同名时优先级最高。

qoderclicn \
  --agents '{"api-reviewer":{"description":"Review API designs","prompt":"You are an API reviewer.","tools":["Read","Grep","Glob"],"maxTurns":6}}' \
  -p "使用 api-reviewer subagent 审查 docs/api.yaml"

--agents 使用 prompt 字段作为系统提示词。当前 JSON schema 支持：description、prompt、tools、disallowedTools、mcpServers、model、effort、color、maxTurns、initialPrompt、skills、permissionMode。如果需要 timeoutMins、temperature、hooks、memory、background 或 isolation，请使用 Markdown 配置。

选择作用域

创建或注入自定义 Subagent 时，可以选择以下作用域：

配置工具

tools 和 disallowedTools 都可以写成逗号分隔字符串或字符串数组。字符串数组既可以使用 YAML 内联数组，也可以使用 YAML 列表：

tools: Read,Grep,Glob

tools: [Read, Grep, Glob]

tools:
  - Read
  - Grep
  - Glob

常用工具名包括 Read、Grep、Glob、Bash、Write、Edit、WebFetch、WebSearch、Agent。

MCP 工具使用完全限定名：

tools:
  - mcp__docs__search
  - mcp__docs__*
  - mcp__*

如果希望某个 Subagent 只能继续调用特定 Subagent，请使用 Agent(name) 表达式：

tools:
  - Read
  - Grep
  - Agent(Explore, Plan)

如果不希望它继续调度任何 Subagent，可以禁用 Agent：

disallowedTools: [Agent]

工具集合的处理顺序是：先根据 tools 注册可用工具，再应用 disallowedTools 移除工具。对于 MCP 工具，必须先通过 mcpServers 或全局 MCP 配置发现，再通过 tools 放行，Subagent 才能使用。

配置 MCP

可以引用已经配置好的 MCP 服务：

mcpServers:
  - docs

也可以内联定义只给这个 Subagent 使用的 MCP 服务：

mcpServers:
  docs:
    command: ./scripts/docs-mcp
    args: ["--stdio"]
    include_tools: ["search", "read"]

mcpServers 支持数组格式，也支持对象格式。内联服务字段如下：

定义 Hook

hooks 写在 Subagent frontmatter 中时，只对该 Subagent 会话生效。支持的事件包括 PreToolUse、PostToolUse、PostToolUseFailure、Stop、SubagentStart、SubagentStop、Notification。

hooks 不支持字符串简写。每个事件的值必须是 matcher 数组；每个 matcher 里再通过 hooks 数组声明一个或多个 Hook。

Subagent 中的 Stop 会映射为 SubagentStop，即在该 Subagent 完成时触发，而不是在主会话结束时触发。

hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: ./scripts/check-subagent-command.sh
          timeout: 30
          statusMessage: Checking command
  Stop:
    - hooks:
        - type: command
          command: ./scripts/subagent-finished.sh

每个事件下是一组 matcher；每个 matcher 中的 hooks 支持以下类型：

frontmatter schema 也接受 once，但普通 Subagent frontmatter 中该字段不会作为一次性 Hook 语义保留；需要一次性行为时，请在 Hook 命令或外部状态中自行控制。

配置权限模式

permissionMode 控制 Subagent 工具调用的审批方式。

permissionMode 建议使用上表中的规范值。运行时会兼容大小写、下划线、连字符等写法；yolo 会被兼容解析为 bypassPermissions，但公开配置建议直接写 bypassPermissions。

需要注意：

• 未声明 permissionMode 时，Subagent 继承父会话当前模式。

• 父会话已经处于 acceptEdits、bypassPermissions 或 auto 时，Subagent 不能通过自己的配置把权限降得更严格。

• plan 不会污染主会话计划状态，它只在该 Subagent 的隔离上下文中生效。

配置远程 Subagent

远程 Subagent 通过 Agent Card 加载，不使用 Markdown 正文作为系统提示词，而是根据远程 Agent Card 暴露的能力和描述完成调用。

---
kind: remote
name: docs-helper
description: Answer questions using the remote documentation agent.
agentCardUrl: https://agent.example/.well-known/agent-card.json
---

也可以使用 agentCardJson 内联 Agent Card JSON。远程 Subagent 支持 auth 字段；常用认证类型包括 apiKey、http 和 oauth。需要认证时，建议把远程 Subagent 放在用户级配置中，避免把凭据提交到项目仓库。

使用 settings.json 覆盖已有 Subagent

settings.json 不能创建新的 Subagent，只能覆盖已经被发现的同名 Subagent。当前支持覆盖启用状态、模型配置、运行限制、工具白名单，并追加 MCP 服务。

{
  "agents": {
    "overrides": {
      "api-reviewer": {
        "enabled": true,
        "tools": ["Read", "Grep", "Glob"],
        "runConfig": {
          "maxTurns": 6,
          "maxTimeMinutes": 10
        },
        "modelConfig": {
          "model": "auto",
          "generateContentConfig": {
            "temperature": 0.2
          }
        },
        "mcpServers": {
          "docs": {
            "command": "./scripts/docs-mcp",
            "args": ["--stdio"]
          }
        }
      }
    }
  }
}

常见用途：

• 设置 "enabled": false 暂时隐藏某个 Subagent。

• 为某个 Subagent 单独调整模型和温度。

• 为自动化场景限制最大轮次或最长执行时间。

• 在不修改原始 Markdown 的情况下收紧工具集合。

• 为已有本地 Subagent 追加 MCP 服务。

插件提供的 Subagent 会应用额外安全策略：插件 Subagent 的 hooks、mcpServers、permissionMode 会被移除，isolation 只有 worktree 会被保留。

本地 Subagent 可配置全字段表

以下字段适用于 Markdown frontmatter。未识别字段会被忽略。