我们都知道，写 prompt 是一门手艺活。同一个 Claude 模型，让它「帮我写个 React 组件」和「以资深前端工程师视角，遵循 WCAG 2.1 AA 规范，使用 TypeScript + React 18 写一个可访问的虚拟滚动表格」得到的输出质量天差地别。
Agency Agents 正是为了解决这个痛点出现的——它把 16 个部门、100+ 个 AI 专家角色（Frontend Developer、Backend Architect、Security Auditor、Reddit Community Ninja……）的人设、流程、交付物、衡量指标都编排好了，我们只需要激活对应角色，AI 就会自动进入「专业模式」。
更友好的是，仓库自带 convert.sh 和 install.sh，可以一键把同一份角色定义同步到 Claude Code、OpenClaw、Cursor、OpenCode、Codex、Gemini CLI 等 10+ 种工具，不需要维护多份配置。
这篇文章，我们就一起来从零把它跑起来，并演示如何在 OpenClaw 中激活一个角色去完成真实需求。
项目简介
msitarzewski/agency-agents 起源于一个 Reddit 帖子里「如果你能雇佣一个 AI 员工团队，你会要哪些岗位？」的讨论，经过几个月的迭代，已经演变成一个相当完整的 AI 代理角色库：
- 16 个部门：engineering、design、marketing、finance、security、sales、testing……几乎覆盖了一个软件公司需要的所有岗位
- 100+ 个角色：从 Frontend Developer、Backend Architect，到 Whimsy Injector、Reality Checker 这种有「人设温度」的角色
- 可度量交付物：每个角色都标注了 success metrics、deliverables、critical rules，不是空泛的 prompt
- 多工具通用：同一份 Markdown 源文件，可转换成 Claude Code subagent、OpenClaw workspace、Cursor rule、OpenCode agent、Codex TOML 等格式
和普通 prompt 模板最大的区别是：这里每个角色有完整的人格化设定（语气、风格、记忆机制）+ 业务流程（mission / workflow / deliverables），更接近「一份岗位说明书」。
难度 / 时长 / 收获
- 难度：⭐⭐（会用命令行即可，无任何代码门槛）
- 时长：15-30 分钟（首次安装 + 激活一个角色 + 跑通一个真实需求）
- 收获：把 Claude Code / OpenClaw 变成「按需调度」的多角色 AI 团队，长期保持专业人设稳定
目标读者画像
- 想用 AI 提效、但嫌写 prompt 太繁琐的开发者
- 1-5 年经验的前端 / 后端 / 全栈 / 安全 / 测试工程师
- 已经在使用 Claude Code、Cursor、OpenClaw、Codex 等 AI 编程工具的实践者
- 想在团队内推行「AI 协作规范」的技术 Lead
核心依赖与环境
| 工具 | 最低版本 | 说明 |
|---|---|---|
| Git | 2.30+ | 克隆仓库 |
| Bash | 4.0+ | 运行 convert.sh / install.sh（Windows 需 Git Bash 或 WSL） |
| Node.js | 18+ | 部分目标工具（OpenClaw、Codex）需要 |
| 目标 IDE / CLI | 最新版 | Claude Code、OpenClaw、Cursor、OpenCode 任选其一即可 |
TIP
如果你已经在用 OpenClaw（一个统一调度多种大模型的 CLI 网关），整篇文章可以做到零成本跑通。
TIP
关于调用成本：Agency Agents 的每个专家角色背后跑的都是顶级模型（Claude Opus 4.8、GPT-5.4、Gemini 2.5 Pro），激活 1 个角色跑 20 轮 React 组件迭代，官方便宜的也要十几块。如果你希望用 官方半价 跑同样的模型，可以试试 Defapi——一个 LLM API 中转平台。它的优势在于基本所有模型都兼容 v1/chat/completions、v1/messages、v1beta/models/ 三套协议，意味着不需要改任何业务代码，把 OpenClaw 配置里的 base_url 指向 Defapi 端点就能立刻省钱，对个人开发者和小团队非常友好。官网入口：defapi.org。
完整项目结构树
agency-agents/
├── academic/ # 学术研究方向
├── design/ # UI/UX 设计
├── engineering/ # 研发（最大的部门，30+ 角色）
├── finance/ # 财务
├── game-development/ # 游戏开发
├── gis/ # 地理信息
├── marketing/ # 市场营销
├── paid-media/ # 付费投放
├── product/ # 产品
├── project-management/ # 项目管理
├── sales/ # 销售
├── security/ # 安全
├── spatial-computing/ # 空间计算
├── specialized/ # 特殊专家
├── strategy/ # 战略
├── support/ # 客户支持
├── testing/ # 测试
├── integrations/ # 多工具集成产物
│ ├── openclaw/ # OpenClaw 工作区（SOUL.md + AGENTS.md + IDENTITY.md）
│ ├── opencode/ # OpenCode agent（.md + YAML frontmatter）
│ ├── claude-code/ # Claude Code subagent
│ ├── cursor/ # Cursor rule（.mdc）
│ ├── codex/ # Codex custom agent（TOML）
│ ├── gemini-cli/ # Gemini CLI subagent
│ ├── github-copilot/ # GitHub Copilot
│ ├── aider/ # Aider CONVENTIONS.md
│ ├── windsurf/ # Windsurf .windsurfrules
│ ├── kimi/ # Kimi Code CLI
│ ├── qwen/ # Qwen Code SubAgent
│ └── mcp-memory/ # MCP 长期记忆
├── scripts/
│ ├── convert.sh # 角色定义 → 工具格式转换器
│ ├── install.sh # 一键安装到本地
│ ├── lib.sh # 共用函数
│ └── lint-agents.sh # 角色定义 lint
├── README.md
└── CONTRIBUTING.md
手把手步骤
下面我们以 OpenClaw 为例，演示完整流程。其它工具只需要把 --tool 换成对应名字即可。
步骤 1：克隆仓库
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents
如果网络受限，可以先 fork 到 Gitee / 自己的 GitHub 再 clone：
git clone https://github.com/<your-fork>/agency-agents.git
cd agency-agents
步骤 2：查看可安装的部门和角色
install.sh 提供了一个非常方便的「列清单」模式：
./scripts/install.sh --list teams
你会看到类似这样的输出：
engineering 33 agents
design 12 agents
marketing 18 agents
security 9 agents
testing 11 agents
...
如果只想装某几个部门（比如 engineering + security），后面用 --division 过滤即可。
步骤 3：生成 OpenClaw 格式的集成文件
convert.sh 会把源 Markdown 拆分成 OpenClaw 期望的 SOUL.md（人格）+ AGENTS.md（流程）+ IDENTITY.md（身份）三件套：
./scripts/convert.sh --tool openclaw
执行成功后，integrations/openclaw/ 目录下会多出 100+ 个子目录：
ls integrations/openclaw/ | head -20
# agency-frontend-developer
# agency-backend-architect
# agency-security-auditor
# agency-reddit-community-ninja
# agency-whimsy-injector
# ...
每个子目录里都长这样：
agency-frontend-developer/
├── SOUL.md # 角色人格：身份、记忆、语气、风格
├── AGENTS.md # 业务流程：mission、deliverables、workflow
└── IDENTITY.md # 身份卡：emoji + 名字 + vibe
步骤 4：一键安装到 OpenClaw
# 全量安装（约 100+ 角色）
./scripts/install.sh --tool openclaw
# 推荐：按部门挑选安装（避免一次性塞太多）
./scripts/install.sh --tool openclaw --division engineering,security
脚本会自动把工作区复制到 ~/.openclaw/agency-agents/ 并向 OpenClaw 网关注册。
步骤 5：重启 OpenClaw 网关让新角色生效
WARNING
如果你的 OpenClaw gateway 一直在运行，必须重启才能加载新注册的角色，否则会报「agent not found」。
openclaw gateway restart
步骤 6：在 OpenClaw 中激活 Frontend Developer
openclaw chat --agent agency-frontend-developer
或者在配置文件中把默认 agent 改成
agency-frontend-developer，每次启动 OpenClaw 自动进入该角色。
步骤 7：跑一个真实需求
我们让刚激活的 Frontend Developer 写一个无障碍的虚拟滚动表格组件：
openclaw chat --agent agency-frontend-developer <<'EOF'
帮我用 React 18 + TypeScript 写一个 DataTable 组件，要求：
1. 使用 @tanstack/react-virtual 做虚拟滚动
2. 满足 WCAG 2.1 AA 无障碍规范
3. 单元格支持自定义渲染
4. 行点击事件可配置
5. 给出可直接运行的完整代码
EOF
你会发现，它产出的代码风格非常一致——因为角色定义里已经固化了「WCAG 2.1 AA」「memo 包裹」「Core Web Vitals 优化」这些约束。我们不需要每次在 prompt 里重复这些要求。
步骤 8：跨工具演示（可选）
同一份角色定义，转换到 Cursor 也只需要一行：
./scripts/convert.sh --tool cursor
./scripts/install.sh --tool cursor --agent frontend-developer,backend-architect
TIP
Cursor 模式下角色以 .cursor/rules/<slug>.mdc 形式存在，Cursor 会根据文件 globs 自动按需加载，写 globs: "**/*.tsx" 可以让前端角色只对 TSX 文件生效，避免污染后端文件。
常见问题排查
Q1：install.sh 报 permission denied
通常是 install.sh 没有可执行权限，macOS / Linux 用户：
chmod +x scripts/install.sh scripts/convert.sh scripts/lib.sh
./scripts/install.sh --tool openclaw
Windows 用户如果是 Git Bash 报这个错，先确认仓库是用 git clone 下载的（不要解压 zip），并用 Git Bash 运行脚本。
Q2：OpenClaw 报「agent not found」或「未注册」
99% 的情况是装完角色后没有重启 gateway：
openclaw gateway restart
openclaw agent list | grep frontend-developer
# 看到输出说明注册成功
如果还不行，检查一下 ~/.openclaw/agency-agents/ 目录下是不是真的有 agency-frontend-developer/SOUL.md 这个文件：
ls ~/.openclaw/agency-agents/agency-frontend-developer/
# 应该看到 SOUL.md AGENTS.md IDENTITY.md
Q3：OpenCode 一次装太多角色后只显示前 119 个
这是 OpenCode 上游的一个已知 bug（issue #27988）——运行时只注册约 119 个 subagent，多出来的会被静默丢弃。
解决方案：用 --division 拆分安装，把总角色数控制在 119 以内：
./scripts/install.sh --tool opencode --division engineering
./scripts/install.sh --tool opencode --division marketing --out ~/.opencode-extra/
脚本在检测到数量超过阈值时会主动 warning，你也可以先 dry-run 看看：
./scripts/install.sh --tool opencode --division engineering --dry-run
Q4：角色 frontmatter 缺字段导致 convert 跳过
convert.sh 会跳过没有 name 字段的源文件。如果你自己 fork 了一个角色但发现没出现在 integrations/openclaw/ 目录里：
# 1. 检查源文件 frontmatter
head -10 engineering/your-custom-agent.md
# 2. 至少要包含：
# ---
# name: Your Agent Name
# description: One-line description
# ---
# 3. 重新转换
./scripts/convert.sh --tool openclaw
Q5：Windows 下 bash 脚本换行符报错
如果你是在 Windows 上把脚本从 zip 解压出来的，文件可能是 CRLF 换行符，bash 跑会报 \r: command not found：
# 方案 A：用 git clone 而不是下载 zip
git clone https://github.com/msitarzewski/agency-agents.git
# 方案 B：手动转换换行符（Git Bash）
dos2unix scripts/*.sh
Q6：角色之间人格冲突 / 上下文串台
如果你在一个 session 里先后激活了 Frontend Developer 和 Security Auditor，可能会发现上下文里残留前一个角色的语气。这是因为大多数 CLI 工具的 agent 是「system prompt 级」注入，切换 agent 不会自动清空对话历史。
解决方案：
# 切换 agent 前先开新会话
openclaw chat --new-session --agent agency-security-auditor
或者在 OpenClaw 配置里启用「切换 agent 自动归档旧会话」。
扩展阅读 / 进阶方向
1. 自定义角色模板
engineering/engineering-frontend-developer.md 是一个非常好的范本。试着 fork 后改一份 engineering-frontend-developer-chinese.md：
---
name: 前端工程师（中文版）
description: 擅长 React/Vue、UI 实现、性能优化的前端工程师，输出中文注释
color: cyan
emoji: 🖥️
vibe: 用中文输出，遵循字节跳动前端规范
---
# 前端工程师（中文版）
你是**前端工程师**，专注现代 Web 技术……
## 🧠 你的身份与记忆
- 角色：现代 Web 应用与 UI 实现专家
- 性格：注重细节、性能敏感、用户为先
- 记忆：记住常见 UI 模式与无障碍最佳实践
然后跑 ./scripts/convert.sh --tool openclaw，新角色就会出现在 integrations/openclaw/ 里。
2. 用 MCP-Memory 给角色加长期记忆
integrations/mcp-memory/ 目录下提供了一套 MCP memory server 的配置，激活后角色可以跨 session 保留偏好（例如「这个团队喜欢用 pnpm 而不是 npm」）。配置方法见仓库内的 mcp-memory/README.md。
3. 多智能体协作工作流
单角色已经很强大了，但更刺激的是把它们编排成协作链。例如：
需求 → [Product Manager] 拆分任务
→ [Frontend Developer] + [Backend Architect] 并行实现
→ [Code Reviewer] 自动审核
→ [QA Test Engineer] 跑测试
→ [Technical Writer] 生成 PR 描述
OpenClaw 内置的「workflow」功能可以串起这些角色，详见 OpenClaw 官方文档。
4. 降低调用成本
前文提过，Agency Agents 的专家角色背后都是顶级模型，长期跑下来成本不低。想用官方半价跑同样的模型，可以直接接入 Defapi（前面「核心依赖」一节有详细说明），零代码改动。
本文基于 msitarzewski/agency-agents 当前 main 分支撰写（commit 截至 2026-06-13），后续仓库可能新增部门或调整脚本接口，建议动手前先
git pull同步最新版本。