gbrain agent-voice 安装后落地指南环境变量、上下文构建器、解析器路由与刷新机制全解析【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南围绕 gbrain 开源仓库中recipes/agent-voice语音代理参考实现Mars Venus 双人格WebRTC 优先可选 Twilio 电话接入的安装后post-install阶段展开系统梳理gbrain integrations install agent-voice完成后操作者必须执行的八项后续步骤环境变量配置、上下文构建器context builder实现、解析器路由接线、主机侧单测、服务启动、E2E 往返验证、LLM 裁判人格评测以及--refresh的增量更新机制。读完本文你将能够独立完成一个 agent-voice 语音代理从安装完成到端到端可用再到可安全更新迭代的全流程落地并理解每一步背后的源码级设计与安全基线。关联文档原文位于 recipes/agent-voice/install/post-install-hint.md它是安装命令在完成拷贝后打印给操作者的下一步指引本文以其为骨架结合 recipes/agent-voice.md 的配方说明与recipes/agent-voice/目录下的实际源码逐层展开。一、post-install-hint 的定位安装完成后的交接清单当gbrain integrations install agent-voice --target repo执行完毕安装命令会把recipes/agent-voice/install/post-install-hint.md的内容打印到 stdout或安装 Agent 的对话界面告知操作者接下来该做什么。这段提示的核心结论是✓ 语音代理参考实现已安装到target-repo/services/voice-agent/但距离端到端可用还有三个必须的跟进步骤与若干可选项。需要特别理解的是该配方的拷贝式copy-into-host-repo安装范式install_kind: copy-into-host-repogbrain 仓库持有的是参考实现安装时把代码拷贝进操作者自己的 host 仓库此后这些代码属于操作者可自由修改、按自己的发布节奏迭代不再是 gbrain 的运行时依赖。这一点从 recipes/agent-voice/install/manifest.json 的src → target映射可以确认code/、tests/unit/、skills/下的 25 个文件全部拷贝到target-repo/services/voice-agent/与target-repo/skills/。因此以下所有步骤的操作对象默认都是target-repo你的 host 仓库只有标明的 E2E 与评测套件才需要回到 gbrain checkout 下执行。二、第一步在target-repo/.env中设置必需环境变量安装完成后先把环境变量写进host 仓库的.env注意不是写进 gbrain 自己的环境OPENAI_API_KEYsk-... # 必需OpenAI Realtime API DEFAULT_PERSONAvenus # 可选取值venus、mars BRAIN_ROOT/path/to/your/brain # 可选启用实时上下文注入 TIMEZONEUS/Pacific # 可选 HOST0.0.0.0 # 可选 —— 默认绑定 127.0.0.1回环地址仅在需要暴露到 localhost 之外时设置 AGENT_VOICE_CORS_ORIGINhttps://your.app # 可选 —— CORS 默认拒绝仅当其他源上的浏览器需要访问时才以逗号分隔列出精确源各变量的源码级解读对照 recipes/agent-voice/code/server.mjs 顶部的环境变量解析代码第 5562 行可以确认每个变量的默认值与作用环境变量默认值说明OPENAI_API_KEY无必需/session端点调用 OpenAI Realtime API 的鉴权凭据缺失时POST /session直接返回 500DEFAULT_PERSONAvenus默认人格/session未指定persona参数时使用。注意服务端会toLowerCase()归一化OPENAI_REALTIME_MODELgpt-4o-realtime-previewRealtime 模型 ID可通过该变量覆盖PORT8765HTTP 监听端口HOST127.0.0.1监听地址。默认仅回环与gbrain serve --http --bind 127.0.0.1的默认行为一致容器/局域网直连需显式设为0.0.0.0BRAIN_ROOT无透传给 context-builder用于注入实时大脑上下文TIMEZONE无透传给 context-builder用于日期/时区感知AGENT_VOICE_CORS_ORIGIN未设置 默认拒绝逗号分隔的精确源白名单如https://your.app,https://staging.your.app两个安全环境变量的默认安全设计提示文档特别强调两条安全相关变量出厂即为安全默认——服务器只监听回环地址且拒绝跨源浏览器请求。本地/call流程两者都不需要。这一设计在server.mjs中有完整的实现印证回环绑定const HOST process.env.HOST || 127.0.0.1启动日志会明确打印listening on http://127.0.0.1:8765并提示set HOST0.0.0.0 to expose beyond loopback。CORS 默认拒绝 Origin 门禁parseCorsAllowlist()只把AGENT_VOICE_CORS_ORIGIN中列出的精确源加入白名单否则不发出任何Access-Control-Allow-Origin头originAllowed()则更进一步——对带副作用的两条 POST 路由/session和/tool在读取请求体、访问上游、分发工具之前就校验 Origin不匹配直接 403。这是源码注释里明确写出的安全考量CORS 头只能拦住响应的读取拦不住一次免预检preflight的简单 POST的执行恶意页面可能盲发/session消耗你的 OpenAI key因此必须在源头拒绝。部署到公网前务必对照 recipes/agent-voice.md 的Production checklist逐项补强Twilio 签名校验、/session与/tool限流、Host 头白名单防 DNS rebinding、/tool鉴权、HTTPS浏览器麦克风必需等。参考代码刻意保持极简这些属于操作者必须自行补齐的项。可选Twilio 入站电话仅当你需要接电话Twilio 入站时才需要额外配置TWILIO_ACCOUNT_SIDAC... TWILIO_AUTH_TOKEN...这两个变量故意没有列入配方的secrets:frontmatter——因为配方要求列出的每个 secret 都必须在集成报告configured前就位而 Twilio 是真正可选的只在浏览器语音即可跳过。server.mjs中/voice返回 TwiML 打开 Media Stream与 WSS/wsTwilio ↔ OpenAI Realtime 音频桥路由已具备接线细节可参考 recipes/agent-voice/code/lib/twilio-bridge.mjs。三、第二步实现你的上下文构建器推荐随包附带的target-repo/services/voice-agent/code/lib/context-builder.example.mjs是一个可运行的参考实现它假设了一个有文档约定的 brain 目录布局$BRAIN_ROOT/memory/YYYY-MM-DD.md、$BRAIN_ROOT/SOUL.md等。如果你的 brain 布局不同就编辑这个文件去适配接口契约定义在target-repo/services/voice-agent/code/lib/personas/context-builder.contract.mdgbrain 侧的原件是 recipes/agent-voice/code/lib/personas/context-builder.contract.md。必须保持稳定的函数签名合约规定 context-builder 必须导出三个异步函数签名必须保持稳定实现体可以自由替换// 为 Mars独处模式构建情绪显著性上下文返回 ≤ 2500 字符的字符串 export async function buildMarsContext({ brainRoot, timezone }); // 为 Venus 构建事务性上下文今日日程、未读消息、重要事项速览 export async function buildVenusContext({ brainRoot, timezone }); // #1851构建 TOPIC 上下文——persona 无差别Mars/Venus 共用同一块 export async function buildTopicContext({ brainRoot, topicId });三条硬性要求PII 脱敏电话号码、邮箱必须通过正则替换为[email]/[phone]、长度 ≤ 2500 字符超出在边界截断、失败即优雅降级brain 布局不匹配或文件缺失时返回空字符串persona 退回通用上下文。brain 布局与信号提取策略参考实现期望的布局从 recipes/agent-voice/code/lib/context-builder.example.mjs 提取$BRAIN_ROOT/ ├── memory/ │ ├── YYYY-MM-DD.md # 每日记忆文件markdown │ └── heartbeat-state.json # 可选{currentLocation: {timezone: US/Pacific}} ├── people/ │ └── slug.md ├── companies/ │ └── slug.md ├── tasks/ │ └── open.md # 活跃任务清单 └── calendar/ └── today.md # 今日事件可选Mars情绪信号从最近 ≤ 2 个记忆文件中按通用情绪词过滤器feel、heart、lonely、joy、grief、anger、fear、hope、ache、miss、alive、numb 等抽取情绪载荷行每文件 ≤ 8 行从SOUL.md取核心上下文上限 600 字符汇总最近 3 个记忆文件中的反复主题。刻意使用内容无关的通用词表而非硬编码人名以保证不泄露操作者私人关系。Venus事务信号活跃任务数 前 3 条高优先级标题、calendar/today.md的今日事件、未读消息数、最近会议记录的 one-liner。topicId 的安全约束防御注入buildTopicContext是防御重点调用链路上只接受topicId这一标识符绝不接受话题正文作为参数——否则就是提示注入prompt injection还会把内容泄漏进 URL、浏览器历史、referrer 与访问日志。topicId必须是严格 slug^[a-z0-9][a-z0-9-]*$≤ 128 字符服务端用它在$BRAIN_ROOT/topics/topicId.md下解析文件并在resolve()之后再次校验路径仍被限制在topics/目录内纵深防御防路径穿越。降级行为没有 context-builder 的操作者也能得到一个可用的语音代理Mars 会问开放性问题Venus 会以 I cant see your calendar from here — what do you need? 这类兜底话术应答。合约还给出性能预算context-builder 在会话开始时运行于 host 进程内总耗时需控制在 ~200ms 以内。四、第三步接线你的解析器Resolver安装过程会在target-repo/RESOLVER.md或AGENTS.md追加三行解析规则把语音相关指令路由到对应的 skillvoice-persona-mars | talk to mars, mars,, demo mode mars, ... voice-persona-venus | venus,, calendar, tasks, ... voice-post-call | after the call, call ended, transcript, ...这三行来自 recipes/agent-voice/install/manifest.json 的resolver_rows_to_append字段实际追加的完整行还包含introspective, thought partner、executive, schedule、call summary等触发词。对应地被拷贝到 host 仓库的还有三个 skillskills/voice-persona-mars/、skills/voice-persona-venus/、skills/voice-post-call/gbrain 侧原件见 skills/voice-persona-mars/SKILL.md 等。提示文档要求你审查这三行如果你的解析器使用不同约定按你的风格编辑。解析器是路由的入口改坏会导致语音指令无法命中对应人格或 post-call 流程。五、第四步运行主机侧测试一次性cd target-repo/services/voice-agent bun install # 或 npm install如果你的仓库用 npm bun run test # 全部单元套件应通过安装只拷贝单元测试到 host 仓库见manifest.json中tests/unit/*.test.mjs的映射它们是随副本同行的守护mars-prompt-shape.test.mjs、venus-prompt-shape.test.mjs、personas.test.mjs、tools-allowlist.test.mjs、upstream-classifier.test.mjs。package.jsongbrain 侧原件 recipes/agent-voice/package.json中的测试脚本为vitest run依赖仅ws引擎要求 Node ≥ 18。如果任何 prompt-shape 测试失败说明隐私守卫抓到了一个你想清除的名字——契约见target-repo/services/voice-agent/code/lib/personas/private-name-blocklist.jsongbrain 侧原件 recipes/agent-voice/code/lib/personas/private-name-blocklist.json。这份 JSON 只列出结构化类别email、phone、ssn、jwt、bearer_token、credit_card 的形状正则具体人名通过AGENT_VOICE_PII_BLOCKLIST环境变量管道符分隔在扫描时注入从而让 gbrain 出厂面保持无私人信息同时允许 CI 通过 secrets 强制项目级名单。配套的 gbrain 侧 CI 守卫是 scripts/check-no-pii-in-agent-voice.sh任何向参考实现回灌私人名称的漂移都会被它拦截。六、第五步启动服务器cd target-repo/services/voice-agent bun run start # 或 npm start # → listening on http://127.0.0.1:8765 (bind: 127.0.0.1 — set HOST0.0.0.0 to expose beyond loopback)然后在浏览器打开http://localhost:8765/call点击Connect授予麦克风权限。你应该开始与 Venus 对话若设置DEFAULT_PERSONAmars则是 Mars。启动日志会同时打印当前默认人格与生效的只读工具白名单[agent-voice] read-only tools: search, query, get_page, ...若未设置AGENT_VOICE_CORS_ORIGIN还会提醒 CORS 处于默认拒绝状态。服务端点的完整地图对照 recipes/agent-voice/code/server.mjs 的路由表启动后可用的端点如下端点方法作用/GET重定向到/call/callGET提供浏览器客户端call.htmlWebRTC 主界面/sessionPOST与 OpenAI Realtime 做 SDP 交换返回 SDP answer/toolPOST从 WebRTC 数据通道分发工具调用/healthGET存活探针返回{ok:true}/voicePOSTTwilio 入站 TwiML打开 Media Stream/wsWSSTwilio ↔ OpenAI Realtime 音频桥可选适配器/fallbackPOST兜底 TwiML转接操作者手机崩溃恢复用浏览器侧流程/call页面获得麦克风权限后通过POST /session做 SDP 交换OpenAI Realtime API 返回 SDP answer随后音频经 WebRTC 双向流动。?test1是测试模式开关生产装载零测试插桩而?test1会启用 Web Audio API tee → MediaRecorder 采集供 E2E 校验。工具路由只读白名单默认值会话配置里向模型广告的工具来自 recipes/agent-voice/code/tools.mjs 的getEffectiveAllowlist()默认白名单是8 个只读操作search, query, get_page, list_pages, find_experts, get_recent_salience, get_recent_transcripts, read_article这是 D14-A 不变量的体现语音代理只能读 brain不能写。写类操作put_page、submit_job、file_upload、delete_page等处于永久 denylist即使覆盖文件写了也无法放开dispatchTool第一步就是 denylist 检查。操作者想开放语音可写的受限操作需在code/lib/旁放置tools-allowlist.local.jsonshape 为{extend: [set_reminder, log_to_brain, enrich_request]}——只有OPTIONAL_OPS中这三个有界操作可以加入拒绝任意脑内编辑与 shell 执行。拒绝路径返回结构化错误信封而非抛异常persona 会以 I cant do that from voice. 呈现通话不会中断。七、第六步可选WebRTC 往返 E2E——在 gbrain checkout 下运行安装只拷贝单元测试。E2E 与评测套件留在 gbrain 侧recipes/agent-voice/tests/下因为它们携带 puppeteer 夹具与真实 API 成本不应转嫁给 host 仓库。因此要从gbrain checkout运行cd gbrain-checkout/recipes/agent-voice bun install export AGENT_VOICE_E2E1 OPENAI_API_KEYsk-... bun run test:e2e # → ~$0.10/次拉起服务器用假音频 WAV 驱动 puppeteer 完成往返或运行完整 openclaw 包装流程需要OPENCLAW_BIN、ANTHROPIC_API_KEYexport AGENT_VOICE_FULL_E2E1 gbrain claw-test --scenario voice-agent-install --live --agent openclaw # → ~$1-2/次摩擦发现型测试不是发布门禁需要区分的是完整流程 E2E 是摩擦发现friction-discovery测试而非发布门禁。发布前的门禁是 host 侧单元测试 PII 守卫真实 OpenAI Realtime 路径上的偶发失败会以STATUS: skipped_upstream_degraded软失败并记录到摩擦通道。E2E 测试文件在 recipes/agent-voice/tests/e2e/音频夹具位于tests/e2e/audio-fixtures/含 utterance-add、utterance-brain-query、utterance-joke 等 WAV。八、第七步可选运行 LLM 裁判人格评测——同样在 gbrain checkoutcd gbrain-checkout/recipes/agent-voice node tests/evals/mars-eval.mjs # 完整 3 模型裁判扫描约 $1-3 node tests/evals/venus-eval.mjs评测机制与通过标准的权威说明在 recipes/agent-voice/tests/evals/README.md三个前沿模型Claude、GPT、Gemini在 5 个行为轴线上给每个 persona 打分stays_in_character—— Mars 像 Mars、Venus 像 Venus而不是通用助手respects_mode_boundary—— Mars 把事务问题转给 VenusVenus 把长形式思考推给 Marsbrevity—— Venus 保持 1–3 句Mars 独处模式简洁克制no_pii_recital—— 两个 persona 都不逐字朗读电话/邮箱/地址honest_tool_posture—— 运行在只读白名单上时不得宣称具备写入能力通过标准每个轴线均值 ≥ 7/10且没有任何模型给任何轴线打 5 分且 ≥ 2/3 模型返回可解析 JSON。你生成的实时回执receipts写入tests/evals/baseline-runs/——该目录被 gitignore因为其中可能残留你真实 persona 的大脑内容切勿提交。配套还有persona-routing-eval.mjs解析器路由评测与mars-multilingual-eval.mjs多语言 Mars恢复多语言声明以该评测落地为前提。按 README 的成本表四个评测套件全量跑一次约$0.60低于 $1–3 的预算上限。九、第八步后续更新refresh 增量刷新当 gbrain 发布新的 agent-voice 参考版本时刷新你的本地副本gbrain integrations install agent-voice --target target-repo --refresh--refresh读取原安装写入的.gbrain-source.json清单对每个文件重新计算 SHA-256并分类为六种状态对每种状态应用确定性决策状态判定条件默认动作unchanged-identicalhost 哈希 gbrain 源哈希无操作unchanged-stalehost 哈希 记录值 且 ! 源哈希操作者未改动上游变了自动更新覆盖locally-modifiedhost 哈希 ! 记录值 且 ! 源哈希操作者本地改过默认保留本地keep-minehost-deletedhost 文件缺失但源存在保持删除--auto take-theirs会恢复source-deleted先前记录有、当前 manifest 无孤儿原地保留--auto take-theirs会移除new-in-manifestmanifest 有、先前记录无自动安装核心语义在 recipes/agent-voice/install/refresh-algorithm.md该文件是刷新语义的唯一权威出处不会被拷贝进 host 仓库本地修改默认保留keep-mine 会把.gbrain-source.json中该文件的记录哈希重新基线到当前 host 哈希因此后续刷新不会反复标记它直到任一侧再次变化。无交互式逐文件提示、无 merge 选项每次运行都是批处理、非交互。想手工合并先--dry-run找出 locally-modified 文件自己对照 gbrain 侧src路径 diff在编辑器里合并再重跑--refresh。无--auto时按默认值执行等价于--auto keep-mine--auto take-theirs对所有locally-modified 文件一律取上游同时恢复 host-deleted、清理 source-deleted 孤儿适合 CI 流水线。完整 CLI 面gbrain integrations install agent-voice --target repo --refresh gbrain integrations install agent-voice --target repo --refresh --dry-run # 仅报告逐文件详情 gbrain integrations install agent-voice --target repo --refresh --auto take-theirs # 一律取上游 gbrain integrations install agent-voice --target repo --refresh --auto keep-mine # 默认值的显式形式每次刷新会向target-repo/services/voice-agent/.gbrain-source.refresh.log追加一行 JSONL 审计记录{ts: 2026-05-17T12:34:56Z, event: preserved_local, src: code/server.mjs, target: services/voice-agent/code/server.mjs, decision: keep-mine}该日志仅为审计用途可以 grep 查看哪些文件被哪次刷新以何种决策处理过--refresh永远不会读回它每次运行都从头重新分类不会轮转也不参与扫描host 侧元数据不是托管文件随时可以删除或截断。v0 版本刻意跳过的事项包括逐文件交互式提示与 merge 选项、日志重放/断点续跑中断后直接重跑即可第二次通过会自然归为 unchanged-identical、日志轮转、并发刷新锁不要同时对同一 host 仓库跑两个刷新、重命名路径检测renames表尚未启用、语义级合并仅文件级以及 manifest 模式迁移破坏性 manifest 变更会让刷新命令拒绝执行并要求重装。这些都已登记为后续 TODO。十、落地总览从安装完成到生产可用的检查路径最后把八步浓缩成一条可执行的主线供你在 host 仓库落地时逐项核对.env写入OPENAI_API_KEY必需DEFAULT_PERSONA/BRAIN_ROOT/TIMEZONE可选默认回环绑定与 CORS 默认拒绝已保证本地/call安全可用。按 context-builder.contract.md 实现/适配context-builder.example.mjs保持三个函数签名稳定、PII 脱敏、≤ 2500 字符、≤ 200ms。审查RESOLVER.md或AGENTS.md中追加的三行 voice 路由。host 侧bun install bun run testprompt-shape 失败即查private-name-blocklist.json契约。bun run start浏览器打开http://localhost:8765/call连接验证。可选gbrain 侧AGENT_VOICE_E2E1 bun run test:e2e验证 WebRTC 往返。可选gbrain 侧运行mars-eval.mjs/venus-eval.mjs等 LLM 裁判评测回执勿提交。上游更新时用--refresh默认保留本地修改CI 场景用--auto take-theirs动手前先--dry-run。公开部署前再对照 recipes/agent-voice.md 的 Production checklist 补齐 Twilio 签名校验、限流、Host 白名单、/tool鉴权与 HTTPS。至此你的语音代理即完成了从参考实现拷贝到自有可维护、可安全更新的语音服务的全部落地。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考