企业官网建设流程全解析

1. 先搞清楚：Agent Team 并不是一个开关按钮

1.1 大家都在说的 Agent Team 到底指什么

最近后台一直有人问起 Claude Code 里的 Agent Team 配置，我猜是被“Agent Team”这个名字误导了。实际上，在 Claude Code 里你找不到一个叫“Agent Team”的设置项或开关，它更像是一套基于子代理（subagents）机制组合出来的团队协作工作流。你可以把每一个 subagent 理解成一个有独立系统提示、独立工具权限和独立目录权限的“虚拟同事”，它们共享同一个项目上下文，却各自负责不同的专业领域，比如架构设计、代码实现、测试补全、代码审查。多个 subagent 还可以被并行调用，互相配合完成一个大任务，这就是所谓的 Agent Team。

我在实际项目里第一次用这个功能时，最大的感受是它比“让一个 Agent 从头写到尾”要稳得多。单一 Agent 面对一个跨模块的需求时，经常会出现“前后矛盾”或者“改了这个忘了那个”的情况。而团队模式下，每个角色只关注自己职责范围内的事，改代码的专心改代码，测试的专心补测试，审查的只挑毛病，任务边界清楚了，上下文干扰就少了。这就像真实项目里你不会让一个人既写业务代码又做安全审计，虽然理论上他能干，但做出来的东西往往两头都不够深入。

1.2 官方内置模式与自定义 Agent Team 的关系

除了你自己定义的 subagents，Claude Code 还内置了几种工作模式，最常用的是 plan 和 help。plan 模式会让模型先做分析和规划，不写代码，适合在动手前先确认思路；help 模式则是让人工介入，逐条确认下一步操作。很多人误以为 plan 模式就是 Agent Team，其实不是，plan 更像是一个“分工前的前置流程”。一个成熟的 Agent Team 工作流，通常会先让 plan 模式做个全局规划，再根据规划去调不同职能的 subagent。

自定义 Agent Team 的关键文件有三个：项目根目录的 CLAUDE.md、.claude/agents/ 目录下的 subagent 定义文件、.claude/commands/ 目录下的自定义斜杠命令。CLAUDE.md 相当于团队章程，负责声明项目约定，比如技术栈、代码风格、禁止修改哪些目录；agents 目录负责定义每个角色的能力和边界；commands 目录则提供快捷入口，让你用 /team、/review 这样的命令一键启动整条流程。这套三层结构设计得很像现实中的团队制度，理解清楚之后配置起来也就顺了。

2. 环境准备与安装：三种系统一条路走通

2.1 安装前需要确认的底层环境

在动手装 Claude Code 之前，我建议先把基础环境确认一遍，否则后面各种报错会让人崩溃。Claude Code 本质上是基于 Node.js 的命令行工具，全局依赖 npm 安装，所以首先得有 Node.js 环境。官方对版本的要求是 18 以上，但我实测下来建议直接装最新的 LTS 版本，也就是 20 或者 22 之间的稳定版，因为某些第三方模型接入插件对 Node 版本还是挺敏感的。检查环境的命令很简单：

node -v npm -v

如果能正常输出版本号，说明 Node 基础环境没问题。Windows 上有个特别容易踩的坑：如果系统是 32 位的，或者 Node 是 32 位版本，安装时会出现“由于与64位版本的Windows不兼容”这类报错。解决办法不是去硬试，而是先去 Node 官网下载 64 位安装包重新装一遍，装完再回到终端确认版本。Linux 上其实最省心，只要记得不要在 root 用户下直接全局安装，建议用普通用户配合 sudo 权限，避免后面出现目录权限冲突。

2.2 安装命令与三种入口选择

环境准备好之后，安装本身倒没什么特别。打开终端执行这一条命令：

npm install -g @anthropic-ai/claude-code

装完验证一下版本，claude --version能看到输出就说明核心安装成功了。如果之前装过旧版本，可以用同一条命令重新执行，npm 会自动升级到最新版。接下来就是选择入口，我用过的有三种：终端原生环境、VS Code 插件、桌面版。

终端原生环境适合重度用户，直接在项目目录下敲 claude 就能进入交互界面，所有快捷键和命令都最完整。VS Code 插件适合边看代码边对话的人，安装后可以在侧边栏打开 Claude Code 面板，还能把对话内容和当前打开的编辑器选区联动起来，看代码时顺手提问题特别方便。桌面版则是在独立窗口里运行，适合不想开终端也不想开编辑器的时候用，界面相对友好一些。我的建议是先用终端原生环境跑通核心功能，再按习惯决定要不要装插件或桌面版，因为后面配置 Agent Team 时很多命令示例都是基于终端给出的。

2.3 关于登录账号与不登录账号的区别

不少新手卡在登录这一步。如果用官方 Anthropic 账号登录，可以通过绑定的方式获得对应订阅权限，这是最省事的方式，但偶尔会遇到企业账号或团队订阅拦截，报错信息类似“your organization has disabled claude subscription access for claude code”。这种情况其实不是配置错误，而是组织策略限制，优先去找管理员开通，或者干脆改用个人账号。个人账号登录后，订阅权限直接在账号里生效，不用额外配环境变量。

不登录账号能不能用？也能。如果你有第三方模型的 API Key，比如 DeepSeek、通义千问、GLM，完全可以走环境变量的方式接入。只要设置好 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，Claude Code 启动时就会走第三方模型的 Anthropic 兼容接口，完全不用登录官方账号。我在后文接入第三方模型的部分会详细说一套通过 cc-switch 切换的方案，那个方式比手动改环境变量方便得多。注册账号和不注册最大的区别就在这里：注册走官方身份认证和订阅体系，不注册走纯 API 通道，两者面对的模型渠道完全不同。

3. 搭建你的第一个 Agent Team：角色、章程与快捷命令

3.1 用 subagents 定义团队角色

要建 Agent Team，第一步是在项目根目录创建.claude/agents/文件夹，然后为每个角色写一个 Markdown 文件。文件名会成为该角色在团队中的名字，所以我建议用连字符命名，比如code-reviewer.md、tester.md。文件的基本结构由头部字段和正文组成，下面是我常用的一个代码审查 Agent 定义：

--- name: code-reviewer description: 负责代码审查与质量把关，适合在提交合并前执行 tools: Read, Grep, Glob, Bash model: sonnet --- 你是一个资深代码审查员。审查代码时请关注以下维度： 1. 是否存在逻辑错误或边界条件遗漏 2. 是否引入安全性问题，如注入、越权、敏感信息泄露 3. 是否符合项目 CLAUDE.md 中约定的代码规范 4. 是否缺少必要的异常处理 输出格式： - 问题列表（P0/P1/P2 分级） - 修改建议 - 确认可以合入的结论

头部字段里我特别强调几个关键项：description决定这个 Agent 什么时候会被自动调度，描述写得越具体，主 Agent 在规划时越容易把它喊出来；tools决定它能碰哪些工具，我习惯先收紧权限，只给 Read、Grep、Glob、Bash 这些最基础的，等遇到确实需要扩权的场景再放开；model可以单独指定模型，比如把审查 Agent 切到更强的模型，把简单的测试 Agent 用轻量模型，这样成本和效果都能兼顾。

再举一个测试 Agent 的例子，定义文件可以这样写：

--- name: tester description: 负责编写和运行单元测试，适合在功能实现完成后调用 tools: Read, Write, Bash model: haiku --- 你是一个严谨的测试工程师。接到任务后： 1. 先阅读相关模块的源代码，梳理核心函数 2. 设计覆盖正常路径和边界条件的测试用例 3. 使用项目的测试框架运行并修正失败项 4. 输出测试覆盖率报告和剩余风险点

3.2 用 CLAUDE.md 固定团队工作协议

光有角色还不够，Agent Team 必须有一套公共规则，否则每个 Agent 各说各话，团队协同就是灾难。这套规则放在项目根目录的 CLAUDE.md 里，每次对话开始后 Claude Code 会自动读取它，相当于给所有 Agent 看的“项目入职手册”。

写 CLAUDE.md 时我总结了三个原则。第一是声明边界，明确哪些目录不允许改动，比如 build、dist、node_modules，避免测试 Agent 顺手改了编译产物。第二是写明技术栈和命令约定，比如构建命令是 npm run build 还是 pnpm build，测试命令是什么，这样任何 Agent 想执行操作时不会靠猜。第三是描述代码风格偏好，比如缩进规范、命名习惯、禁止使用 any 类型等。项目足够复杂时，还可以把 CLAUDE.md 里的通用规则拆到.claude/目录下的子文档，再通过 @file 的方式引用，保持主文档短小精悍。

有一个细节需要特别留意：CLAUDE.md 中的规则对所有 Agent 生效，所以你写的每一条都会直接影响最终产出。我见过有同事写了条“禁止输出任何解释”，结果所有 Agent 都变成了沉默的改代码机器，发现问题时根本不知道它为什么这么改。规则文字写清楚、给足上下文，比单纯下禁令重要得多。下面是一个简化版 CLAUDE.md 示例：

# 项目约定 - 技术栈：Python 3.11 + FastAPI + PostgreSQL - 测试命令：pytest tests/ -v - 禁止修改目录：build/, dist/, migrations/versions/ - 代码风格：使用 ruff 默认规则，类型注解必须完整 - 对外交互：所有用户输入必须先做长度校验

3.3 用 slash commands 提供团队入口

角色定义好了，规则也落地了，最后一步是给团队加一些“一键呼叫”的快捷方式。在.claude/commands/目录下，你可以为常用的流程创建命令文件，比如/team用来启动一次完整的团队协作，/review用来让审查 Agent 单独开工。

我举个例子，创建一个.claude/commands/team.md，内容可以这样：

该命令用于启动一次完整的 Agent Team 协作。 执行流程： 1. 先读取项目根目录的 CLAUDE.md，理解项目约定。 2. 调用 code-reviewer 对当前分支进行差异检查。 3. 如果存在问题，调用 developer 修复。 4. 修复完成后调用 tester 运行并补充测试。 5. 最后由 code-reviewer 复检并输出合入建议。

这样一个命令就把原本需要多次手动切换的流程串起来了。命令文件里还可以写$ARGUMENTS之类的占位符来接收用户输入，比如/team 修复登录模块的会话过期问题，后面的描述会被当作本次任务的额外目标传给流程。到这一步，你的 Agent Team 已经有了角色、制度和入口，算是真正从零配出来了。

4. 实战：用 Agent Team 改造一个遗留项目

4.1 一个真实的改造案例

下面分享一下我实际跑过的一个流程，方便你看清 Agent Team 怎么配合。当时手里的项目是一个老旧的订单管理系统，模块之间耦合很重，连测试都没有。我的目标是在不动整体架构的前提下，修掉一个会话超时导致用户跳回登录页的问题，并补上关键路径的单元测试。

我先启动 claude 进入项目，然后在对话里执行创建目录、写 CLAUDE.md、写 subagent 定义这些动作。这一步不需要手工敲文件，直接告诉主 Agent：“在 .claude/agents/ 下创建 developer、tester、code-reviewer 三个角色的定义，写入到对应文件”，它会读项目结构后直接生成，我再手工微调。这里建议一定要人工过一遍生成出来的定义，因为自动生成的 description 往往太宽泛，比如只会写“擅长写代码”，没有说明具体场景，后面主 Agent 调度时就不容易精准匹配。

4.2 团队协作的完整调用顺序

一切就绪后，我首先让 plan 模式做分析，不要直接动代码。我把需求描述成：“分析订单管理系统中用户会话超时后跳转逻辑的实现位置，评估修改影响范围，给出分步实施方案。”这一步的输出会变成一个很好的任务拆解，我再把它贴进后续的 Agent 调用里。plan 模式的好处是只动脑不动手，产出规划文档后还会征求我意见，确认没问题再继续。

接着我调用 developer Agent 实施修复，指令里除了描述问题，还特意补充了“只能修改 src/modules/session 目录下的文件”这个边界条件。这里就体现出 subagents 权限的价值：我给了 developer 读写 src 目录的权限，但通过 CLAUDE.md 约束它不要动其他模块，它执行的每一步我都看得到，遇到要改超出权限的文件时系统会明确暂停等待确认。修复完成后，我紧接着调 tester Agent 补测试。tester 会自动扫描 src/modules/session 下的函数，生成测试用例，并在 /tmp 目录下跑测试验证。

最后一步让 code-reviewer 对整个 diff 做审查。整个过程大概花了不到二十分钟，其中大部分时间花在等待模型推理上。最终结果是改动控制在三个文件以内，新增测试覆盖率达到核心路径的八成以上，reviewer 挑出了两个我确实没注意到的边界情况。这个案例让我确信，Agent Team 的价值不在于“多 Agent 同时干活”，而在于职责拆分让每个环节的上下文都很干净，每个模型都只处理自己最擅长的那一小块。

4.3 让多个 Agent 协作的三个关键技巧

第一次上手 Agent Team 时，我踩了不少坑，这里整理三个最关键的经验。

第一，上下文隔离要做得足够细。多个 Agent 即使可以并行，也不代表它们应该共享所有项目内容。每次调用子代理时，最好在指令里明确“你只需要关注某目录或某模块”，再配合 subagent 自身的 tools 权限，双重隔离。第二，尽量把复杂任务的最终验收交给审查类 Agent，而不是写代码的 Agent 自己确认。人写代码容易陷入“自己觉得没问题”的惯性，模型也一样。第三，不要期望一次调通，Agent Team 和真实团队一样需要迭代。第一次跑出来的结果很可能不满足要求，这时候不要推翻重来，而是把上一次输出的审查意见作为输入再次调用，几次之后效果会明显稳下来。

5. 第三方模型接入：用 cc-switch 自由切换 DeepSeek、Qwen、GLM

5.1 为什么需要 cc-switch 这样的配置工具

官方账号毕竟有额度限制，而且很多团队会有成本控制要求，所以接入第三方模型就成了很现实的需求。市面上的方案不少，手动改环境变量是最直接的，但一旦需要在多个模型之间切换，手动操作很容易出错。我之前就多次因为忘了改 ANTHROPIC_BASE_URL 导致请求全部打错服务，排查起来非常耗时，尤其是同时接了多个项目的时候。

cc-switch 这类工具解决的就是这个痛点。它的作用是把不同模型的供应商配置（接口地址、密钥、模型名等）集中起来管理，通过简单的菜单选择或快捷键就能切换当前生效的配置，不用每次去翻环境变量文件。社区里用的人不少，对 DeepSeek、Qwen、GLM 这些主流模型的支持也比较成熟，适合用来搭一个低成本又灵活的 Claude Code 开发环境。本质上它就是个配置管家，省去的是频繁改环境变量带来的低级错误。

5.2 配置步骤与验证方法

用 cc-switch 接入第三方模型的步骤大致是这样的：先安装好 cc-switch，这通常是一个命令行工具，通过包管理器安装即可；然后在它的配置文件中添加供应商，需要准备 Base URL 和 API Key 两个关键信息。以 DeepSeek 为例，它的 Anthropic 兼容接口地址通常在官方文档里能查到，格式一般是https://api.deepseek.com/anthropic这样。把该地址填入 Base URL，再把账号对应的密钥填入 API Key，保存后选择这套配置生效。

配置完成后不要急着直接跑完整项目，先在终端里执行一个最简单的对话验证一下。启动 claude 后随便问一句“用一句话介绍你自己”，如果能正常返回说明通道已经通了。这里有个实用的小经验：很多第三方模型对“你是不是 Claude”这个问题会回答得和官方模型完全不同，这完全正常，因为底层的系统提示和模型本身都不一样，只要工具调用和代码能力正常就行，不用为了这个问题纠结。如果响应时报认证错误，优先检查 API Key 是否填错或过期。

5.3 第三方模型下 Agent Team 的表现差异

换到第三方模型之后，Agent Team 的表现会有比较明显的变化。最核心的影响因子是模型的工具调用能力，也就是它是否能稳定地决定“调用哪个工具、传什么参数”。工具调用能力弱的模型在跑 Agent Team 时经常会卡在怎么读文件、怎么执行命令这些环节，表现就是任务响应变慢甚至中断，看起来像死机一样。

所以我选模型时有个固定标准：先看它是否适配 Anthropic 的 tool use 协议，再看上下文窗口能否覆盖项目的多个关键文件。DeepSeek 的新版模型在这方面口碑不错，价格也便宜；Qwen 和 GLM 的性能也在快速接近，但不同版本差异较大，建议动手前先查一下具体版本的兼容说明。需要提醒的是，第三方模型跑出的代码质量大概率不如官方旗舰模型，用它搭 Agent Team 更适合做原型验证、批量重构和自动化测试，别在关键系统上盲目依赖。这套配置方案适合开发环境和个人学习，生产环境请自行评估风险。

6. 常见报错与排查技巧实录

6.1 安装与启动阶段的报错处理

我整理过一份安装使用 Claude Code 的排障清单，先挑几个高频问题说。第一个是安装时提示“your organization has disabled claude subscription access for claude code”，这个具体场景我在安装部分提过，本质是订阅策略限制，换用个人账号或改用第三方 API 配置就能绕开。第二个是 Windows 下安装时报“与64位版本的Windows不兼容”，确认系统是 64 位的，然后卸载 32 位 Node，重新安装 64 位版本，再清理一下 npm 缓存，通常就装上了。

还有一个容易被忽略的问题：某些终端软件在 Windows 上默认用的是 PowerShell 而不是 CMD，部分 npm 脚本的执行路径会不一致导致报错。我会提前把终端换成 Windows Terminal，并确认 PATH 中已经加入了 Node 的安装目录。Linux 下如果遇到 permission denied，多半是全局安装目录权限不够，用 sudo 安装或者配置 npm 的 prefix 到用户目录都能解决。如果你在安装过程中遇到其他没列出来的报错，最有效的办法不是搜博客，而是先看完整报错信息里提到的文件路径和行号，再针对性查官方文档。

6.2 权限与命令执行问题

Claude Code 能直接执行终端命令，这对效率提升帮助非常大，但也带来了权限疑问。默认情况下，它会先展示将要执行的命令，等用户确认后才运行；如果你不想每次都被打断，可以在设置里调整自动执行策略，让高频的安全命令直接放行。但我的建议是，对于删除、覆盖文件这类高风险命令，保留确认机制，因为模型一旦判断失误，批量操作造成的损失是没法轻易回滚的。

如果遇到“命令执行被拒绝”或者“工具调用失败”，优先检查两件事：一是当前目录是否有写权限，二是 subagent 定义里是否明确了所需工具的权限。尤其是在自定义团队里，一个角色拿不到 Bash 工具时，很多自动化操作根本走不通。把 tools 字段从 Read, Grep, Glob 扩成 Read, Grep, Glob, Bash 之后，问题通常立刻消失。权限这块的思路就是“最小够用”，不要害怕少给权限，窄权限范围反而能避免很多误操作。

6.3 连接本地模型与常见配置疑问

热词里还有一类高频问题：Claude Code 能不能直接调用 LM Studio 之类的本地模型？答案是能，原理和接第三方云端 API 一样，只要在 LM Studio 里开一个兼容 Anthropic 格式的本地服务端口，然后把 ANTHROPIC_BASE_URL 指向 localhost 对应的端口就行。本地模型的优势是完全免费、数据不出内网，缺点是速度慢、推理能力相对有限，跑 Agent Team 里的复杂任务时会比较吃力，做点代码补全和短对话倒是够用。如果你有 NVIDIA 显卡，配置得当的话速度会好一些，但整体依然不如商业 API。

关于飞书这类办公软件怎么连接 Claude Code，常见做法是通过 hook 机制在事件发生时发送通知。Claude Code 支持在配置文件里声明 hooks，当 Agent 执行到特定节点时可以往群机器人的回调地址发消息，这样你人不在电脑前也能知道任务进度。思路是利用 hooks 里的 PostToolUse 事件，把关键信息 POST 到群机器人的 webhook 地址，配置上并不复杂。核心伪代码如下：

# 在 hooks 配置中写入： PostToolUse: - matcher: "Bash" hooks: - type: command command: "curl -X POST -H 'Content-Type: application/json' -d '{\"msg_type\":\"text\",\"content\":{\"text\":\"执行了命令\"}}' 你的群机器人地址"

6.4 排查问题速查表

这里再补一句个人建议：把排查清单打出来放在手边，大部分报错都是配置问题而不是工具 bug。多试几次改配置，少怀疑机器，经验就是慢慢攒出来的。