Harvey配置指南：harvey.yaml详解，教AI销售代理卖什么、卖给谁

Harvey 是一个跑在你本机上的 AI 销售代理（autonomous AI sales agent）：它会寻找潜在客户、撰写并发送冷邮件、处理回复、促成会议，全程只消耗你已有的 Claude 或 ChatGPT 订阅，无需 API Key。而决定这个销售代理"是谁、卖什么、卖给谁"的，就是仓库根目录下的 harvey.yaml——这份纯文本配置教它扮演什么身份、讲什么卖点、对谁开口、用什么渠道、发多快。下面按配置块逐一拆解。

快速开始：3 种生成 harvey.yaml 的方式 🚀

拿到模板配置有三种途径，推荐第一种：

方式	命令	说明
从官网训练（推荐）	harvey train https://你的官网.com	爬取官网，自动学习产品并生成 harvey.yaml，同时产出 skills/product_knowledge.md 与 competitive_intel.md 两份技能文件（详见 harvey/trainer.py）
交互式向导	harvey setup	6 步问答：选 brain 提供商 → 配邮箱 → 填产品与 ICP → 设行为参数（见 harvey/setup.py）
手动编辑	直接打开模板	以仓库里的 harvey.yaml 为模板，按注释逐块填写

配置块总览：7 个键决定一切

配置块	干什么	必填	源码位置
persona	外联身份：名字、公司、语气	✅	harvey.yaml#L1-L7
product	卖什么：产品、定价、卖点、异议应对、成交目标	✅	harvey.yaml#L9-L28
icp	卖给谁：行业、职位、规模、地区	✅	harvey.yaml#L30-L45
channels	怎么发：邮件/LinkedIn 渠道与限流	否	harvey.yaml#L47-L58
usage	怎么跑：订阅额度上限、心跳间隔、静默时段	否	harvey.yaml#L60-L66
brain	用哪个订阅思考：claude / codex	否	harvey/config.py#L216-L257
compliance	发件前逐收件人合规检查	否	harvey.yaml#L74-L78

前三个块必填，后四个都有默认值。所有字段由 harvey/config.py 中的 Pydantic 模型校验，写错会直接报出字段路径。

文件查找顺序（harvey/config.py#L415-L436）：harvey.local.yaml 永远优先于 harvey.yaml，且本地文件在 当前目录 → 项目根目录 两级中先找。这是刻意设计：harvey.local.yaml 已被 gitignore，你可以在自己的 fork 里放真实产品配置，而仓库中的 harvey.yaml 保持模板——避免误公开你的定位与定价。

persona 配置：给 AI 销售代理起名字、定人设

persona 定义了发件人身份，6 个字段全部必填：

persona:
  name: "Harvey"            # 潜客看到的名字
  company: "Your Company"
  role: "Business Development"
  email: "[e-mail]"
  linkedin: "linkedin.com/in/harvey-yourcompany"
  tone: "professional, consultative, confident"

• email 与 role 会体现在冷邮件的署名中，务必与你的发件域名一致；
• tone 会被注入各代理的提示词（见 prompts/），直接决定文案风格，可以按品牌自由改写。

product 配置：卖什么、怎么回应异议、成交目标是什么

这是整份配置中最"有业务含量"的块（harvey.yaml#L9-L28）：

product:
  name: "Your Product"
  description: "Describe what your product does and who it's for"
  pricing: "Starting at $X/mo"
  key_benefits:
    - "Benefit 1"
  objection_responses:
    "too expensive": "I understand budget is important. Most of our clients see ROI within 30 days..."
    "already have a solution": "That makes sense. Curious — what's the one thing you wish it did better?"

• key_benefits：建议写 3–5 条具体、可量化的卖点，Writer 代理生成邮件序列时优先引用它们；
• objection_responses：异议应对表——把销售中常听到的推脱当作键、你的实际回应当作值，Handler 代理处理回复时会直接调用（方法论见 skills/objection_handling.md）；
• offer 子块决定"有人感兴趣时干什么"：

参数	可选值	含义
primary / entry	任意文案	主报价 / 低门槛入口（如"14 天免费试用"）
goal	book_call、start_trial、get_reply	成交目标
booking_method	calendar_link、suggest_times、ask_preference	约会议方式
booking_url	日历链接	仅 calendar_link 时使用

icp 配置：教它卖给谁

icp（Ideal Customer Profile）划定目标客户画像，是 Scout 代理给潜客打分、Discover 阶段筛选公司的依据：

icp:
  industries:
    - "SaaS"
    - "Marketing Agency"
  company_size: "10-200 employees"
  titles:
    - "VP Marketing"
    - "CMO"
  geography:
    - "United States"
  hiring_signals: []

两个进阶字段：

• hiring_signals：列出"正在招什么职位 = 正在采购什么工具"的信号词。一家公司在招 Head of Growth，说明它在找增长工具——Harvey 会据此扫描招聘页与职位板。留空则回退到 titles（harvey/config.py#L55-L63）；
• geo_coordinates：给每个城市提供 纬度,经度,半径km，例如 "Denver, CO": "39.7392,-104.9903,50"——没有坐标，目录类数据源只能按公司名匹配，召回会大打折扣。

channels 配置：发送渠道与限流阀门

channels:
  email:
    enabled: true
    provider: "gmail"          # gmail | microsoft | smtp | instantly
    max_daily_sends: 50
    require_approval: true      # 每封邮件先进 Outbox 等人工批准
    send_to_risky: false        # 是否发给 catch-all 域名
    max_bounce_rate: 0.05       # 退信率超 5% 自动停发
  linkedin:
    enabled: true
    max_daily_connections: 20
    max_daily_messages: 10

• provider 对应不同的邮箱接入：gmail（推荐）走 Gmail/Workspace API，microsoft 走 Microsoft 365（docs/microsoft365.md），smtp 兼容任意 SMTP+IMAP 邮箱；
• require_approval：Copilot 模式开关。true 时每封外发邮件都停在 Outbox 等你批准（harvey outbox 或仪表盘 Outbox 页），确认质量稳定后改为 false 即全自主运行；
• max_bounce_rate：全局熔断器，退信率超过阈值自动暂停全部发送（实现见 harvey/integrations/quota.py 与 harvey/gate.py）；
• LinkedIn 自动化违反其服务条款，请只用可以承受风险的账号。

usage 与 brain 配置：运行节奏与思考引擎

usage:
  max_daily_claude_percent: 80   # 只用订阅额度的 80%，给你自己留余量
  heartbeat_interval_minutes: 15  # 心跳间隔：醒来→决策→干活→睡下
  quiet_hours:
    start: "22:00"
    end: "07:00"
    timezone: "America/New_York"

brain:
  provider: "claude"    # claude | codex（ChatGPT 订阅，可选）
  model: ""             # 留空用提供商默认模型

• max_daily_claude_percent 名虽带 claude，实际限制的是 brain.provider 所选订阅（设置名早于 Codex 支持）；Harvey 会读取订阅配额实时节流；
• 静默时段、时间格式、时区都有严格校验：时间必须 24 小时制 HH:MM，时区必须是 IANA 名（如 Asia/Shanghai）；
• 选 Codex 时注意：仅支持 macOS/Linux 且需 Codex CLI 0.159.3，失败永远不会自动回退到 Claude（详见 harvey/codex.py）。

compliance 配置：发件前的合规检查（可选）

compliance:
  precleared:
    enabled: false
    sender_country: ""          # GB 或 US：你的业务所在地
    address_source: "unknown"   # published | bought | scraped | given | unknown

启用后，第一封冷邮件发出前，Harvey 会通过 Precleared 检查该收件地址在 UK PECR、US CAN-SPAM、Canada CASL、德国 UWG 等法规下是否允许被冷邮件触达；任何不是"可以发"的结论都会把邮件扣在 Outbox 并附上原因（实现见 harvey/integrations/precleared.py）。注意 enabled: true 时 sender_country 必须为 GB 或 US，否则配置直接报错。

常见配置错误与排查 🔍

报错 / 现象	原因与解法
Config file not found: harvey.yaml	找不到配置文件，运行 harvey setup 或从模板创建（harvey/config.py#L309-L328）
Invalid YAML in harvey.yaml	缩进或符号写错，YAML 对缩进敏感，复制模板时最易踩坑
compliance.precleared.sender_country must be GB or US	开启 precleared 检查却漏填/写错 sender_country
'22:0' is not a valid time	quiet_hours 必须 24 小时制 HH:MM，如 22:00
is not a valid timezone	timezone 必须 IANA 名，如 America/New_York、Asia/Shanghai
max_daily_claude_percent must be between 0 and 100	百分比越界，改回 0–100

校验失败时，日志会逐条列出 字段路径: 错误原因，照单修正后重跑 harvey setup 即可（harvey/config.py#L300-L306）。

小结：一张配置检查清单 📋

1. harvey train https://你的官网.com 或 harvey setup 生成 harvey.yaml；
2. 必改三块：persona（身份）、product（卖点 + 异议应对 + 成交目标）、icp（客户画像）；
3. 确认 channels.email.provider 与 .env 中凭据匹配，保留 require_approval: true 先看几轮 Outbox；
4. harvey signals 确认要采集哪些信号，再 harvey run 启动心跳循环。

配置只是第一步：Harvey 的销售技巧藏在 skills/ 的 Markdown 技能库里，改一个文件、下一个心跳就生效——这才是调教你的 AI 销售代理的完整路径。