第 10 章 · 03 subagents 配置、环境变量与故障排查

第 10 章 · 03 subagents 配置、环境变量与故障排查

本节摘要:收尾三件事:自定义子代理——--agents 标志用 JSON 即席定义会话级子代理,与文件级定义三级优先级;关键环境变量分组速查——认证、禁用开关、限额防护、遥测调试;最后是故障排查四问,覆盖"命令找不到/认证失败/会话找不到/JSON 损坏"四大高频故障。学完本节,你具备独立部署与排障的完整能力。

学习目标

1. 说出 --agents JSON 的必填/选填字段与三级加载优先级。
2. 说出至少 6 个关键环境变量的作用。
3. 说出 Agent View 的用途与 claude agents 的派发标志。
4. 按"四问"流程排查命令行高频故障。

一、--agents:即席自定义子代理

第 4 章的 .claude/agents 是文件级定义;--agents 标志则把定义直接塞进命令,会话即用即弃:

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}
​

字段规则:description 与 prompt 必填,tools 省略则继承全部工具,model 可选(sonnet/opus/haiku)。

完整示例——三个分工明确的专家代理:

{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.",
    "tools": ["Read", "Edit", "Bash", "Grep"],
    "model": "opus"
  },
  "documenter": {
    "description": "Documentation specialist for generating guides.",
    "prompt": "You are a technical writer. Create clear, comprehensive documentation.",
    "tools": ["Read", "Write"],
    "model": "haiku"
  }
}
​

三种用法:

# 内联定义
claude --agents '{"security-auditor": {"description": "Security specialist for vulnerability analysis", "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.", "tools": ["Read", "Grep", "Glob"], "model": "opus"}}' "audit this codebase"

# 从文件加载(团队共享)
claude --agents "$(cat ~/.claude/agents.json)" "review the auth module"

# 与其他标志组合
claude -p --agents "$(cat agents.json)" --model sonnet "analyze performance"
​

加载优先级

同一名字的代理出现在多个位置时,按此覆盖:

CLI 定义 > 项目级 > 用户级,名字冲突时高优先级胜出。

二、关键环境变量分组速查

认证与模型

功能禁用开关(排查/裁剪环境用)

限额与防护

调试与遥测

三、settings.json 常用键

{
  "wheelScrollAccelerationEnabled": false,
  "language": "french",
  "footerLinksRegexes": ["https://jira\\.example\\.com/.*"]
}
​

四、故障排查四问

问 1:命令找不到?

# 安装
npm install -g @anthropic-ai/claude-code

# 检查 PATH 是否含 npm 全局 bin 目录
# 或直接用完整路径兜底
npx claude
​

代理/内网环境:确认 downloads.claude.ai 已加入出口白名单(v2.1.113+ 原生二进制分发后必查)。

问 2:认证失败?

• export ANTHROPIC_API_KEY=your-key,确认密钥有效且有额度。
• 确认密钥权限覆盖所请求的模型。
• claude auth status 检查登录态(登录成功退出 0)。

问 3:会话找不到?

• 先列会话找对名称/ID(claude agents 或 -c 接最近会话)。
• 会话可能因长期不活跃过期。
• -c 只接最近一次;定向恢复用 -r "会话名"。

问 4:JSON 输出损坏?

• 用 --json-schema 强制结构。
• 提示中写明字段名与含义。
• 确认用的是 --output-format json,而不是只在提示里说"给我 JSON"。

终极隔离大法

任何诡异行为(插件冲突/Hooks 作祟/MCP 报错),先 claude --safe-mode 启动——全部定制关闭后症状消失,则逐个恢复定制项定位元凶;/doctor 可自动诊断并一键修复(f 键)。

小结

• --agents:description/prompt 必填、tools/model 选填;CLI > 项目 > 用户三级覆盖。
• 环境变量四组:认证模型、禁用开关、限额防护、调试遥测,各取所需。
• 排障四问:命令→认证→会话→JSON,层层递进;--safe-mode + /doctor 终极兜底。

下一节预告:第 10 章结束,整个教程到站。回到总纲,按"阅读建议"规划你的回炉路线。