cc-haha 桌面端子 Agent 完整指南任务委派、内置 Agent 与自定义配置【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha子 AgentSubagent是 cc-haha 桌面端多 Agent 协作的核心机制主 Agent 将一个边界清晰的任务交给一个携带独立上下文的副本去执行副本只把结论与证据交回主对话。本文以 docs/en/desktop/agents.md中文对照见 docs/desktop/agents.md为主线结合 Agent 系统原理 与桌面端 AgentManager.tsx、agentStore.ts、agents.ts 的实现细节系统讲解什么时候该委派、六个内置 Agent 各自擅长什么、如何在「设置 → Agents」中浏览与调整、以及如何从零创建并持久化一个属于自己的 Agent。读完后你将能在 cc-haha 桌面端独立完成子 Agent 的选型、调优与自定义开发。什么是子 Agent子 Agent 是「被派出去干一件明确小任务的 Claude 副本」。它与主 Agent 的最大区别在于上下文边界子 Agent 在一个独立的上下文窗口中工作只把结论和证据返回给主对话中间的调查过程、工具调用记录都留在它自己的上下文里不会污染主对话的上下文预算。这个设计让两种任务尤其受益独立调查可以整体委派。例如「调查某个模块的认证流程」涉及多个文件、有明确的问题、范围和预期证据交给子 Agent 后主 Agent 可以继续推进其他工作。轻量查询不必委派。例如查找validateUser的调用位置通常一次定向搜索就能完成为此启动一个子 Agent 反而浪费启动时间和上下文传输成本。需要强调的是委派本身有成本启动耗时、上下文传递、结果整合。下文会给出更具体的取舍标准。什么时候该派什么时候不该派适合委派的场景源自文档可以独立站住的调查—— 需要阅读多个文件且能明确约定问题、范围和应返回的证据可并行执行的独立工作—— 比如前端、后端分开调查涉及代码编辑时给每个子 Agent 划清文件归属由主 Agent 负责整合与最终验证有特定关注点的独立复核—— 例如把「权限边界」和「会话恢复」分开检查而不是无差别地重复一整轮审查。通常应留在主 Agent 的任务简单搜索已明确位置的小改动短任务且下一步必须等待其结果才能继续任何「结果立刻要用」的中间步骤。委派后的可视化被派出的子 Agent 会出现在活动面板的SubAgents区块工具活动实时冒泡展示点开任意一个可以看到它的完整运行记录和最终结果。后台运行run_in_background的子 Agent 同样如此——你不必等它跑完就能实时看到它在做什么。这一交互对应的数据来自桌面端的 subagent API 模块 subagents.ts 与其测试 subagents.test.ts。内置 Agent开箱即用的六个角色无需任何配置即可直接使用的内置 Agent 共有六个文档给出的速览表如下名称用途general-purpose通用兜底。研究复杂问题、搜索代码、多步骤任务不确定派谁就派它Explore快速探索代码库。按模式找文件、按关键词搜代码、回答「这块是怎么工作的」Plan架构师。设计实现方案返回分步计划、关键文件和取舍claude-code-guide回答关于 Claude Code、Agent SDK 和 Claude API 本身的问题verification收工前的验收。跑构建、测试、linter给出通过 / 失败 / 部分通过的结论statusline-setup配置 Claude Code 状态栏在会话中可以直接点名委派「用 Explore 去找一下……」也可以不指定让 Claude 根据任务性质自行判断该派谁。各内置 Agent 的工具池与模型特征根据 Agent 系统原理 中记录的内部实现六个内置 Agent 在工具池、模型与读写能力上有明确分工Agent读写能力工具池默认模型用途general-purpose读写全部工具继承父 Agent通用任务Explore不能改文件全部工具减去编辑类Edit / Write / NotebookEdit / Agent 等Haiku快速探索Plan不能改文件同 Explore继承父 Agent架构规划verification不能改项目文件同 Explore另允许在 tmp 下写临时测试脚本继承父 Agent独立验证claude-code-guide只读搜索 网络工具Glob / Grep / Read / WebFetch / WebSearchHaiku文档指南statusline-setup读写仅 Read EditSonnet状态栏配置注意两个容易被忽略的点Explore 虽然不能改文件但它的工具池包含 Bash—— 它能执行任意命令只是无法落盘写文件文档明确提示Explore与claude-code-guide默认走 Haiku快、便宜statusline-setup走 Sonnet这是按「速度与成本」而非「输出质量」做的出厂选择——如果你更看重质量可以按后文方法单独调整。浏览已安装的 Agent设置 → Agents打开桌面端设置 → Agents即可看到当前环境下的全部 Agent该入口实现在 AgentManager.tsx由 Settings.tsx 挂载。页面布局分两层顶部三张汇总卡Agent 总数、当前生效数active、来源类型数sources。对应代码中 SummaryCard 渲染的三个统计项其中生效数来自activeAgents来源数按AGENT_SOURCE_ORDER过滤出非空分组后计数。来源分组列表按固定顺序分组展示顺序为User用户→ Project项目→ Local本地→ Managed托管策略→ Plugin插件→ CLI argCLI 参数→ Built-in内置这一顺序在源码中定义于 AGENT_SOURCE_ORDER对应的 Agent 来源类型userSettings/projectSettings/localSettings/policySettings/plugin/flagSettings/built-in定义在 agents.ts。同名覆盖规则当多个来源存在同名 Agent 时排位靠前的来源会覆盖靠后的被覆盖的那个会被标记为「Overridden by X」。这一点在列表行的 overriddenBy 徽标 和详情页都有体现且底层列表数据overriddenBy字段由服务端跨来源统一计算见 agentStore.ts 中「覆盖关系需要全量列表才能一致」的注释。日常最常打交道的两组User用户你自己创建的 Agent对所有项目生效文件存放在~/.claude/agents/Project项目仅对当前项目生效文件存放在项目目录的.claude/agents/下会随仓库一起分发。详情页与行内操作点击任意一行进入详情页可以看到该 Agent 的模型、推理强度effort、工具范围、完整系统提示词实现见 AgentDetailView其中DetailStat展示配置模型与 effortMarkdownRenderer 渲染系统提示词。内置与插件来源是只读的详情页右上角显示锁形「只读」标记LockKeyhole图标 settings.agents.readOnly文案没有编辑/删除按钮只有用户与项目来源可编辑。悬停行出现操作按钮用户/项目 Agent 显示「编辑」「删除」内置 Agent 显示「调整模型」AgentRowActions组件AgentManager.tsx。编辑和删除也会同步出现在详情页右上角。可调整的内置 Agent只有overridable true的内置 Agent 才显示「调整模型」按钮agents.ts 中overridable字段的注释明确仅内置 Agent 可通过 override 调整模型与 effort。调整内置 Agent 的模型与推理强度内置 Agent 的模型与 effort 是可覆盖的但系统提示词、工具范围和颜色不可改仍由内置定义锁定。操作入口与可选项点击内置 Agent 行上的「调整模型」或详情页右上角同名按钮打开覆盖弹窗BuiltInAgentOverrideModal。只有两项可编辑模型Model内置默认 / 继承主会话Inherit from parent/ Haiku / Sonnet / Opus / Fable 别名 / 当前 Provider 已配置的模型推理强度Effort内置默认或 low / medium / high / xhigh / max 五档。其中模型别名常量定义在 BUILT_IN_MODELSeffort 档位定义在 EFFORTS。模型选择器AgentModelSelector会列出当前 Provider 的可用模型、四个别名与「继承」选项。「内置默认」与「继承主会话」的区别这是文档特别强调的易混点二者不是一回事内置默认Built-in default该 Agent 出厂时钉死的模型。以Explore为例就是它默认绑定的 Haiku继承主会话Inherit from parent跟随主对话当前正在使用的模型。想恢复出厂设置选「内置默认」或直接点「Reset to built-in default」按钮。底层实现上弹窗保存时选择「内置默认」会提交null从而删除该覆盖记录而不是写入默认值的字面量——见 AgentManager.tsx 中「永远不要把默认值的字面量写死进用户配置文件」的注释逻辑以及 agentStore.ts 中「内置默认是什么由服务端决定store 绝不在本地重建」的注释。覆盖记录的落盘位置覆盖写入~/.claude/settings.json的builtInAgentOverrides字段对所有项目生效。手工编辑等价于{ builtInAgentOverrides: { Explore: { model: sonnet, effort: low }, general-purpose: { effort: high } } }示例来自 Agent 系统原理。key 是 spawn 时使用的 agentType大小写敏感。覆盖的几个易踩规则只有 model / effort 两个字段可改。覆盖不会改变source仍是built-in因此内置 Agent 的工具特权保持不变清除覆盖 删除字段而不是写inherit。各内置 Agent 的出厂默认互不相同Explore默认haiku、Plan默认继承父会话、general-purpose甚至不写 model所以model: inherit是一个正常的取值表示跟随主会话与「恢复默认」含义不同未知的 agentType 会被忽略但不会被清理内置 Agent 集合随 feature flag 与 entrypoint 变化自动清理会在开关翻转时销毁有效配置同名用户 Agent 会完全遮蔽内置 Agent如果你手写了一个name: Explore的用户 Agent它会把内置的Explore完全盖住此时调整内置的模型不会产生任何效果——弹窗里会提示这一点对应 AgentManager.tsx 中overrideShadowed警告逻辑策略限制当组织策略strictPluginOnlyCustomization包含agents时用户级与项目级覆盖在解析阶段即被忽略只有 managed 来源生效生效时机与 Agent Markdown 文件一样手工改 settings.json 不会自动作用于已在运行的会话桌面端保存时会触发一次会话重载手工改文件则需要重启会话或执行/reload-plugins。模型与 Provider 的绑定关系Agent 配置里保存的是模型 ID而不是 Provider。模型选择器列出的是当前 Provider 的可用模型以后如果切换 Provider别名Haiku / Sonnet / Opus / Fable会按新 Provider 的映射重新解析完整模型 ID则要求新 Provider 也支持该模型否则不可用。创建自己的 Agent点击「设置 → Agents」右上角的Create Agent按钮打开创建弹窗AgentFormModal。各字段说明如下配置范围Scope—— 用户还是项目。选「项目」时需确认目标项目路径弹窗内提供目录选择器DirectoryPicker仅创建模式可选编辑模式下 Scope 被禁用。用户范围写入~/.claude/agents/项目范围写入目标项目的.claude/agents/名称Name—— 1–64 位小写字母、数字、连字符或下划线。这是主 Agent 调用它时使用的名字。源码中校验正则见 NAME_PATTERN/^a-z0-9?$/即必须以字母或数字开头和结尾中间可含连字符与下划线例如code-reviewer描述Description—— 说明主 Agent 应该在什么场景下委派给它。这是最重要的字段主 Agent 正是靠它来决定要不要调用这个 Agent。写得太含糊这个 Agent 就永远不会被叫到。创建/编辑时该字段为必填descriptionRequired校验见 handleSubmit系统提示词System prompt—— 定义职责、边界和预期输出。创建模式下必填模型Model—— 继承主 Agent或选择 Haiku / Sonnet / Opus / Fable 别名或选择当前 Provider 已配置的模型。简单重复的活交给 Haiku 更快更省推理强度Effort—— 继承或指定 low / medium / high / xhigh / max。模型不支持某档时会自动降级或忽略该字段工具Tools—— 三选一全部工具inherit、不允许使用工具none、自定义列表custom。自定义模式下内置工具按「读取与搜索 / 修改文件 / 执行命令 / 工作流」四类分组勾选分组元数据见 TOOL_METADATA 与 ToolPicker下方还有一个自由输入框用于填写 MCP 工具名或形如Bash(git:*)的权限规则自由输入框的解析器 parseTools 专门处理了括号配对因此带参权限规则可以安全地包含空格与逗号颜色Color—— 可选仅用于在界面上区分不同 Agent。可选色板见 AGENT_COLORS共 9 种red / orange / yellow / green / blue / purple / pink / cyan。最小权限原则文档中的原话提示只给任务必需的工具。一个只负责读代码并汇报结论的 Agent不需要 Write 和 Bash——权限收窄了它跑偏的空间也就小了。保存与热重载行为保存操作会把配置写成 Markdown 文件到对应目录并尝试刷新当前会话。刷新失败不会回滚已经写好的文件——重启后定义仍然生效。桌面端的完整行为链在 agentStore.ts 中可见增/改/删/覆盖都会走runAgentMutationagentStore.ts先调用 agentsApi 的create/update/delete/setOverride/clearOverride接口再list全量刷新注释明确覆盖关系跨来源计算只有全量列表才一致随后通过POST /api/agents/reloadagentsApi.reload超时 120 秒热重载运行中的会话若会话未运行或重载失败会返回not_running/failed原因界面顶部出现不阻塞操作的警告条mutationWarning 重试按钮见 AgentManager.tsx。Agent 文件的格式与来源优先级标准 Markdown 定义格式在用户或项目的agents目录下创建.md文件即可定义 Agentfrontmatter 示例来自 Agent 系统原理--- name: code-reviewer description: 专业代码审查代理 tools: - Read - Grep - Glob - Bash model: sonnet effort: high permissionMode: dontAsk maxTurns: 10 --- 你是一个专业的代码审查员。请检查以下方面 1. 代码质量和可读性 2. 潜在的安全漏洞 3. 性能问题 4. 最佳实践遵循可配置字段一览字段类型说明namestringAgent 类型名称descriptionstring何时使用的说明toolsstring[]允许的工具列表[*]表示全部disallowedToolsstring[]禁止的工具列表modelstring使用的模型fable/opus/sonnet/haiku、完整模型 ID 或inheriteffortstring推理强度low/medium/high/xhigh/max以模型能力为准permissionModestring权限模式maxTurnsnumber最大对话轮数mcpServersobject[]需要的 MCP 服务器hooksobjectAgent 特定的钩子colorstringAgent 的界面标识颜色skillsstring[]可使用的技能memorystring记忆作用域user / project / localisolationstring隔离模式worktree / remotebackgroundboolean是否默认后台运行继承的写法想继承当前会话最清楚的做法是省略对应字段——不写model就继承主会话模型不写effort就继承当前会话的推理强度。model: inherit是模型字段的等价显式写法effort没有inherit值。另外需注意Agent工具的单次调用没有effort参数因此 effort 应在 Agent 定义或会话层设置整数形式的effort仅为既有 SDK/JSON 兼容而保留桌面端 Agent 管理器只写入上述五个命名档位。同名 Agent 的来源优先级多个来源定义同名 Agent 时实际生效的定义按以下优先级选择从高到低见 Agent 系统原理策略 Agentpolicy—— 组织托管策略CLI 参数 Agentflag—— 通过--agents注册项目 Agentproject—— 项目目录的.claude/agents/用户 Agentuser——~/.claude/agents/插件 Agentplugin—— 由插件提供内置 Agentbuilt-in—— 系统预定义。桌面端列表会展示被覆盖的定义及其来源但真正 spawn 时使用的是优先级最高的活动定义。模型与推理强度的解析优先级模型从高到低CLAUDE_CODE_SUBAGENT_MODEL的具体模型值设为inherit时不锁定模型本次Agent({ ..., model: ... })调用指定的模型Agent Markdown frontmatter 中的modelsettings.json 中builtInAgentOverrides指定的model仅内置 Agent主会话模型。推理强度从高到低CLAUDE_CODE_EFFORT_LEVELAgent Markdown frontmatter 中的effortsettings.json 中builtInAgentOverrides指定的effort仅内置 Agent当前会话的 effort模型默认值。low、medium、high、xhigh、max是否可用取决于解析后的真实模型及提供商能力Claude 模型会向下回退到可用档位其他提供商按各自的模型目录规范化不支持 effort 的模型不会应用该字段。子 Agent 通常继承主会话的扩展思考extended thinking开关但解析后的模型强制要求优先例如 Fable 5 会规范化为 adaptive thinking。权限模式参考每个 Agent 可设置的权限模式permissionMode模式说明default正常权限请求需要用户确认plan所有操作需要显式审批acceptEdits自动接受文件编辑其他操作需确认bypassPermissions跳过所有权限检查dontAsk拒绝所有未预批准的操作autoAI 驱动的权限分类仅 Ant 内部bubble权限提示冒泡到父 Agent 终端快速参考操作方法浏览/管理已安装 Agent桌面端设置 → AgentsAgentManager.tsx查看 Agent 详情点击列表行查看模型、effort、工具范围与系统提示词调整内置 Agent行内「调整模型」或详情页同名按钮写入~/.claude/settings.json的builtInAgentOverrides恢复内置默认弹窗内「Reset to built-in default」删除整条覆盖记录创建自定义 Agent「Create Agent」弹窗保存为~/.claude/agents/*.md或项目目录/.claude/agents/*.md手工定义 Agent编写带 frontmatter 的 Markdown 文件放入对应 agents 目录热点重载桌面端保存后自动刷新会话刷新失败不阻塞重启后生效本文所有 UI 行为均可在 AgentManager.tsx 及其配套的 agentStore.ts、agents.ts 中找到对应实现与测试如 AgentManager.test.tsx、agentStore.test.ts可继续深入阅读验证。【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 cc-haha 桌面端子 Agent 完整指南：任务委派、内置 Agent 与自定义配置
cc-haha 桌面端子 Agent 完整指南任务委派、内置 Agent 与自定义配置【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha子 AgentSubagent是 cc-haha 桌面端多 Agent 协作的核心机制主 Agent 将一个边界清晰的任务交给一个携带独立上下文的副本去执行副本只把结论与证据交回主对话。本文以 docs/en/desktop/agents.md中文对照见 docs/desktop/agents.md为主线结合 Agent 系统原理 与桌面端 AgentManager.tsx、agentStore.ts、agents.ts 的实现细节系统讲解什么时候该委派、六个内置 Agent 各自擅长什么、如何在「设置 → Agents」中浏览与调整、以及如何从零创建并持久化一个属于自己的 Agent。读完后你将能在 cc-haha 桌面端独立完成子 Agent 的选型、调优与自定义开发。什么是子 Agent子 Agent 是「被派出去干一件明确小任务的 Claude 副本」。它与主 Agent 的最大区别在于上下文边界子 Agent 在一个独立的上下文窗口中工作只把结论和证据返回给主对话中间的调查过程、工具调用记录都留在它自己的上下文里不会污染主对话的上下文预算。这个设计让两种任务尤其受益独立调查可以整体委派。例如「调查某个模块的认证流程」涉及多个文件、有明确的问题、范围和预期证据交给子 Agent 后主 Agent 可以继续推进其他工作。轻量查询不必委派。例如查找validateUser的调用位置通常一次定向搜索就能完成为此启动一个子 Agent 反而浪费启动时间和上下文传输成本。需要强调的是委派本身有成本启动耗时、上下文传递、结果整合。下文会给出更具体的取舍标准。什么时候该派什么时候不该派适合委派的场景源自文档可以独立站住的调查—— 需要阅读多个文件且能明确约定问题、范围和应返回的证据可并行执行的独立工作—— 比如前端、后端分开调查涉及代码编辑时给每个子 Agent 划清文件归属由主 Agent 负责整合与最终验证有特定关注点的独立复核—— 例如把「权限边界」和「会话恢复」分开检查而不是无差别地重复一整轮审查。通常应留在主 Agent 的任务简单搜索已明确位置的小改动短任务且下一步必须等待其结果才能继续任何「结果立刻要用」的中间步骤。委派后的可视化被派出的子 Agent 会出现在活动面板的SubAgents区块工具活动实时冒泡展示点开任意一个可以看到它的完整运行记录和最终结果。后台运行run_in_background的子 Agent 同样如此——你不必等它跑完就能实时看到它在做什么。这一交互对应的数据来自桌面端的 subagent API 模块 subagents.ts 与其测试 subagents.test.ts。内置 Agent开箱即用的六个角色无需任何配置即可直接使用的内置 Agent 共有六个文档给出的速览表如下名称用途general-purpose通用兜底。研究复杂问题、搜索代码、多步骤任务不确定派谁就派它Explore快速探索代码库。按模式找文件、按关键词搜代码、回答「这块是怎么工作的」Plan架构师。设计实现方案返回分步计划、关键文件和取舍claude-code-guide回答关于 Claude Code、Agent SDK 和 Claude API 本身的问题verification收工前的验收。跑构建、测试、linter给出通过 / 失败 / 部分通过的结论statusline-setup配置 Claude Code 状态栏在会话中可以直接点名委派「用 Explore 去找一下……」也可以不指定让 Claude 根据任务性质自行判断该派谁。各内置 Agent 的工具池与模型特征根据 Agent 系统原理 中记录的内部实现六个内置 Agent 在工具池、模型与读写能力上有明确分工Agent读写能力工具池默认模型用途general-purpose读写全部工具继承父 Agent通用任务Explore不能改文件全部工具减去编辑类Edit / Write / NotebookEdit / Agent 等Haiku快速探索Plan不能改文件同 Explore继承父 Agent架构规划verification不能改项目文件同 Explore另允许在 tmp 下写临时测试脚本继承父 Agent独立验证claude-code-guide只读搜索 网络工具Glob / Grep / Read / WebFetch / WebSearchHaiku文档指南statusline-setup读写仅 Read EditSonnet状态栏配置注意两个容易被忽略的点Explore 虽然不能改文件但它的工具池包含 Bash—— 它能执行任意命令只是无法落盘写文件文档明确提示Explore与claude-code-guide默认走 Haiku快、便宜statusline-setup走 Sonnet这是按「速度与成本」而非「输出质量」做的出厂选择——如果你更看重质量可以按后文方法单独调整。浏览已安装的 Agent设置 → Agents打开桌面端设置 → Agents即可看到当前环境下的全部 Agent该入口实现在 AgentManager.tsx由 Settings.tsx 挂载。页面布局分两层顶部三张汇总卡Agent 总数、当前生效数active、来源类型数sources。对应代码中 SummaryCard 渲染的三个统计项其中生效数来自activeAgents来源数按AGENT_SOURCE_ORDER过滤出非空分组后计数。来源分组列表按固定顺序分组展示顺序为User用户→ Project项目→ Local本地→ Managed托管策略→ Plugin插件→ CLI argCLI 参数→ Built-in内置这一顺序在源码中定义于 AGENT_SOURCE_ORDER对应的 Agent 来源类型userSettings/projectSettings/localSettings/policySettings/plugin/flagSettings/built-in定义在 agents.ts。同名覆盖规则当多个来源存在同名 Agent 时排位靠前的来源会覆盖靠后的被覆盖的那个会被标记为「Overridden by X」。这一点在列表行的 overriddenBy 徽标 和详情页都有体现且底层列表数据overriddenBy字段由服务端跨来源统一计算见 agentStore.ts 中「覆盖关系需要全量列表才能一致」的注释。日常最常打交道的两组User用户你自己创建的 Agent对所有项目生效文件存放在~/.claude/agents/Project项目仅对当前项目生效文件存放在项目目录的.claude/agents/下会随仓库一起分发。详情页与行内操作点击任意一行进入详情页可以看到该 Agent 的模型、推理强度effort、工具范围、完整系统提示词实现见 AgentDetailView其中DetailStat展示配置模型与 effortMarkdownRenderer 渲染系统提示词。内置与插件来源是只读的详情页右上角显示锁形「只读」标记LockKeyhole图标 settings.agents.readOnly文案没有编辑/删除按钮只有用户与项目来源可编辑。悬停行出现操作按钮用户/项目 Agent 显示「编辑」「删除」内置 Agent 显示「调整模型」AgentRowActions组件AgentManager.tsx。编辑和删除也会同步出现在详情页右上角。可调整的内置 Agent只有overridable true的内置 Agent 才显示「调整模型」按钮agents.ts 中overridable字段的注释明确仅内置 Agent 可通过 override 调整模型与 effort。调整内置 Agent 的模型与推理强度内置 Agent 的模型与 effort 是可覆盖的但系统提示词、工具范围和颜色不可改仍由内置定义锁定。操作入口与可选项点击内置 Agent 行上的「调整模型」或详情页右上角同名按钮打开覆盖弹窗BuiltInAgentOverrideModal。只有两项可编辑模型Model内置默认 / 继承主会话Inherit from parent/ Haiku / Sonnet / Opus / Fable 别名 / 当前 Provider 已配置的模型推理强度Effort内置默认或 low / medium / high / xhigh / max 五档。其中模型别名常量定义在 BUILT_IN_MODELSeffort 档位定义在 EFFORTS。模型选择器AgentModelSelector会列出当前 Provider 的可用模型、四个别名与「继承」选项。「内置默认」与「继承主会话」的区别这是文档特别强调的易混点二者不是一回事内置默认Built-in default该 Agent 出厂时钉死的模型。以Explore为例就是它默认绑定的 Haiku继承主会话Inherit from parent跟随主对话当前正在使用的模型。想恢复出厂设置选「内置默认」或直接点「Reset to built-in default」按钮。底层实现上弹窗保存时选择「内置默认」会提交null从而删除该覆盖记录而不是写入默认值的字面量——见 AgentManager.tsx 中「永远不要把默认值的字面量写死进用户配置文件」的注释逻辑以及 agentStore.ts 中「内置默认是什么由服务端决定store 绝不在本地重建」的注释。覆盖记录的落盘位置覆盖写入~/.claude/settings.json的builtInAgentOverrides字段对所有项目生效。手工编辑等价于{ builtInAgentOverrides: { Explore: { model: sonnet, effort: low }, general-purpose: { effort: high } } }示例来自 Agent 系统原理。key 是 spawn 时使用的 agentType大小写敏感。覆盖的几个易踩规则只有 model / effort 两个字段可改。覆盖不会改变source仍是built-in因此内置 Agent 的工具特权保持不变清除覆盖 删除字段而不是写inherit。各内置 Agent 的出厂默认互不相同Explore默认haiku、Plan默认继承父会话、general-purpose甚至不写 model所以model: inherit是一个正常的取值表示跟随主会话与「恢复默认」含义不同未知的 agentType 会被忽略但不会被清理内置 Agent 集合随 feature flag 与 entrypoint 变化自动清理会在开关翻转时销毁有效配置同名用户 Agent 会完全遮蔽内置 Agent如果你手写了一个name: Explore的用户 Agent它会把内置的Explore完全盖住此时调整内置的模型不会产生任何效果——弹窗里会提示这一点对应 AgentManager.tsx 中overrideShadowed警告逻辑策略限制当组织策略strictPluginOnlyCustomization包含agents时用户级与项目级覆盖在解析阶段即被忽略只有 managed 来源生效生效时机与 Agent Markdown 文件一样手工改 settings.json 不会自动作用于已在运行的会话桌面端保存时会触发一次会话重载手工改文件则需要重启会话或执行/reload-plugins。模型与 Provider 的绑定关系Agent 配置里保存的是模型 ID而不是 Provider。模型选择器列出的是当前 Provider 的可用模型以后如果切换 Provider别名Haiku / Sonnet / Opus / Fable会按新 Provider 的映射重新解析完整模型 ID则要求新 Provider 也支持该模型否则不可用。创建自己的 Agent点击「设置 → Agents」右上角的Create Agent按钮打开创建弹窗AgentFormModal。各字段说明如下配置范围Scope—— 用户还是项目。选「项目」时需确认目标项目路径弹窗内提供目录选择器DirectoryPicker仅创建模式可选编辑模式下 Scope 被禁用。用户范围写入~/.claude/agents/项目范围写入目标项目的.claude/agents/名称Name—— 1–64 位小写字母、数字、连字符或下划线。这是主 Agent 调用它时使用的名字。源码中校验正则见 NAME_PATTERN/^a-z0-9?$/即必须以字母或数字开头和结尾中间可含连字符与下划线例如code-reviewer描述Description—— 说明主 Agent 应该在什么场景下委派给它。这是最重要的字段主 Agent 正是靠它来决定要不要调用这个 Agent。写得太含糊这个 Agent 就永远不会被叫到。创建/编辑时该字段为必填descriptionRequired校验见 handleSubmit系统提示词System prompt—— 定义职责、边界和预期输出。创建模式下必填模型Model—— 继承主 Agent或选择 Haiku / Sonnet / Opus / Fable 别名或选择当前 Provider 已配置的模型。简单重复的活交给 Haiku 更快更省推理强度Effort—— 继承或指定 low / medium / high / xhigh / max。模型不支持某档时会自动降级或忽略该字段工具Tools—— 三选一全部工具inherit、不允许使用工具none、自定义列表custom。自定义模式下内置工具按「读取与搜索 / 修改文件 / 执行命令 / 工作流」四类分组勾选分组元数据见 TOOL_METADATA 与 ToolPicker下方还有一个自由输入框用于填写 MCP 工具名或形如Bash(git:*)的权限规则自由输入框的解析器 parseTools 专门处理了括号配对因此带参权限规则可以安全地包含空格与逗号颜色Color—— 可选仅用于在界面上区分不同 Agent。可选色板见 AGENT_COLORS共 9 种red / orange / yellow / green / blue / purple / pink / cyan。最小权限原则文档中的原话提示只给任务必需的工具。一个只负责读代码并汇报结论的 Agent不需要 Write 和 Bash——权限收窄了它跑偏的空间也就小了。保存与热重载行为保存操作会把配置写成 Markdown 文件到对应目录并尝试刷新当前会话。刷新失败不会回滚已经写好的文件——重启后定义仍然生效。桌面端的完整行为链在 agentStore.ts 中可见增/改/删/覆盖都会走runAgentMutationagentStore.ts先调用 agentsApi 的create/update/delete/setOverride/clearOverride接口再list全量刷新注释明确覆盖关系跨来源计算只有全量列表才一致随后通过POST /api/agents/reloadagentsApi.reload超时 120 秒热重载运行中的会话若会话未运行或重载失败会返回not_running/failed原因界面顶部出现不阻塞操作的警告条mutationWarning 重试按钮见 AgentManager.tsx。Agent 文件的格式与来源优先级标准 Markdown 定义格式在用户或项目的agents目录下创建.md文件即可定义 Agentfrontmatter 示例来自 Agent 系统原理--- name: code-reviewer description: 专业代码审查代理 tools: - Read - Grep - Glob - Bash model: sonnet effort: high permissionMode: dontAsk maxTurns: 10 --- 你是一个专业的代码审查员。请检查以下方面 1. 代码质量和可读性 2. 潜在的安全漏洞 3. 性能问题 4. 最佳实践遵循可配置字段一览字段类型说明namestringAgent 类型名称descriptionstring何时使用的说明toolsstring[]允许的工具列表[*]表示全部disallowedToolsstring[]禁止的工具列表modelstring使用的模型fable/opus/sonnet/haiku、完整模型 ID 或inheriteffortstring推理强度low/medium/high/xhigh/max以模型能力为准permissionModestring权限模式maxTurnsnumber最大对话轮数mcpServersobject[]需要的 MCP 服务器hooksobjectAgent 特定的钩子colorstringAgent 的界面标识颜色skillsstring[]可使用的技能memorystring记忆作用域user / project / localisolationstring隔离模式worktree / remotebackgroundboolean是否默认后台运行继承的写法想继承当前会话最清楚的做法是省略对应字段——不写model就继承主会话模型不写effort就继承当前会话的推理强度。model: inherit是模型字段的等价显式写法effort没有inherit值。另外需注意Agent工具的单次调用没有effort参数因此 effort 应在 Agent 定义或会话层设置整数形式的effort仅为既有 SDK/JSON 兼容而保留桌面端 Agent 管理器只写入上述五个命名档位。同名 Agent 的来源优先级多个来源定义同名 Agent 时实际生效的定义按以下优先级选择从高到低见 Agent 系统原理策略 Agentpolicy—— 组织托管策略CLI 参数 Agentflag—— 通过--agents注册项目 Agentproject—— 项目目录的.claude/agents/用户 Agentuser——~/.claude/agents/插件 Agentplugin—— 由插件提供内置 Agentbuilt-in—— 系统预定义。桌面端列表会展示被覆盖的定义及其来源但真正 spawn 时使用的是优先级最高的活动定义。模型与推理强度的解析优先级模型从高到低CLAUDE_CODE_SUBAGENT_MODEL的具体模型值设为inherit时不锁定模型本次Agent({ ..., model: ... })调用指定的模型Agent Markdown frontmatter 中的modelsettings.json 中builtInAgentOverrides指定的model仅内置 Agent主会话模型。推理强度从高到低CLAUDE_CODE_EFFORT_LEVELAgent Markdown frontmatter 中的effortsettings.json 中builtInAgentOverrides指定的effort仅内置 Agent当前会话的 effort模型默认值。low、medium、high、xhigh、max是否可用取决于解析后的真实模型及提供商能力Claude 模型会向下回退到可用档位其他提供商按各自的模型目录规范化不支持 effort 的模型不会应用该字段。子 Agent 通常继承主会话的扩展思考extended thinking开关但解析后的模型强制要求优先例如 Fable 5 会规范化为 adaptive thinking。权限模式参考每个 Agent 可设置的权限模式permissionMode模式说明default正常权限请求需要用户确认plan所有操作需要显式审批acceptEdits自动接受文件编辑其他操作需确认bypassPermissions跳过所有权限检查dontAsk拒绝所有未预批准的操作autoAI 驱动的权限分类仅 Ant 内部bubble权限提示冒泡到父 Agent 终端快速参考操作方法浏览/管理已安装 Agent桌面端设置 → AgentsAgentManager.tsx查看 Agent 详情点击列表行查看模型、effort、工具范围与系统提示词调整内置 Agent行内「调整模型」或详情页同名按钮写入~/.claude/settings.json的builtInAgentOverrides恢复内置默认弹窗内「Reset to built-in default」删除整条覆盖记录创建自定义 Agent「Create Agent」弹窗保存为~/.claude/agents/*.md或项目目录/.claude/agents/*.md手工定义 Agent编写带 frontmatter 的 Markdown 文件放入对应 agents 目录热点重载桌面端保存后自动刷新会话刷新失败不阻塞重启后生效本文所有 UI 行为均可在 AgentManager.tsx 及其配套的 agentStore.ts、agents.ts 中找到对应实现与测试如 AgentManager.test.tsx、agentStore.test.ts可继续深入阅读验证。【免费下载链接】cc-hahaLocal-first cross-platform desktop workspace for Claude Code / agents: multi-agent, Git worktrees, code diffs, skill marketplace, multi-model, Computer Use, task-aware desktop pets, with WeChat, Feishu, DingTalk, Telegram, WhatsApp and H5 access.项目地址: https://gitcode.com/gh_mirrors/cl/cc-haha创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考