过去使用 Codex 进行代码审查，通常是把代码、分支或 Pull Request 交给同一个模型。
它负责理解改动、发现问题、判断严重程度，最后再生成审查报告。
这种方式足够简单，也很容易使用，但它存在一个明显的问题：
从发现问题到验证问题，所有判断都可能来自同一个模型。
如果模型第一次阅读代码时忽略了某个风险，它在第二次检查自己的结论时，也可能继续忽略同一个风险。
随着 Codex 对自定义 Subagent 的支持逐渐完善，我们可以采用一种更接近真实软件团队的工作方式：
Codex 主 Agent
负责理解任务、拆解范围和调度流程
Kimi Code Reviewer
负责独立代码审查
MiniMax Code Reviewer
负责从另一个模型视角检查缺陷
Pi Code Reviewer
调用独立审查器提出候选问题，再逐条验证
最终形成的已经不再是一个模型独自完成全部工作，而是一套由主 Agent 统一调度的多模型代码审查系统。
🚀 本篇笔记所对应的视频：
多模型系统的意义，并不是简单地让三个模型重复检查同一份代码。
如果只是把同一个 Prompt 同时交给多个模型，再把结果拼接起来，通常只会产生大量重复内容。
更有效的做法，是先为每个 Agent 设定清晰的职责边界。
例如：
| Agent | 主要职责 |
|---|---|
| 主 Agent | 确定审查范围、创建子 Agent、汇总与验证结果 |
| Kimi Reviewer | 独立检查正确性、安全性、并发和兼容性问题 |
| MiniMax Reviewer | 从另一个模型视角补充代码缺陷和测试风险 |
| Pi Reviewer | 调用独立审查流程，并验证候选问题是否真实存在 |
这样的设计有两个直接价值。
不同模型的训练数据、推理方式和代码偏好并不完全相同。
同一个问题可能被 GPT 忽略，却被 Kimi 或 MiniMax 发现。
多模型不能保证一定正确，但可以扩大审查覆盖面。
一个模型提出问题，并不意味着这个问题可以直接写进最终报告。
更可靠的流程应该是：
第三方模型提出候选问题
↓
主 Agent 重新打开对应代码
↓
检查触发路径与实际影响
↓
必要时运行测试或静态检查
↓
确认后才进入最终报告
也就是说，其他模型负责提供新的观察角度，主 Agent 负责最终证据校验。
这套系统中最重要的设计原则，是把主 Agent 和第三方 Subagent 的模型配置彻底分开。
整体结构如下：
用户任务
↓
Codex 主 Agent
├→ Kimi Code Reviewer
├→ MiniMax Code Reviewer
└→ Pi Code Reviewer
↓
汇总、去重与验证
↓
最终报告
主 Agent 继续使用默认的 OpenAI 模型，负责：
第三方模型则只绑定到指定的自定义 Agent。
例如，只有显式调用 Kimi Reviewer 时，任务才会被路由到 Kimi。
普通 Subagent 不会因为系统中注册了 Kimi，就自动切换到 Kimi 模型。没有明确指定 Agent 类型时，它仍可能继承主 Agent 的模型配置。
这可以避免一个非常危险的问题：
为了增加一个第三方 Reviewer，却意外把整个 Codex 主 Agent 都切换到了第三方模型。
因此，第三方模型的连接信息、模型目录和认证逻辑，都应该被限制在独立的 Provider 和 Agent 配置中，而不是放入主配置的全局层级。
代码审查和代码实现是两种不同的职责。
如果 Reviewer 在发现问题后立即开始修改代码，就容易出现以下情况：
因此，我为所有 Code Review Subagent 设置了相同的基本原则：
默认只读
不主动编辑文件
不创建提交
不扩大任务范围
不把风格偏好当成缺陷
Reviewer 应重点检查：
每一条问题还必须回答三个问题：
问题发生在哪里？
什么场景会触发？
会造成什么实际影响？
如果没有足够证据，就不应该为了让报告显得“有内容”而编造 Finding。
没有发现可执行问题时，直接说明没有验证到明确缺陷，反而更加可靠。
主 Agent 和第三方 Subagent 使用不同模型和 Provider 时，最大的难点往往不是模型路由，而是任务上下文如何传递。
在实测中，常见的上下文交接方式存在三种情况。
看起来最保险，但完整历史可能同时携带父 Agent 的模型类型、角色状态和内部上下文。
对于自定义第三方 Agent，这可能导致：
这种方式看似最干净，但第三方 Subagent 可能根本收不到当前用户的实际任务。
结果通常是：
在这次配置中，更可靠的方式是只让子 Agent 继承当前一轮任务。
这样既可以保留当前用户的明文要求，又不会把父 Agent 的完整历史、角色和模型状态全部带入子线程。
它解决的是一个非常实际的问题：
第三方模型必须知道“现在要做什么”，但不一定需要知道主 Agent 之前所有的思考过程。
这也是跨 Provider Subagent 能否稳定工作的关键。
当父任务中包含“创建 Reviewer 并执行审查”之类的描述时，第三方 Subagent 有可能把这条父级指令也当成自己的任务。
于是可能出现：
主 Agent 创建 Kimi Reviewer
↓
Kimi Reviewer 又尝试创建 Kimi Reviewer
↓
新的 Reviewer 继续创建 Reviewer
这会造成无意义的递归调用。
因此，每个专用 Subagent 的角色指令都应该明确：
直接执行被委派的任务，不要再次创建或委派给其他 Codex Agent。
在联调过程中，还应当让不同角色清楚自己的身份：
主 Agent：
负责创建子 Agent 并等待结果
Reviewer：
直接执行 Code Review，不再继续委派
在多 Agent 系统里，“你是谁”与“你应该做什么”同样重要。
Kimi Reviewer 是一个独立的只读代码审查 Agent。
它适合检查：
它的价值在于，为主 Agent 提供一个不同模型的独立审查视角。
MiniMax Reviewer 的职责与 Kimi Reviewer 类似，但使用不同模型。
同时保留两个 Reviewer，并不是为了证明哪个模型一定更强，而是为了观察：
如果两个 Reviewer 返回同一个问题，主 Agent 仍需要重新验证。
多个模型意见一致，只能提高关注优先级，不能直接代替证据。
Pi Reviewer 的设计更特殊。
它本身仍然由主模型运行，但会调用一个受限、只读的 Pi 审查器，让 Pi 使用另一个模型进行第二轮独立审查。
其工作流程是：
Codex Reviewer 确定审查范围
↓
调用只读 Pi Reviewer
↓
Pi 返回候选问题
↓
Codex 逐条重新检查代码
↓
确认或否决每一条候选问题
↓
只报告通过验证的问题
这里最关键的原则是：
Pi 的输出只是审查证据，不是最终答案。
Pi 返回的问题必须被重新打开、重新定位和重新验证。
需要删除：
这种结构比直接转发 Pi 的回答更加可靠，因为它形成了“外部发现—本地验证”的两阶段流程。
自定义模型接入 Codex 时，终端可能出现模型元数据相关的 Warning。
很多人看到 Warning 后，会立刻认为第三方模型没有真正运行。
但模型目录警告和模型路由失败是两件不同的事情。
判断 Subagent 是否真的使用了指定模型，应同时检查：
也就是说，不要只看终端里的一行提示。
真正可靠的判断来自完整的运行链路：
Agent 角色正确
+
模型正确
+
Provider 正确
+
工具调用真实发生
+
请求日志匹配
当第三方模型通过本地代理接入 Codex 时，还需要注意系统网络环境。
如果系统启用了全局 HTTP 代理，本来发往本机服务的请求，也可能被错误转发到外部代理。
表现通常是：
解决思路不是不断修改模型参数，而是先确认：
这是本地 Agent Harness 中非常典型的一类问题：
看起来像模型错误，实际是网络路径错误。
另一类常见问题是：配置最初完全正确，但代理工具重启、切换 Provider 或重新接管后，主配置被自动重写。
结果可能是：
原本：
主 Agent 使用 OpenAI
Kimi 只用于指定 Reviewer
重启后：
主 Agent 也被改成 Kimi
这种错误非常隐蔽，因为用户可能仍然看到 Codex 正常运行，却不知道模型路由已经变化。
更可靠的做法是：
如果确实需要自动修复配置，脚本应当具备幂等性：
无论执行一次还是执行多次，最终配置都保持相同。
仅仅看到主 Agent 输出一句“Kimi 已完成审查”，并不能证明 Kimi 真的运行过。
父 Agent 有可能根据已有上下文模拟一个看似合理的子任务结果。
因此，完整验证应至少覆盖以下几层。
确认主配置和自定义 Agent 配置可以被真实解析器读取，而不是仅凭肉眼判断格式正确。
发起一次真实任务，确认主 Agent 仍然使用预期的默认模型和 Provider。
绕过 Subagent 交接，直接测试第三方模型路由，确认本地代理能够收到请求并成功返回。
由主 Agent 创建指定 Reviewer，并确认子线程中的：
要求子 Agent 返回一个只有实际执行后才能获得的标记或证据。
例如：
重启代理工具和 Codex 后，再次确认：
只有这些步骤全部通过，才能说明系统不是“配置看起来正确”，而是真的完成了端到端路由。
说明模型连接和 Provider 大概率正常。
问题更可能出现在：
通常说明它没有收到清晰的当前任务。
应优先检查上下文继承方式，而不是立刻修改模型参数。
这通常属于上游容量问题。
不应直接把它判断为协议或本地代理配置错误。
说明全局配置被代理工具重新接管。
应检查配置事实来源和重启后的覆盖逻辑。
在接入第三方模型时，最容易被忽略的是凭据传播范围。
建议始终遵守以下原则：
尤其在使用 Pi 等外部审查器时，传递内容应严格限制在当前代码审查范围内。
对于大型 diff，可以只传递：
不要为了让模型拥有“完整上下文”，把整个用户目录、配置目录或凭据文件一起交给它。
这套多模型代码审查系统，真正有价值的地方，不是 Codex 可以同时调用 Kimi、MiniMax 和 Pi。
而是我们开始把代码审查拆成不同责任：
主 Agent 负责调度
第三方模型负责独立发现
确定性工具负责验证
主 Agent 负责最终判断
这已经不再是简单的“换一个模型”。
它更接近一套小型的 Graph Engineering 工作流：
任务进入
→ 选择 Reviewer
→ 多模型独立审查
→ 汇总候选问题
→ 逐条验证
→ 删除重复和误报
→ 输出最终报告
但多 Agent 并不会自动带来更高质量。
真正决定系统可靠性的，仍然是：
当这些基础工作真正做好之后，Codex 才不再只是一个独自工作的超级 Agent。
它开始变成一个能够调度不同模型、不同工具和不同审查路径的 AI 工程团队。
]]>当 Claude Code、Codex、Grok、Gemini、OpenCode 等 AI 编程工具越来越强，开发者面临的问题也在发生变化。
过去，我们关心的是：
哪个模型写代码更强？
现在，一个新的问题逐渐浮现：
当我同时使用多个 AI Agent 时，应该怎样管理它们？
如果让 Claude Code 负责分析，让 Codex 负责实现，让 Grok 负责 Review，再让另一个 Agent 补测试，你很快就会遇到一系列现实问题：
多个 Agent 会不会互相覆盖文件？
不同任务应该使用哪个分支？
谁正在执行，谁已经完成，谁在等待输入？
多个 Agent 给出不同实现后，应该怎样比较？
离开电脑之后，如何继续查看和控制任务？
多个 Claude、Codex 账号以及额度，又该如何管理？
最近我体验了一段时间 Orca。它给我的最大感受是：Orca 并不是想成为一个更强的 AI 编程 Agent，而是在尝试成为多个 AI Agent 之上的管理层。
🚀 本篇笔记所对应的视频：
传统 IDE，例如 VS Code，主要围绕人类开发者设计：
但在 AI Agent 逐渐承担大量编码工作的情况下，开发界面的核心对象正在变化。
开发者不再只是自己编辑代码，还需要同时观察多个 Agent、给它们派发任务、检查执行状态、比较不同结果，并决定最终合并哪个方案。
Orca 将自己定位为一个面向 AI Agent 工作流的开发环境。官方对它的描述是：在同一个桌面 IDE 中并排运行多个 AI 编程 Agent，每项任务拥有自己的 Git worktree、Agent 终端和浏览器环境。它并不是模型，也不会替代 Git，而是运行开发者原本就在使用的 Claude Code、Codex、OpenCode 等 CLI Agent。
换句话说：
VS Code 更像一张给人类使用的办公桌，而 Orca 更像一间用于管理多个 AI 工程师的项目作战室。
假设我们在同一个项目目录中同时运行三个 Agent：
Claude Code：分析认证模块并修改接口
Codex：重构登录流程
Grok：检查安全问题并补充修复
它们很可能同时读取和修改相同文件。
第一个 Agent 读取代码后，第二个 Agent 改写了文件；第一个 Agent 再继续操作时，它所理解的代码状态可能已经过时。
接下来就会出现：
Orca 的核心设计之一，就是让每项任务运行在独立的 Git worktree 中。
每个 worktree 都有自己的：
多个 Agent 即使修改相同路径的文件，也不会直接覆盖彼此的工作。开发者可以让它们从同一个基础版本出发，分别尝试不同方案，最后查看各自的 Diff，选择更好的实现。
这解决的并不只是“分支切换麻烦”，而是多 Agent 并行开发最基础的隔离问题。
只有一个 Agent 时，我们可以盯着终端看它在做什么。
但当 Agent 数量变成五个、十个甚至更多时，情况就完全不同了。
你需要知道：
在我的视频测试中，Orca 左侧侧边栏能够显示不同 worktree 和 Agent 的运行状态；不同 Agent 还可以通过标签页或横向、纵向分屏同时显示。关闭 Orca 中的任务视图后，之前的 worktree、终端内容和任务记录也可以重新恢复。
Orca 还提供了更结构化的 Orchestration 能力。它可以通过消息、Task、Dispatch 和 Decision Gate 等机制协调多个 Agent，而不只是向多个终端随便发送几段 Prompt。官方将 Orchestration 定义为结构化的多 Agent 协调层，用于任务派发、完成状态跟踪、Agent 间消息以及需要人工决策的流程。
可以简单理解为：
Worktree
解决“在哪里工作”
Agent Terminal
解决“由谁执行”
Orchestration
解决“谁做什么、依赖谁、怎样确认完成”
这使多 Agent 工作流从“同时打开几个终端”，逐渐变成一套可管理的执行流程。
不过也需要注意：Orchestration 是协调基础设施，不是一个自动替你完成所有任务拆解、技术判断和代码合并的“AI 主管”。任务边界、验收标准和最终决策，仍然需要开发者负责。
AI 编程发展到现在，代码生成速度已经不是唯一瓶颈。
真正困难的部分越来越像是：
AI 一次生成了几百行甚至几千行修改，我怎样确认它真的做对了？
如果同时运行多个 Agent，这个问题会更加严重。
三个 Agent 分别给出三个实现，并不意味着开发效率自动提升。假如所有修改都混在一个目录里，或者你必须手动来回寻找文件、复制行号、整理反馈，那么并行带来的收益很快会被 Review 成本抵消。
Orca 为每个 worktree 提供独立 Diff，并支持查看暂存、未暂存和新增文件，还提供合并冲突界面以及按行、按代码块暂存等能力。
它的 Annotate AI Diff 功能还允许开发者直接在 Diff 行上留下评论，再把一批评论统一发送给 Agent，让 Agent 根据带有明确代码位置的反馈进行修改。这样就不需要手动复制文件名、行号和代码片段。
这让一种非常有价值的工作流成为可能：
让多个 Agent 从同一版本出发
分别尝试不同方案
查看各自 Diff
选择最好的方向
在 Diff 上批量标注意见
让获胜 Agent 继续修改
最终由人类审查和合并
Orca 官方甚至专门提供了“三个 Agent 竞争同一项任务”的使用方式：同一个 Prompt、三个 worktree、三个 Agent，完成后比较结果并选择获胜方案。
所以 Orca 的价值并不是减少人工 Review，而是让人工 Review 更有组织。
AI Agent 经常需要长时间运行。
它可能在：
如果这时需要开会、出门或换一台设备，传统终端工作流就很不方便。
在这次视频测试中，我将 Orca 桌面端与手机配对后，可以直接在手机上查看不同任务和 Agent 的终端输出，了解它们当前的执行状态。
Orca 官方提供了 iOS 和 Android Mobile Companion。目前移动端仍处于 Beta 阶段，定位也不是完整代码编辑器，而是桌面端的远程控制器。它可以查看 worktree 和 Agent 状态、读取近期终端输出、回复等待输入的 Agent、查看 Source Control、切换账号和创建 workspace。
这意味着，一个比较现实的使用场景是：
在电脑上启动多个 Agent
离开工位去开会
手机收到 Agent 完成或等待输入的通知
查看终端内容
回复“继续”或补充一个要求
回到电脑后集中 Review
它并不是让开发者在手机上完成复杂编码，而是避免长时间 Agent 因为一个简单确认停在那里。
很多重度 AI 编程用户并不只使用一个工具。
常见组合可能是：
Claude Code 负责分析和复杂推理
Codex 负责代码实现
Grok 或 Gemini 负责补充 Review
OpenCode 负责其他模型调用
与此同时，开发者还可能拥有个人账号、公司账号、不同工作区账号，以及 Host、WSL、远程服务器等不同运行环境。
传统做法经常是不断执行：
logout
login
重新选择账号
检查额度
重启 Agent
Orca 可以在状态栏中显示 Claude、Codex 等 Provider 的用量和重置窗口，并提供 Claude、Codex 的账号切换能力。官方说明中，当前用量会跟随活动账户显示，其他已配置账户也可以在账号选择器中查看。
对于 Codex 和 Claude，Orca 可以在不手动修改配置文件的情况下切换活动账号。但已经运行的 Agent 进程通常仍会保留启动时的账号身份，需要重启相应 Session，新的 Session 才会使用切换后的账号。
这项功能看起来不像 worktree 那么醒目，但对于每天高频使用多个 AI Provider 的开发者来说，非常实用。
视频中我还演示了 Orca 的 Tasks 功能。
在 Tasks 页面中，可以选择项目仓库，查看 GitHub Issues 和 Pull Requests。打开一个 Issue 后，可以直接基于它创建 workspace，Orca 会启动对应 Agent，并把 Issue 上下文放入任务输入中。
这样，传统流程：
打开 GitHub
找到 Issue
复制标题和描述
回到终端
创建分支
启动 Agent
粘贴上下文
就可以简化为：
打开 Issue
创建 Worktree
启动 Agent
官方文档也说明，从 GitHub Issue 创建 worktree 时，Orca 会预填任务名称，并把 Issue 与 worktree 关联起来；Tasks 页面还可以浏览 GitHub Projects 中的卡片并从卡片直接创建 worktree。
除了 GitHub，Orca 还支持 Linear、Jira 和 GitLab 等工作项来源，把“任务从哪里来”和“Agent 在哪里执行”连接在一起。
在视频中，我还测试了语音输入。
设置好语音识别模型后，通过快捷键即可直接说出：
对这个项目的代码进行 Review。
识别结果会进入 Codex 的输入框，然后可以直接提交任务。
对于复杂代码需求，键盘输入依然更精确；但对于“继续执行”“检查测试”“总结当前修改”“对这个模块做 Review”一类指令，语音输入确实能够减少操作成本。
视频还演示了自动化功能。例如，可以选择一个仓库、指定 Codex 等 Agent，再设置为每个工作日上午 9 点自动运行 Repo Review。
这意味着 Orca 不只是在管理当前打开的终端，也开始把部分重复性工作转变为可计划的 Agent 任务。Orca CLI 同样提供对 worktree、终端、浏览器和定时自动化的控制能力。
在多 Agent 工作流中，最怕的事情之一是：
我昨天到底在哪个分支、哪个终端里，让哪个 Agent 做到了哪一步？
Orca 会恢复打开的 worktree、终端分屏、滚动记录和聚焦标签页。在宿主机没有重启、后台 PTY 进程仍然存活的情况下，关闭并重新打开 Orca，Agent 进程还可以继续运行并重新连接。
在视频中，我恢复了之前关闭的 oh-my-pi 和 Claude Code 任务。之前的输出内容没有丢失，恢复后还可以继续查看或接着执行。
当你只有一个终端时，这可能只是一个便利功能；但当你同时维护多个 worktree 和多个 Agent 时，它实际上是在保存整个“AI 团队的工作现场”。
虽然 Orca 的功能非常丰富，但它并不是“输入一句需求，就自动完成整个项目”的工具。
官方也明确强调：
它真正擅长的是：
把不同 Agent 放进合适的隔离环境
让多个任务可以并行推进
让状态、上下文和结果更容易被管理
把最终判断权留给开发者
Worktree 隔离也不等于完整安全沙箱。
即使每个 Agent 使用独立目录，Agent 仍然可能执行命令、访问网络、读取凭据或修改 worktree 之外的资源。特别是在启用类似 YOLO 或跳过权限确认的模式时，仍然需要理解相应风险。
此外，更多 worktree、文件监视器、浏览器标签和终端进程也会消耗更多磁盘与内存。官方的故障排查建议同样提到，不再使用的 worktree 和浏览器标签应及时关闭。
我认为，Orca 特别适合下面几类开发者。
第一类，是已经同时使用 Claude Code、Codex、OpenCode 等多个 CLI Agent 的人。
第二类，是经常需要让多个 Agent 并行尝试同一个问题，并对不同结果进行比较的人。
第三类，是在多个功能分支、多个 Issue 和多个 PR 之间频繁切换的人。
第四类，是需要通过 SSH 或远程开发机运行长时间 Agent 任务的人。Orca 可以在远程主机创建 worktree 和运行 Agent，同时在本地继续使用编辑器与 Diff 界面。
第五类，是认为“生成代码已经很快，但管理、Review 和合并 AI 代码越来越累”的人。
相反，如果你平时只运行一个 Agent、一次只处理一个小任务，并且不需要多分支并行，那么 Orca 带来的收益可能没有那么明显。
过去两年，AI 编程工具之间的竞争主要围绕：
但随着模型能力逐渐提高，另一个竞争维度也会越来越重要：
谁能更好地组织多个 Agent 工作？
未来的开发方式可能不再只是：
一个开发者
+
一个 AI 助手
而是：
一个开发者
管理多个拥有不同能力的 AI Agent
让它们在隔离环境中并行工作
通过结构化流程交付结果
最终由人类 Review 和决策
从这个角度来看，Orca 真正想解决的，并不是“怎样让一个 AI 写代码更快”。
而是：
当一个人开始管理一支 AI 工程团队时，需要怎样的开发基础设施？
这也正是我认为 Orca 最值得关注的地方。
]]>GPT-5.6 系列终于正式发布了。
这次 OpenAI 一共推出了三个型号：面向复杂任务的 Sol、主打平衡的 Terra，以及追求速度和成本的 Luna。
从官方公布的数据来看，GPT-5.6 Sol 在终端操作、浏览器自动化、长上下文和 Agent 任务上的表现都非常突出，部分成绩甚至超过了 Claude Fable 5 和 Claude Mythos 5。
但跑分表只能告诉我们模型在标准化测试中拿了多少分，无法回答一个更实际的问题：
把一个真正复杂的任务交给它，它到底能不能做出来？
为了弄清楚这一点，我没有只让它写几个函数或者生成一个简单网页，而是连续安排了九组难度完全不同的任务：
测试完成以后，我对 GPT-5.6 Sol 最大的感受，不是它突然变得无所不能了。
而是它越来越像一个能够接手完整项目的人。
它仍然会犯错，也会误解指令，甚至会为了尽快完成任务主动寻找捷径。但只要任务目标足够清楚，它确实比过去的大多数模型更愿意继续追踪问题，把代码、测试、功能和最终交付一起做完。
🚀 本篇笔记所对应的视频：
GPT-5.6 Sol 发布后，OpenAI 同时推出了 Max、Pro、Ultra 等不同名称，很容易让人误以为它们是不同模型。
其实不是。
GPT-5.6 Sol 支持多档推理强度：
none、low、medium、high、xhigh、max
推理强度越高，模型能够用于分析问题的时间和计算量越多，但延迟和 Token 消耗也会随之增加。
我在这次测试中，大部分复杂任务使用的都是 Extra High。
它适合大型代码开发、复杂逻辑推理、跨文件修改和需要反复验证的任务，但完全没有必要用来修改按钮颜色或者调整一段文案。
Pro 更重视最终答案的质量，而不是速度和成本。
它更适合架构设计、安全审查、复杂研究，以及做错一次就会造成很大损失的任务。
Ultra 默认由多个 Agent 并行处理任务，再由主 Agent 汇总结果。
它和 Max 的区别非常明显：
如果任务可以拆成前端、后端、数据库和测试四个独立方向，Ultra 会很有价值。
但如果只是修改同一个文件，让四个 Agent 同时工作，往往只会产生重复劳动、上下文膨胀和修改冲突。
OpenAI 没有公布 GPT-5.6 Sol 的参数量、训练规模和具体架构。
目前能够确认的主要参数包括：
上下文窗口：1,050,000 Tokens
最大输出：128,000 Tokens
官方模型资料标注的知识截止日期：2026 年 2 月 16 日
输入类型：文本、图片
输出类型：文本
暂不支持：音频输入、视频输入和微调
API 模型名称：gpt-5.6-sol
它还支持网页搜索、文件搜索、代码解释器、Hosted Shell、Computer Use、MCP、Skills、图像生成、Apply Patch 和 Tool Search 等工具。
GPT-5.6 Sol 的标准 API 价格为：
这里还有一个容易被忽略的细节。
当单次请求的输入超过 272K Tokens 后，整个请求都会进入长上下文计价区间，输入和输出价格都会进一步上涨。
所以百万上下文并不意味着应该把整个代码仓库、几十份 PDF、所有日志和历史对话一次性全部塞进去。
它解决的是“放不下”的问题，却无法自动解决“内容太乱”和“重点不突出”的问题。
我首先在 ChatGPT 网页版中询问了两个问题：
第一，它的知识截止日期是什么时候？
第二，它知道的日本最新首相是谁？
网页端给出的回答是，知识截止日期为 2025 年 12 月，同时也正确回答了当时的日本首相。
至少从这个简单测试看，它对近期政治信息的覆盖没有出现明显断层。
但这里也暴露出一个值得注意的问题：
模型自己回答的知识截止日期，和官方模型资料中的日期并不完全一致。
这说明我们不能单纯依赖模型自报身份、版本和知识截止日期。真正需要确认模型参数时，仍然应该以官方模型卡和 API 文档为准。
模型可以回答自己是谁，但它对自身运行环境的描述不一定永远准确。
第一道真正的能力测试，是让 GPT-5.6 Sol 使用 SVG 制作一段动画：
一只几维鸟、一只渡渡鸟和一只鹈鹕，分别骑着自行车在土星环上比赛。
我还要求：
最终生成的结果总体不错。
土星、土星环和背景中的几颗行星都被画了出来，鹈鹕和渡渡鸟的外形也比较容易辨认。自行车车轮会持续转动，而且不同车辆还表现出了不同的运动速度。
不过，它犯了一个非常明显的错误：
几维鸟是倒着骑自行车的。
几维鸟最长、最明显的嘴部应该朝向前进方向，但它生成的身体朝向刚好相反。
这次测试说明，GPT-5.6 Sol 已经能够同时处理：
但它对角色朝向和生物结构的理解还不够稳定。
单从最终视觉效果来看，这次生成结果已经可以使用，不过和我之前测试 Claude Fable 5 时得到的版本相比，细节和整体完成度仍然略逊一筹。
第二道 SVG 测试更加困难。
我要求它制作一段男性使用复合弓射箭的动画，并且必须表现出：
结果一开始就出现了问题。
尽管提示词里明确要求使用 SVG，它第一次仍然直接调用了图像生成工具，给我生成了一张静态图片。
我再次强调：
用 SVG，不是用图像生成。
第二次它才真正生成了可运行的 SVG 动画。
修正后的结果包含了拉弓特写、滑轮转动、放箭、箭矢飞行和命中靶心等完整过程，还加入了动画进度显示。
从功能完整性来看，它确实理解了我想要的整个过程。
但在物理结构上仍然有一个严重问题：
它把复合弓拿反了，弓片弯曲的方向也是反的。
这次测试暴露了 GPT-5.6 Sol 的两个短板。
第一，它有时会根据任务内容自行选择工具，即使这个选择和提示词里的明确要求冲突。
第二，它可以生成“看起来像那么回事”的物理动画，却不一定真正理解机械结构中的受力方向。
箭能够飞出去，滑轮也会转，靶心也能命中。
但这些元素组合在一起，不代表物理关系一定正确。
接下来，我把逻辑推理和动画生成结合在了一起。
题目是一个经过扩展的农夫过河问题。
农夫需要把老虎、羊、蛇、鸡和一筐苹果安全送到对岸，但船每次只能搭载农夫和一样东西。
同时存在三组特殊关系：
普通的大模型测试，通常只需要输出一段文字步骤。
这次我要求 GPT-5.6 Sol 不仅要推导出正确方案，还要使用 SVG 动画完整演示整个过河过程。
最终，它给出的主要顺序是：
这套顺序是成立的。
更重要的是，它没有只输出几个移动的小圆点，而是做出了一个完整场景：
这次结果让我比较意外。
因为模型必须先完成逻辑推理，再把推理结果转换成时间轴，最后还要把每一步对应到 SVG 动画状态。
它唯一比较明显的 Bug，是农夫独自划船返回时，整个人会变成倒立状态。
原因很可能是模型为了复用同一个角色元素，直接使用了整体翻转，而没有单独处理人物朝向。
但除了这个问题，整段动画的推理顺序、场景元素和播放流程都比较完整。
在我看来，这个案例比单纯让模型回答一道逻辑题更有价值。
因为它不只证明了模型“知道答案”，还证明了它能够把答案转换成一个真正可运行、可观察的产品。
完成 SVG 测试后，我继续加大难度，让它使用 Three.js 创建波音 747-8 洲际客机的三维模型。
要求包括：
等待几分钟后，它生成了一个可以直接运行的版本。
外部视角下，可以对飞机进行 360 度旋转和缩放。机身、机翼、尾翼和四台发动机都已经具备，整体轮廓也能看出波音 747-8 的特征。
点击“进入机舱”后，视角会切换到飞机内部。
用户可以在机舱中转动视角和前后移动，内部也确实包含座椅、窗户和过道。
不过它实现的过道明显过于狭窄，部分座椅和机舱空间比例也不够合理。
这说明它已经能搭建完整的三维交互体验，但距离精准的工业建模还有很大差距。
如果目标是展示概念、制作网页 Demo 或快速验证交互方式，这个结果已经足够。
如果要还原真实飞机尺寸、空气动力学结构或者舱内布局，就必须提供更严格的尺寸数据和参考模型。
网页端的测试主要集中在 SVG 和 Three.js。
进入 Codex 后，我决定把难度再提高一个等级。
过去测试大模型的游戏开发能力时，我经常使用 Three.js。但对现在的模型来说，使用 Three.js 制作一个网页小游戏已经不算特别困难。
所以这一次，我改用 Godot 4。
第一个任务，是开发一款可以直接运行的 3D 侏罗纪坦克射击游戏。
游戏设定是：
玩家驾驶一辆现代坦克进入侏罗纪时代，通过鼠标控制炮塔和准星，可以射击恐龙、翼龙、树木、石头以及突然出现的 UFO。
我只提前创建了一个空的 Godot 3D 项目，然后把需求完整交给 Codex。
大约半小时后，游戏已经能够直接运行。
进入场景以后，可以看到一辆完整的 3D 坦克。键盘可以控制前进、后退和转向，鼠标能够控制炮塔方向，点击后会发射炮弹。
炮弹击中树木后，树会倒下。
场景里还出现了多种不同外形的恐龙和天空中的翼龙。玩家可以驾驶坦克在地图中寻找并攻击这些目标。
更出乎意料的是，它还实现了随机出现的 UFO。
UFO 不只是一个装饰模型，而是会主动攻击玩家。坦克可以转动炮塔进行还击，命中后 UFO 会坠落并发生爆炸。
它还加入了环境音效、射击音效、爆炸效果，以及不同类型的恐龙模型。
这个项目当然还称不上完整商业游戏。
画面精细度、敌人 AI、碰撞反馈和关卡设计都有提升空间。
但它已经不是一段用来演示语法的代码，而是一款具备基本循环的游戏原型：
移动、瞄准、射击、敌人攻击、目标被摧毁、爆炸反馈。
从一个空的 Godot 项目到能够运行的三维射击原型，大约用了半小时。
这已经足以说明，GPT-5.6 Sol 的优势不是只会生成某一段代码，而是能够在一个真实工程里持续创建场景、脚本、节点和交互逻辑，最后把它们拼成一个完整结果。
完成侏罗纪坦克游戏后，我又测试了一个相反的方向。
前一个任务的提示词非常详细，几乎把玩法、操作方式和场景元素都规定好了。
这一次，我故意只给它一个很短的任务：
使用 Godot 4 开发一款可以直接运行的 3D 空战原型。玩家驾驶 A-10 攻击机，可以攻击地面的坦克和装甲车，需要模拟导弹发射和机炮射击，其余部分由模型自行发挥。
大约 20 分钟后，项目完成。
游戏支持第三人称和第一人称视角切换。
飞机可以：
画面中还会实时显示飞机速度。
第一人称座舱视角的效果尤其不错，导弹发射、飞行和爆炸也已经形成完整反馈。
测试过程中，我还因为操作失误直接撞到了地面。这从另一个侧面说明，它确实实现了飞机和地形之间的碰撞，而不只是播放一段预设动画。
这个案例说明，GPT-5.6 Sol 不仅能够根据详细规格执行，也能够在提示词非常简短的情况下自行补全大量设计。
但这并不意味着提示词越短越好。
提示词越短，模型发挥空间越大，结果也越不可控。
如果只是做创意原型，这种自主发挥非常有价值。
如果开发的是正式产品，仍然应该明确规定控制方式、核心玩法、性能要求、代码结构和验收标准。
整个测试中，最复杂、也最有代表性的案例，是一套原生 iOS 背单词产品。
这次我没有让它开发一个只有几个页面的小型 MVP，而是明确告诉它：
除非遇到无法解决的技术障碍，否则不要主动缩小范围，尽可能实现接近最终产品的体验。
整个产品包含三个部分：
Chrome 扩展负责用户阅读英文网页时的取词。
用户双击不认识的单词后，扩展需要显示：
用户可以把这些单词保存到 Supabase。
iOS App 再从 Supabase 中读取词库，并根据用户保存的单词生成学习计划。
更复杂的是，我还要求它把用户学过的单词随机组合起来，通过 OpenRouter 调用大模型生成一篇英文短文，让这些单词自然地出现在文章中，帮助用户在语境中强化记忆。
App 使用 Swift 和 SwiftUI 开发。
整个开发过程持续了一个多小时，中间也不是完全一次成功。我让 Codex 继续修复了多轮 Bug，才最终得到能够完整运行的版本。
这一点必须说清楚：
它不是一句提示词下去，几分钟后就凭空变出一个完全无 Bug 的商业产品。
但真正重要的是，它在遇到问题后没有停在一个残缺版本，而是继续修改，最终把整条产品链路跑通了。
App 首先实现了注册和登录。
用户创建账号后，首页会显示当前词库、学习进度和学习状态。
Chrome 扩展也可以登录同一个账号，并提供：
我在一篇英文文章中连续双击了多个单词。
扩展能够弹出翻译卡片，显示单词在当前句子中的具体意思，而不只是给出脱离语境的词典解释。
随后，我把八个单词保存到了词库。
回到 iOS App 后，这八个单词已经同步出现。
点击开始学习后，App 会自动创建一轮学习计划。
每个单词不仅包含中文解释，还会显示用户当时在网页中看到它的原始句子。
这点非常重要。
很多背单词软件只保存单词本身，过几天后用户已经忘记当时为什么查这个词。
保留原始网页语境，可以让记忆重新和具体阅读场景建立联系。
完成单词学习后，用户可以选择文章主题，再点击“生成专属短文”。
我选择了四个刚刚学习的单词。
生成完成后，这四个单词都自然出现在短文中，并且被高亮显示。
页面还支持：
其中朗读功能的声音比较机械，明显使用的是系统级语音合成。
这也是整个产品中比较明显的不足。
后续可以将它替换成质量更高的大模型语音 API，让长文章朗读听起来更自然。
读完短文后，App 会自动进入巩固练习。
它实现了：
我实际录入了一句英文，App 成功识别出了说话内容。
完成整轮学习后，它还会生成学习总结，显示：
词库页面中，每个通过 Chrome 扩展保存的单词也可以单独打开，查看解释和原始语境。
这个项目最有价值的地方，不是某一个页面设计得多漂亮。
而是 GPT-5.6 Sol 打通了完整的数据链路：
网页取词 → Chrome 扩展 → Supabase → iOS App → 学习计划 → 大模型生成短文 → 练习 → 学习总结。
它同时处理了：
从最终完成度来看，这一次 GPT-5.6 Sol 开发的版本，甚至比我之前使用 Claude Fable 5 开发的版本更完整。
提示词中要求的大部分功能都实现了，其中一些学习流程和交互细节还超出了我原本的预期。
当然，这仍然是原型，而不是可以直接上架的正式产品。
真正发布前，还需要继续处理：
但它已经证明了一件事：
复杂 Agent 模型正在从“帮你写代码”，走向“帮你搭建产品”。
最后，我测试了 GPT-5.6 Sol 的浏览器自动化能力。
我让 Codex 接管浏览器，进入 Tinkercad，创建一个简单的房屋三维模型。
它首先进入 3D 设计工作区，然后开始寻找可以使用的元素。
原本我以为它会使用立方体、屋顶、门窗等基本几何体，从零搭建一座房子。
但它很快清空了当前内容，在搜索框中直接搜索“房子”，找到一个现成房屋模型，拖到工作区，再对尺寸和参数进行调整。
最后，它保存了这个房屋模型，并告诉我任务已经完成。
这个结果非常有意思。
从任务目标来看，我只要求它“创建一个简单的房子模型”，并没有明确规定必须从几何体开始搭建。
所以它并没有违反指令。
它只是发现了一条更快完成目标的路径。
这说明 GPT-5.6 Sol 已经不再机械地把每一个动作都从头执行，而是会观察环境、寻找现有资源，再选择成本更低的方案。
但这个案例也带来了一个非常重要的提醒：
模型完成了任务，不代表它使用的是你预期的方法。
如果我的真实目的不是得到一座房子，而是测试它能否使用基本几何体完成建模，那么提示词中就必须明确写出：
否则，模型会优先优化最终结果，而不是遵循你脑海中没有写出来的过程。
把 SVG、Three.js、Godot、iOS 和浏览器自动化放在一起看，GPT-5.6 Sol 的特点已经非常明显。
过去使用代码 Agent，经常会遇到一种情况：
模型完成了表面修改，测试还没跑完，边界条件没有处理，文档也没有同步，然后就告诉你任务已经完成。
GPT-5.6 Sol 更愿意继续追踪问题。
尤其是在 iOS App 开发中，它经历了一个多小时和多轮 Bug 修复，最终仍然把 Chrome 扩展、Supabase、SwiftUI 和大模型接口连接了起来。
它不是不会失败。
它的提升在于，失败后更愿意继续做。
很多模型可以单独写一个 SwiftUI 页面，也可以单独写一个 Chrome 扩展。
真正困难的是把这些部分连接起来。
Sol 在这次测试中表现最突出的能力，正是把不同技术栈组合成一个完整工作流。
它不是只生成一堆互不相关的文件，而是尝试让数据真正从一个系统流向另一个系统。
A-10 游戏的提示词非常短，但它主动补充了：
这种自主性在创意原型中非常有价值。
但在正式项目中，也意味着必须提前写清楚边界。
几维鸟倒着骑车、复合弓方向错误、弓片弯曲方向错误、农夫返回时倒立、飞机机舱过道过窄。
这些错误有一个共同特点：
模型实现了主要功能，却没有完全理解现实世界中的结构、比例和方向。
所以在涉及机械、建筑、医学、工程和真实物理结构时，不能因为动画“能动起来”，就默认它是正确的。
Tinkercad 房屋模型是最直观的例子。
它没有从零搭建，而是直接搜索现成模型。
这和 METR 测试中发现的某些行为虽然性质不同，但背后有一个相似点：
模型会主动寻找最快满足完成条件的路径。
这不一定是坏事。
在人类工作中，复用现成资源本来就是一种效率。
问题在于，如果某些路径不能使用，就必须提前写进约束，而不能指望模型自行理解。
GPT-5.6 Sol 在 Terminal-Bench 2.1 中获得 88.8 分，Ultra 模式达到 91.9。
它在 DeepSWE、BrowseComp 和 OSWorld 等涉及终端、网页和计算机操作的测试中也表现突出。
这些结果和我的实际体验基本一致。
Sol 最强的并不是单次代码补全，而是：
但在 SWE-Bench Pro 中，Sol 的成绩仍然明显落后于 Fable 5。
Artificial Analysis 的综合测试中，Sol Max 也没有全面超过 Fable 5。
这说明它并不是在所有任务中都更聪明。
我的判断是：
Sol 更擅长把东西做出来，而且做得完整、可运行；Fable 5 在部分需要细腻理解、代码可读性和严密分析的任务中，仍然可能更强。
这两个模型并不是简单的上下级关系，而是工作风格不同。
Sol 的自主性很强。
如果不给出验收标准，它会自己判断什么叫完成，而这个判断不一定和你相同。
一个完整任务至少应该写清楚：
Tinkercad 案例里，我只规定了结果，没有规定过程，所以它直接复用了现成模型。
以后可以把约束分成两类。
结果约束：
过程约束：
只写结果，模型会寻找最快路径。
结果和过程都写清楚，才能得到真正符合预期的交付。
不要让模型只说“已经完成”。
应该要求它：
在 iOS App 项目中，真正有价值的并不是它生成了多少代码，而是最后确实完成了注册、取词、同步、文章生成和练习流程。
普通代码修改和文档整理，Medium 或 High 通常已经足够。
Max 更适合复杂架构、疑难故障和高风险决策。
Ultra 则只适合能够真正并行拆分的任务。
模型越强，越要学会控制计算量，而不是无脑把所有选项开到最高。
目前更务实的方式，不是寻找一个包打天下的模型，而是按照任务路由：
可以先让 Fable 5 设计架构，再让 Sol 实现。
也可以先让 Sol 完成产品，再让 Fable 5 进行代码审查。
模型之间的竞争，正在逐渐变成不同工序之间的分工。
你是本项目的交付负责人，不是只提供建议的顾问。
目标：
[写清楚最终需要解决的问题]
最终交付物：
[代码、文件、报告、应用或可运行项目]
技术要求：
[技术栈、平台、依赖和版本]
必须实现：
1. [核心功能]
2. [核心功能]
3. [核心功能]
禁止事项：
1. [不能使用的捷径]
2. [不能修改的内容]
3. [未经批准不能执行的操作]
验收标准：
1. 项目可以实际运行或构建。
2. 必须执行相关测试。
3. 必须验证主要用户流程。
4. 不得只根据代码推测功能可用。
5. 必须列出仍然存在的问题。
工作规则：
1. 先检查现有项目和环境。
2. 制定实现计划，再开始修改。
3. 遇到错误后继续定位和修复。
4. 涉及删除数据、发布、付款或生产环境时，必须暂停。
5. 最终只交付完成结果、验证记录、已知问题和后续建议。
这套模板最重要的不是让提示词变长。
它真正解决的是四个问题：
什么才算完成，哪些捷径不能走，什么时候必须停下来，以及最后拿什么证明结果可信。
完成这九轮测试后，我认为 GPT-5.6 Sol 并不是一个在所有方面都碾压其他模型的“全能模型”。
它会把几维鸟画反，会把复合弓拿反，会让农夫倒立，也会在 Tinkercad 里直接找一个现成房子交差。
但与此同时，它也能在半小时内做出一款可玩的 Godot 三维射击游戏，在简短提示词下自行补全空战玩法，还能持续一个多小时，把 Chrome 扩展、Supabase、SwiftUI 和大模型 API 连接成一套真正能够运行的学习产品。
这就是 GPT-5.6 Sol 最值得关注的地方。
过去，我们判断一个模型好不好，主要看它能不能给出正确答案。
现在，更值得问的问题变成了：
它能不能在长时间工作后仍然记得最初目标？
能不能自己发现缺失的功能？
能不能在遇到 Bug 后继续修复？
能不能把代码、界面、数据库、测试和最终交付连在一起？
能不能真正运行项目，而不只是生成几段看起来合理的代码？
从这次测试来看，GPT-5.6 Sol 已经越来越接近一个能够负责完整交付的 Agent。
它不一定是每一道题里最聪明的学生。
但在真实工作中，它可能是那个最愿意把项目做完、把现场收拾干净，最后还回来检查一遍的人。
而这，往往比跑分多拿几分更重要。
本文基于截至 2026 年 7 月 10 日的公开资料和实际测试结果整理。不同账户、运行环境、推理级别和工具权限可能导致结果存在差异。
]]>AI 编程工具越来越强，但问题也越来越现实：我们到底要不要让 Claude Code、Codex、Gemini 这类 agent 直接跑在自己的电脑上？它们能读项目、执行命令、安装依赖、访问网络，效率很高，但风险也不小。Docker Sandboxes 的定位就是给这些 AI agent 提供一个隔离运行环境：让 agent 能开发、能跑命令、能装依赖，但不要默认拥有整台电脑的访问能力。
Docker 官方文档里对 sbx 的定位很清楚：它是 Docker Sandboxes 的 CLI。你可以用它启动 agent、管理 sandbox、控制网络访问、挂载项目目录、转发端口、保存 secret，甚至让 agent 在 sandbox 内使用独立 Docker daemon 构建镜像。更重要的是，Docker Desktop 不是使用 sbx 的必要条件。
brew trust docker/tap
brew install docker/tap/sbx
sbx login
cd ~/my-project
sbx run claude
sbx login 会打开浏览器，让你用 Docker 账号登录。第一次登录或重置策略后，CLI 会让你选择默认网络策略：Open、Balanced、Locked Down。官方建议多数开发工作从 Balanced 开始，因为它默认拒绝未知出站流量，但允许常见开发站点、AI Provider、包管理器、代码托管、容器 registry 等。
winget install -h Docker.sbx
sbx login
cd ~/my-project
sbx run claude
Windows 用户同样通过 sbx login 登录，然后进入项目目录启动 agent。常规体验和 macOS 类似。
curl -fsSL https://get.docker.com | sudo REPO_ONLY=1 sh
sudo apt-get install docker-sbx
sudo usermod -aG kvm $USER
newgrp kvm
sbx login
cd ~/my-project
sbx run claude
Linux 上需要注意 KVM 权限。执行 usermod -aG kvm 后，需要重新登录，或者用 newgrp kvm 让当前 shell 立即获得权限。
启动一个 Claude Code sandbox：
sbx run claude
查看已有 sandbox：
sbx ls
停止 sandbox，但保留状态：
sbx stop <sandbox-name>
删除 sandbox，彻底清理它的内部状态：
sbx rm --force <sandbox-name>
进入 sandbox shell：
sbx exec -it <sandbox-name> bash
官方文档给出的基本生命周期就是：run 启动，ls 查看，stop 暂停，rm 清理。要记住，stop 只是停掉，状态还在；rm 才是删除。删除 sandbox 后，里面安装的包、内部 Docker images、containers、volumes 都会一起消失。但如果你使用的是 direct mount 模式，agent 已经写到 host 项目目录里的文件不会因为 sbx rm 被删除。
默认情况下，sbx run claude 会根据 agent 和工作目录生成名字，比如 claude-test。但更推荐显式命名：
sbx run claude --name myproject-claude
之后你可以从任意目录重新连接：
sbx run --name myproject-claude
如果你想对同一个项目跑多个实验，也可以起不同名字：
sbx run claude --name feature ~/my-project
sbx run claude --name spike ~/my-project
两个 sandbox 可以挂载同一个 workspace，但它们的内部状态彼此独立。
这是很多人第一次会踩坑的地方。sbx run 有自己的参数，Claude Code 也有自己的参数。要把参数传给 sandbox 里的 Claude Code，需要用 -- 分隔：
sbx run claude -- --dangerously-skip-permissions
规则是：
sbx run claude [sbx自己的参数] -- [传给claude的参数]
例如：
sbx run claude --name claude-test -- --dangerously-skip-permissions
--dangerously-skip-permissions 不是 sbx 的参数，而是 Claude Code 的参数。如果少了中间的 --，sbx 会报：
ERROR: unknown flag: --dangerously-skip-permissions
需要注意的是，在 sbx 里用这个参数，风险确实比直接在 host 上小，但并不是零风险。Direct mount 模式下，Claude Code 仍然可以修改当前挂载进去的项目文件。
默认是 Direct Mode。你在项目目录里运行：
cd ~/Projects/myproject
sbx run claude
这时当前项目目录会被直接挂进 sandbox。Claude 改文件，host 上立即可见。这个模式最适合日常开发，尤其是 macOS/iOS 项目：Claude 在 sandbox 里改代码，Xcode 在 host 上构建和运行。
更隔离的方式是 Clone Mode：
cd ~/Projects/myproject
sbx run --clone claude
Clone Mode 会在 sandbox 里创建一个私有 Git clone，host 仓库以只读方式挂载。agent 的提交可以通过 host 上的 sandbox-<name> remote 拉回来。这个模式适合高风险重构、并行任务、探索性修改。缺点是 host 工作区不会立即看到改动，需要 git fetch sandbox-<name> 取回。
Direct Mode 简单高效，Clone Mode 隔离更强。个人日常开发建议默认 Direct Mode；不确定 agent 会不会大改时，再用 --clone。
你可以给 sandbox 挂多个目录：
sbx run claude ~/project-a ~/shared-libs:ro ~/docs:ro
第一个路径是主 workspace，agent 会从这里启动。后面的路径是额外 workspace。加 :ro 表示只读挂载，适合挂文档、参考代码、公共库，避免 agent 误改。
不建议把整个 ~/Projects 或 ~ 都挂进去。更安全的做法是：每个项目进入自己的目录启动，让 sandbox 只看到当前项目和必要的只读参考资料。
sandbox 默认是网络隔离的。agent 在里面启动了开发服务器后，host 浏览器不能直接访问。需要发布端口：
sbx ports my-sandbox --publish 8080:3000
open http://localhost:8080
也可以让系统自动选择 host 端口：
sbx ports my-sandbox --publish 3000
sbx ports my-sandbox
停止转发：
sbx ports my-sandbox --unpublish 8080:3000
这对前端项目、API 服务、文档站点都很实用。
如果文件不在挂载的 workspace 里，可以用 sbx cp：
sbx cp ./config.json my-sandbox:/home/user/
sbx cp my-sandbox:/home/user/output.log ./
sbx cp ./src/ my-sandbox:/home/user/src
注意，复制时必须有一端使用 SANDBOX:PATH 形式。Docker 文档也说明，不支持直接在两个 sandbox 之间复制。
sbx 的网络策略非常重要。官方文档说明，sandbox 出站 HTTP/HTTPS 流量会通过 host 上的代理执行访问规则。第一次登录时可以选择 Open、Balanced、Locked Down。
手动初始化策略：
sbx policy init balanced
允许访问某个域名：
sbx policy allow network api.anthropic.com
阻止某个域名：
sbx policy deny network ads.example.com
只对某个 sandbox 生效：
sbx policy allow network --sandbox my-sandbox api.example.com
一次允许多个：
sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org"
查看策略：
sbx policy ls
如果公司启用了组织级治理，local policy 会失效。Docker FAQ 明确说，组织管理员可以通过 Docker Admin Console 集中管理网络和文件系统策略；当组织治理开启时，它会替代本机 sbx policy 规则，本地规则不再参与评估。这是付费组织治理能力，适合团队统一管控 agent 能访问什么、能挂载什么路径。
很多 agent 需要 Anthropic、OpenAI、GitHub 等 token。sbx secret 用来管理这类凭据。
例如给后续新 sandbox 配 GitHub token：
echo "$(gh auth token)" | sbx secret set -g github
-g 表示 global，对未来创建的 sandbox 生效。已有 sandbox 不会自动拿到新的 global secret，需要单独配置。
如果你只想在当前 shell 临时传入，也可以用环境变量配合 sbx run。如果某个环境变量不是 sbx secret 支持的服务类型，Docker FAQ 建议写入 sandbox 内的 /etc/sandbox-persistent.sh，让它在 sandbox 生命周期内持久生效。
sandbox 里的 Claude Code 不等于 host 上的 claude。如果你卸载了 host 上通过 Homebrew 安装的 Claude Code，sbx run claude 仍然使用自己的 template。
查看 template：
sbx template ls
删除旧 Claude template，让下次重新拉取：
sbx template rm docker.io/docker/sandbox-templates:claude-code-docker
或者用 IMAGE ID 删除：
sbx template rm 9a3bab17aae9
更新当前已有 sandbox 里的 Claude Code：
sbx exec <sandbox-name> claude --version
sbx exec <sandbox-name> claude update
sbx exec <sandbox-name> claude --version
如果你想让以后新建 sandbox 默认更新，通常做法是删除旧 sandbox 和旧 template，再重新 sbx run claude。不要轻易用 sbx reset，它会清更多状态，包括 sandboxes、cache、policy、secret、登录状态等。
Docker FAQ 说明，sbx CLI 会收集基础使用数据，例如运行了哪个命令、成功还是失败、耗时、登录用户名等；同时也说明 Docker Sandboxes 不会监控 session、不会读取 prompts、不会访问代码。
如果要关闭 analytics：
export SBX_NO_TELEMETRY=1
为了长期生效，写进 zsh 配置：
echo 'export SBX_NO_TELEMETRY=1' >> ~/.zshrc
source ~/.zshrc
验证：
echo $SBX_NO_TELEMETRY
应输出：
1
如果 sbx daemon 已经在没有这个变量的环境下启动，可以重启一次：
sbx daemon stop
SBX_NO_TELEMETRY=1 sbx daemon start -d
列出 sandbox：
sbx ls
删除不用的 sandbox：
sbx rm --force claude-test1 claude-untitled-folder
删除所有 sandbox 前，先确认列表：
sbx ls
再谨慎执行：
sbx rm --force $(sbx ls | awk 'NR>1 {print $1}')
如果使用 --clone，删除前一定要确认改动已经 fetch 回 host 或 push 到远端。Docker 文档提醒，删除 clone-mode sandbox 会一起删除 sandbox 内的 clone；未 fetch 或未 push 的提交会丢失。
Docker Sandboxes 的核心价值，不是让 AI agent 变得“绝对安全”，而是把风险控制在更清晰的边界里。它让 Claude Code 这类工具仍然能读写项目、安装依赖、运行服务、构建容器，但不再默认拥有整台电脑的访问面。个人开发可以用 Direct Mode 获得最高效率；高风险任务可以用 Clone Mode；团队环境可以通过组织级 policy 和 audit log 做统一治理。
如果你准备长期使用 AI 编程工具，sbx 很适合成为默认入口：项目进目录，执行 sbx run claude，需要跳过 Claude Code 内部确认就用 -- 传参，需要隔离就加 --clone，不用的 sandbox 及时 sbx rm。掌握这些命令之后，AI agent 的效率和安全边界会同时变得更可控。
它有点特殊。
特殊在于，它不是 MCP，也不是 Skills，也不是普通的 Subagent，更不是 Agent Teams。
更特殊的是：它已经出现在 Claude Code 的二进制实现里，也可以实际运行，但官方公开文档里还没有正式说明。甚至在 Claude Code 2.1.147 的发布信息中，Workflow 曾短暂出现过，随后又被移除。
所以今天这篇文章不会把它包装成”官方正式发布的新功能”。更准确地说：
Workflow 是 Claude Code 里已经可用、但仍处于隐藏/实验状态的多 Agent 编排能力。
如果你平时已经在用 Claude Code、Subagents、Skills 或 Agent Teams，那么 Workflow 值得重点关注。它可能是继 MCP 和 Skills 之后，Claude Code 生态里又一个非常关键的能力方向。
🚀 本篇笔记所对应的视频：
一句话解释：
Workflow 是用 JavaScript 脚本来编排多个 Claude Code agent 的机制。
以前我们让 Claude Code 做复杂任务，通常是这样说：
请你先分析代码，再找风险，再给出修复方案。
这本质上还是自然语言驱动。模型会自己决定怎么拆任务、什么时候派 subagent、如何汇总结果。
Workflow 不一样。
它把这个过程写成代码：
phase("Review")
const results = await Promise.all([
agent("检查 correctness 风险", { label: "correctness-reviewer" }),
agent("检查 security 风险", { label: "security-reviewer" }),
agent("检查 testing 覆盖", { label: "test-reviewer" }),
])
phase("Aggregate")
const final = await agent(
`请汇总这些结果：${JSON.stringify(results)}`,
{ label: "aggregator" },
)
return final
也就是说，Workflow 做的不是”再多叫几个 agent”，而是把多 Agent 的调用顺序、并行关系、阶段划分、输出格式和最终聚合，都变成可复用的脚本。
这就是它真正重要的地方。
很多人第一次看到 Workflow，可能会问：Claude Code 不是已经有 Subagents 和 Agent Teams 了吗？为什么还需要 Workflow？
可以这样理解。
Subagent 很适合临时委派。
比如：
它的优点是简单、自然、启动成本低。
但它的问题也明显：整个流程主要还是模型临场决定。今天它这么拆，明天可能换一种拆法；这次它记得验证，下次可能跳过验证。它适合”临时任务”，不太适合沉淀成稳定流程。
Agent Teams 更像一个多 agent 协作界面。
你可以让不同角色并行工作，人类再去调度、查看、接管。它适合交互式协作，适合长期多角色任务。
但如果你要的是一个可以反复跑的”工程流水线”，Agent Teams 仍然偏交互，不够脚本化。
Skills 更像”能力包”。
它告诉模型：
Skills 的优势在于分发、说明、触发、上下文封装。
但 Workflow 的优势在于执行编排。
所以更准确的关系不是”Workflow 取代 Skills”，而是：
Skills 负责封装和分发，Workflow script 负责执行真正的多 Agent 工作流。
未来很可能出现这种形态：
my-review-skill/
SKILL.md
workflows/
sharded-review.workflow.mjs
pr-review.workflow.mjs
examples/
report.md
Skill 告诉 Claude Code 什么时候用；Workflow 负责把流程跑起来。
这是我测试之后最深的感受。
普通 prompt 是一次性的。
Subagent 是临时派生的。
Agent Teams 更偏人工调度。
但 Workflow script 可以沉淀下来。
一旦某个脚本在某类任务上跑得不错，后续你就可以复用它完成类似任务。
比如：
你不需要每次重新描述完整流程。你只需要保存脚本，下次换一个仓库、换一个主题、换一个 PR，再把参数改掉即可。
这就让”工作流”从一种 prompt 写法，变成了可以共享、可以修改、可以迭代的资产。
当前 Workflow 仍然是隐藏/实验能力，所以需要显式开启。
启动 Claude Code 前，可以这样设置：
export CLAUDE_CODE_WORKFLOWS=1
claude
或者直接：
CLAUDE_CODE_WORKFLOWS=1 claude
进入 Claude Code 后，如果你希望它使用 Workflow，可以明确写：
ultrawork
请生成一个只读的大代码库分片审查 workflow script。
不要执行，先让我确认。
这里要注意：ultrawork 更像一个经验性触发词，不是官方公开文档里的正式命令。它在测试中能有效提示 Claude Code 使用 Workflow，但不能把它当成稳定 API。
最稳妥的方式是两步走：
第一步，让 Claude Code 生成脚本，但不要执行。
ultrawork
请为当前仓库生成一个 workflow script，但不要执行。
要求：
1. 识别 4-8 个 review shard
2. 每个 shard 用 agent()
3. 每个 agent 必须带 JSON schema
4. 最后 aggregator 合并 findings
5. 写到 /tmp/sharded-review.workflow.mjs
6. 输出 scriptPath，等待我确认
第二步，确认脚本后再运行：
Workflow({
scriptPath: "/tmp/sharded-review.workflow.mjs"
})
目前我最推荐 scriptPath 方式，因为这是反复 E2E 验证过的路径。
下面是一个最小可运行的例子：
export const meta = {
name: "workflow-smoke-test",
description: "Minimal one-agent workflow script smoke test",
phases: [
{ title: "Run", detail: "Spawn one subagent and validate structured output" },
],
}
phase("Run")
const result = await agent(
"Return ok=true and message exactly WORKFLOW_SCRIPT_SMOKE_OK. Do not use tools.",
{
label: "smoke-agent",
phase: "Run",
model: "haiku",
schema: {
type: "object",
properties: {
ok: { type: "boolean" },
message: { type: "string" },
},
required: ["ok", "message"],
additionalProperties: false,
},
},
)
return {
ok: result.ok === true && result.message === "WORKFLOW_SCRIPT_SMOKE_OK",
result,
}
这里有几个关键点：
第一，meta 定义这个 workflow 的名称、描述和阶段。
第二，phase() 用来声明当前执行阶段。
第三，agent() 用来启动 subagent。
第四，schema 用来约束 subagent 的结构化输出。
第五，最后用 return 返回 workflow 的最终结果。
这已经不是普通 prompt，而是一个可以复跑、可以检查 artifact、可以被别人复用的工作流。
下面是几类我认为最值得做成 Workflow script 的场景。
这是 Workflow 最典型的场景。
比如一个仓库可以拆成：
每个 reviewer 只看自己的分片，最后 aggregator 汇总结果、去重、排序。
这种模式比”请审查整个仓库”稳定得多。
一个 PR 可以让多个 agent 同时检查：
最后给出：
这比单 agent review 更有覆盖面。
适合文档、方案、Prompt、Release Note。
流程可以是：
这个模式很适合需要质量闭环的内容生产。
可以让不同 agent 分别研究：
然后由 synthesizer 生成最终报告。
这种 workflow 一旦跑通，就可以反复用于不同技术主题。
比如你有 4 个 prompt 版本，不知道哪个更好。
Workflow 可以并行测试多个版本，然后由 judge agent 评分和排序。
这比人工复制粘贴 prompt 做对比高效很多。
可以，而且这可能是 Workflow 最有想象力的地方。
以前大家共享的是 prompt、skill、MCP server。
现在，至少在工作流编排这个层面，大家可以共享：
deep-research.workflow.mjs
pr-review.workflow.mjs
large-codebase-review.workflow.mjs
prompt-eval.workflow.mjs
release-gate.workflow.mjs
别人拿到脚本后，只要环境支持 Workflow，就可以复用这套工作流。
这意味着什么？
意味着”如何组织多个 agent 做事”本身，也可以变成开源资产。
以前我们共享的是能力。
现在我们可以共享流程。
Workflow 很强，但不代表它可以无监督使用。
我在实际测试中也看到过边界。
比如用 Workflow 做代码审查时，它能快速发现很多高价值问题，但也可能把某些问题严重级别判断过高。一个看似 SQL 注入的 finding，人工复核后发现上游已经有 UUID/prefix 正则约束，所以不能直接定性为 critical。
还有一次生成-批评-修复 workflow 中，因为 schema 字段叫 ok，critic 把它理解成”草稿是否合格”，返回了 ok=false，导致脚本最终断言失败。后来把字段改成 reviewed，结果就稳定了。
这说明两点：
第一，Workflow 能提升覆盖面，但不能替代工程判断。
第二，Workflow 的 schema 设计非常关键。
所以我建议：
Workflow({ scriptPath }) 执行Workflow 的价值，不是让 Claude Code 多叫几个 agent。
它真正的价值是：
把 Agent 编排变成代码。
这件事会带来三个变化。
第一，复杂任务可以复跑。
第二，优秀工作流可以共享。
第三，多 Agent 协作可以从”模型临场发挥”，变成”脚本化、结构化、可观察的工程流程”。
这也是为什么我认为 Workflow 值得重点关注。
它现在还不是正式公开能力，也不适合被包装成稳定平台 API。
但如果你已经在深度使用 Claude Code，尤其是已经在使用 Subagents、Agent Teams、Skills，那么 Workflow 很可能会成为你下一阶段最重要的效率杠杆。
未来如果官方正式公开这个能力，我们大概率会看到大量 workflow script 项目出现：
那时，大家共享的就不只是 prompt，而是完整的多 Agent 工作流。
这可能才是 Claude Code Workflow 最值得期待的地方。
本期内容到这里，欢迎大家点赞、关注和转发，谢谢大家观看。
]]>/goal 是 OpenAI 在 Codex CLI 0.128.0（2026 年 4 月 30 日发布）中新增的一条命令。它不是又一个普通的提示词模板，而是 Codex 内部新增了一整套目标生命周期管理机制——给一个目标，Codex 会自己一轮接一轮往下推进，真正实现无人值守。社区里已经出现连续运行 21 小时、烧掉 9 亿 token 的案例。这篇笔记把我自己踩过的坑、固定下来的工作流、配套的 Skill 全都整理成保姆级教程。
🚀 本篇笔记所对应的视频：
/goal 是什么，以及它为什么重要/goal 是 OpenAI 在 Codex CLI 0.128.0（2026 年 4 月 30 日发布）中新增的一条命令。官方更新日志的原话是：
Added persisted /goal workflows with app-server APIs, model tools, runtime continuation, and TUI controls for create, pause, resume, and clear.
翻译成大白话就是：/goal 不是又一个普通的提示词模板，而是 Codex 内部新增了一整套目标生命周期管理机制。它由四个层面共同构成：
active / paused / achieved / unmet / budget_limited）thread/goal/{get, set, clear} 三个接口，让客户端可以读写目标状态get_goal、create_goal、update_goal 三个工具，让模型可以查询和声明完成，但不能自己暂停/清空/篡改这套机制最直观的效果就是：给一个目标，Codex 会自己一轮接一轮往下推进，真正实现无人值守。社区里已经出现连续运行 21 小时、烧掉 9 亿 token 的案例；我自己测试中也跑过几个小时不间断的批量重构任务。
如果你之前听说过 Ralph Loop（用脚本反复让 agent 跑同一个目标的工作流），/goal 就是 OpenAI 把它做进了 Codex 内核里。OpenAI 总裁 Greg Brockman 在 X 上的原话是：“codex now has a built in Ralph loop++”。比起外部脚本驱动的 Ralph Loop，内置版本的优势在于：目标可以跨会话恢复、token 预算是一等公民、暂停/恢复是原生命令，而且不需要每轮重建上下文，产出质量明显更稳。
/goal 解决了哪些以前解决不了的问题理解 /goal 价值的关键，是它到底解决了什么以前没办法解决的问题。我归纳为四点：
普通 prompt 是写在 Codex 的对话流里的。一旦上下文超过阈值触发 /compact，或者你切换会话，prompt 就可能被压缩、被覆盖、被丢失。/goal 不一样，它把”目标”作为独立的 thread 状态存起来，跟对话历史是两回事。所以：
/compact 压缩对话历史，不会破坏 goal 状态codex resume <id> 还能续上之前的 goal注意一个已知问题：Issue #19910 报告，如果
/compact发生在一轮模型调用执行的中间，延续提示词不会被重新注入，下一个 agent 可能丢掉目标和审计要求。如果你计划做超长任务，尽量让自动 compaction 落在轮次边界而不是手动压缩。
这是 /goal 最低估的部分，但也是最关键的部分。
每一轮空闲后，Codex 会自动向模型注入一段叫 continuation.md 的提示词（源码在 codex-rs/core/templates/goals/continuation.md）。这段提示词的核心要求是这样的（直译关键段落）：
在判定目标已达成之前，执行一次”完成审计”：
- 把目标重述为具体的交付物或成功标准
- 构建一份提示词到产物的清单，把每一条显式要求、每一个编号项、每一个具名文件、命令、测试、门禁、交付物映射到具体证据
- 检查相关文件、命令输出、测试结果、PR 状态等真实证据
- 不要把代理信号当成完成证据：测试通过、清单填满、verifier 跑成功、写了大量代码 —— 这些只是辅助信号，不能单独作为完成依据
- 把不确定视作未达成；继续验证或继续工作
以及一段非常关键的反偷懒规则：
不要依赖你的意图、阶段性进度、已耗费精力、对早前工作的记忆、或一个看上去合理的最终答案，作为完成的证明。只有审计显示目标确实已达成、且没有遗留必需工作时，才能调用
update_goal标记完成。
这套机制是在解决一个具体的痛点：模型在长任务中习惯”sandbag”（早早声称做完然后偷懒）。/goal 把这种倾向用机制压住了 —— 但前提是你给的目标必须能被映射成一份清单。
/goal 支持设置 token 预算上限。一旦烧到上限，Codex 不会粗暴中断当前轮次，而是注入另一段提示词 budget_limit.md，让模型把当前任务收尾：总结已完成的进度、列出剩余工作、给出下一步建议，然后停下。
对于无人值守场景，这意味着即使你设错了预期或者目标比想象中复杂，你也能在第二天打开终端时拿到一份能看懂的进度报告，而不是一堆半成品和没了的 token。
/goal 提供四条 TUI 命令：
| 命令 | 作用 |
|---|---|
/goal <objective> |
创建或替换当前目标 |
/goal |
显示当前目标摘要（状态、目标内容、耗时、token 用量） |
/goal pause |
暂停延续 |
/goal resume |
恢复暂停的目标（早期叫 /goal unpause，后来 PR #20082 改名了） |
/goal clear |
清空当前目标 |
注意：暂停/恢复/清空/预算限制状态的转换，模型自己改不了，只能由用户或运行时触发。这是设计上的安全边界 —— 模型唯一能自己做的状态变更是”标记完成”，而且这个动作还得通过完成审计。
/goal，什么场景不要用/goal 很强，但不是所有任务都该用它。盲目用反而费 token、跑偏、卡死。我的判断标准是这样的：
/goal/goal 跑/goal/goal 给我开发一个背单词 APP。没有验收标准，Codex 会幻想出一个目标然后认真去实现，但实现出来的不是你要的。/goal 的特点是会自己往下推进，这种场景下风险会被放大。/goal 反而徒增开销。/plan 模式下，即使你看到 UI 上显示 “Goal active”，Codex 实际上不会自动延续。源码里 should_ignore_goal_for_mode 函数在 Plan 模式下直接跳过 goal 延续。所以如果你要用 /plan 做规划，先退出 Plan 模式再启动或恢复 /goal。/goal/goal 目前是实验性功能，默认关闭，需要手动开启。
打开 ~/.codex/config.toml，加上下面这段：
[features]
goals = true
如果你想完整体验所有相关功能（尤其是 /plan 配合 /goal），可以把协作模式也打开：
[features]
goals = true
collaboration_modes = true
保存，然后重启 Codex，/goal 就可用了。
如果你不熟悉配置文件的位置和写法，可以直接在 Codex 里用自然语言描述，比如：
请帮我开启 Codex 0.128 新增的 /goal 命令。
配置文件位置：~/.codex/config.toml
需要在 [features] 段下加上 goals = true。
如果文件不存在请创建，如果 [features] 段不存在请新增。
Codex 会自动帮你完成。改完别忘了重启。
启动后输入 /，如果在斜杠命令补全列表里能看到 /goal，说明已经启用。也可以直接输入 /goal 回车，如果显示”暂无目标”或者类似的状态摘要，就是好了。
/goal 提示词的核心心法我在最初使用 /goal 的时候，踩过一个最典型的坑：直接 /goal 加一句简短描述就回车走人。结果几个小时回来一看，Codex 跑了一堆事情，但跑的根本不是我要的；甚至有时候会陷入静默卡死状态。
后来我把这个事情想清楚了：/goal 对提示词的要求，比普通对话高一个数量级。原因是它的内置审计机制 —— continuation.md 要把你的目标映射成一份”提示词到产物”的清单，如果你用的是模糊词（”全部”、”所有”、”彻底”、”清理一下”、”提升一下”），清单根本建不起来，审计就会退化成”测试跑过了就算完成”这种代理信号 —— 然后你就得到一个声称完成、实际跑偏的结果。
所以 /goal 真正发挥威力的前提，是你要能写出可被映射成清单的目标。
经过这段时间的实践，我固定下来一套五段式模板，几乎所有 /goal 我都按这个写：
/goal <一句话描述目标>
Scope: <作用范围 — 改哪些文件/子系统/feature 区域，其他不要碰>
Constraints:
- <硬性约束 1 — 比如"不要修改数据库 schema">
- <硬性约束 2 — 比如"保持现有公开 API 不变">
- <硬性约束 3 — 项目类型相关的默认规则>
Done when:
1. <可验证的产物 1 — 引用具体文件名或命令>
2. <可验证的产物 2>
3. <可验证的产物 3>
...
Stop if:
- <机械可识别的停止条件 1 — 比如"需要新依赖">
- <机械可识别的停止条件 2 — 比如"需要修改 MUST NOT 列表中的文件">
Use a token budget of <N> tokens for this goal.
每一段的要点：
project.pbxproj“就比”不要破坏现有结构”好。npm test、pytest -q、tsc --noEmit 都比”测试通过”明确）。/goal 把 src/data/words.json 里的词库扩展到 1000 个唯一词条。
Scope: 只改 src/data/words.json，其他文件不要动。
Constraints:
- 词条 schema 保持不变（id / word / phonetic / meaning / example）
- 不允许重复词条（以 word 字段为准去重）
- 只能用真实的、常见的英语单词，不要生造
Done when:
1. words.json 包含恰好 1000 个唯一词条
2. 所有词条 schema 校验通过（用 tools/validate.js 跑一遍）
3. 在终端输出最终词条数和文件大小
Stop if:
- 需要修改 words.json 以外的任何文件
- 需要新增 npm 依赖
- 出现 schema 校验失败超过 3 次
Use a token budget of 80000 tokens.
这个目标可以被审计 —— 每一条 Done when 都对应一个能跑的检查；每一条 Stop if 都是机械可识别的；Scope 把作用面锁死了。这种 goal Codex 跑起来准确率明显不一样。
下面是我目前固定下来的三种 /goal 用法。从简单到复杂，按任务规模选用。
/goal 直接用 — 适合中等任务适合任务边界清楚、自己能写出五段式模板的场景。直接在 Codex 里输入完整的 /goal <五段式提示词>，回车，然后该干嘛干嘛去。
跑起来后，你随时可以：
/goal（不带参数）查看当前进度：状态、耗时、token 用量/goal pause 暂停/goal resume 恢复/goal clear 中止这是最常用的形态。70% 的任务我都是这样跑的。
/plan + /goal — 适合复杂任务如果任务复杂、需求还比较模糊、自己也没想清楚验收标准，直接 /goal 是不行的，要先用 /plan 把方案讨论清楚。
完整流程：
/plan 或者 Shift+Tab 切换）Shift+Tab 退出 Plan 模式/goal 执行上面的开发计划，加上 Done when / Stop if / token budget为什么要先选”保持 Plan 模式”再手动退出？因为前两个选项会立刻执行，但执行的不是 /goal 模式，享受不到延续和审计；而你直接在 Plan 模式里输入 /goal，会落入 Issue #20656 的坑（看上去激活了但其实不延续）。所以必须先退出 Plan 模式，再下 /goal。
/goal — 适合规格驱动开发这是最适合 /goal 的工作流之一。Spec-Driven Development（SDD）的思路是：先把需求写成规格文档（包含 proposal、specs、design、tasks），然后让 AI 严格按规格实现。规格文档天然就是一份审计清单 —— 把它喂给 /goal，完成审计能精准地工作。
OpenSpec 是 Fission-AI 团队开发的开源 SDD 工具（MIT 协议，GitHub 上 37k stars），它的工作方式是这样的：
You: /opsx:propose add-dark-mode
AI: Created openspec/changes/add-dark-mode/
✓ proposal.md — 为什么要做、改了什么
✓ specs/ — 需求和场景
✓ design.md — 技术方案
✓ tasks.md — 实现清单
Ready for implementation!
完整工作流：
OpenSpec 需要 Node.js 20.19.0+。安装命令：
npm install -g @fission-ai/openspec@latest
进入项目目录，初始化：
cd your-project
openspec init
OpenSpec 会在项目里生成 openspec/ 目录，并把适配你 AI 工具的指令写到对应的位置（它支持 20+ 种 AI 工具，Codex 也在里面）。
在 Codex 里直接输入（/opsx:propose 是 OpenSpec 安装后注册的斜杠命令）：
/opsx:propose 为这个项目新增 Cohere Rerank 作为第五个 Rerank provider
Codex 会调用 OpenSpec，把你的需求拆解成 proposal.md、specs/、design.md、tasks.md。这一步不会动你任何源代码，只是把”要做什么”写清楚。
/goal 执行规格规格文档生成完后，在 Codex 里：
/goal 严格实现 openspec/changes/add-cohere-rerank/ 中描述的变更。
First action: 先读 proposal.md / specs/ / design.md / tasks.md / AGENTS.md 这五个文件，
报告每个文件的字数和关键章节标题，等我确认后再开始实现。
Scope: design.md 里的 "MUST NOT modify" 列表严格遵守。
Constraints:
- AGENTS.md 中的所有 iron rules 不可违反
- 不允许新增 npm 依赖
- 镜像现有 4 个 Rerank provider 的代码风格
Done when:
1. tasks.md 中的每一项都打勾，引用对应文件路径
2. 每条 SHALL 都有对应的通过测试，引用测试名
3. 每个 GIVEN/WHEN/THEN 场景都有集成测试覆盖
4. `npx tsc --noEmit` 退出码 0
5. `npm test` 退出码 0，粘贴汇总输出
6. README.md 在 provider 表格里加上新一行
7. CHANGELOG.md 在 Unreleased 段加条目
Stop if:
- 任何任务需要修改 MUST NOT 列表中的文件
- SHALL 之间出现冲突（暂停，让我决定）
- 需要 npm install 新依赖
- 现有 Rerank provider 测试出现失败
Use a token budget of 120000 tokens.
注意第二行的 First action：这是个非常关键的小技巧。它强制 Codex 在动手前先把规格文件全部读一遍并向你报告确认 —— 防止 Codex 用 @filename 等不可靠引用方式假装”知道”了规格，实际上没读全。
这种工作流跑出来的产物质量最稳。我自己测试中，中等规模的 feature（类似新增一个 provider 这种 200~400 行的改动）基本都能一次跑通，跑完直接是个能 review 的 PR。
goal-prompt-builder 把上面这些自动化写好五段式提示词需要练习。如果不熟练，或者懒得每次手写，可以用我开发的 goal-prompt-builder —— 一个专门用来生成 /goal 提示词的 Claude Skill，仓库在：
https://github.com/win4r/goal-prompt-builder （MIT 协议）
/goal 内置的 continuation.md 审计机制非常强，但前提是你的目标文本能被映射成清单。这个 skill 的核心目的就是：保证生成的目标文本一定可以被映射成审计清单。
按 README 描述，skill 触发后会走 6 步：
package.json、Cargo.toml、*.xcodeproj 等）或者抓 GitHub README，顺便读 AGENTS.md / CLAUDE.md/goal 提示词，加一段简短的设计说明它内部有一组硬规则（从 continuation.md 倒推出来的）：
@filename 引用不准我用这个 skill 之后，日常写 /goal 的速度快了非常多 —— 简单任务一两分钟就能从一句话需求走到一个可用的 5 段式提示词。
按 README，有三种方式：
curl -L -o /tmp/goal-prompt-builder.skill \
https://github.com/win4r/goal-prompt-builder/raw/main/goal-prompt-builder.skill
mkdir -p ~/.claude/skills
unzip -o /tmp/goal-prompt-builder.skill -d ~/.claude/skills/
rm /tmp/goal-prompt-builder.skill
git clone https://github.com/win4r/goal-prompt-builder.git
ln -s "$(pwd)/goal-prompt-builder/goal-prompt-builder" ~/.claude/skills/goal-prompt-builder
如果你不熟命令行，直接在 Codex 里描述安装需求：
请帮我安装这个 skill：https://github.com/win4r/goal-prompt-builder
按 README 的安装方式装到默认位置。
Codex 会自己执行下载、解压、放到对应目录。装完后重启 Codex，skill 就生效了。
注意：这个 skill 是用 Claude Skills 格式构建的，默认安装位置是
~/.claude/skills/。具体在哪个客户端能被识别，以你客户端文档为准 —— README 明确列出的兼容客户端是 Claude Code、Claude Desktop、以及支持 Skills 的 Claude.ai。
安装重启后，skill 会被以下短语自动触发，不需要手动调：
最简单的用法是丢一个一句话需求进去，比如：
我想用 /goal 给这个项目增加 Cohere Rerank 作为第五个 Rerank provider
skill 会：
package.json）AGENTS.md / CLAUDE.md 提取项目特定的规则/goal + 一段设计说明，告诉你为什么这样写把输出粘贴到 Codex 的输入框，回车，任务就跑起来了。
这些是我自己踩过、或者社区在 GitHub Issue 里报告过的坑。直接列出来，贴在显示器旁边比什么都管用。
/goal 不延续现象：UI 上显示 “Goal active”，但 Codex 不会自己往下推进，看上去像卡死了。
原因：Issue #20656。源码里 should_ignore_goal_for_mode(mode) -> mode == ModeKind::Plan。Plan 模式下 goal 延续被静默跳过。
对策：用 /plan 做规划时不要同时启动 /goal。规划完先退出 Plan 模式（Shift+Tab），再下 /goal。
/compact 把 goal 上下文搞丢现象：跑了一段时间，模型突然好像”忘了”目标的细节，开始做不相关的事，或者过早声称完成。
原因：Issue #19910。如果 /compact 发生在一轮模型调用执行的中间，延续提示词不会被重新注入，后续 agent 丢掉目标和审计要求。
对策：长任务不要手动 /compact。设一个相对宽松的 token 预算，让自动 compaction 落在轮次边界上。
/goal，之后 resume 列表里找不到这个会话现象：codex resume 列表、Codex Desktop 的 recents 里都看不到这个 thread，但 thread 本身没丢，知道 ID 还能打开。
原因：Issue #20792。/goal-first 的 thread 在列表里被遗漏了。
对策：新 thread 第一条消息别用 /goal。先随便发一句话，比如 “Working on the OAuth migration goal”，再用 /goal。
现象：跑了几个小时回来，声称做完了，但你一看实际改动只是边边角角，核心问题没动。
原因：这些词没法被 continuation.md 映射成清单，审计退化成”测试跑过 = 完成”。
对策：换具体的数字或可验证的状态。”修 5 个真实可复现的 bug”、”覆盖 README 列出的 3 条用户路径”、”pytest 0 失败 0 跳过” —— 这些都比”修复所有 bug”强一万倍。
现象：任务跑飞，token 烧光也没人提醒，等回来一看账单不对劲。
对策：永远设 token budget。Use a token budget of <N> tokens for this goal.。烧到上限会触发软停止，让模型把工作收尾，而不是裸停。
现象：让 Codex 做迁移，跑着跑着把数据库 schema 改了 / 把不该删的文件删了。
对策：破坏性操作不要用 /goal。必须用的话，Constraints 里明确写”不要执行 rm -rf“、”不要修改数据库 schema”、”任何 destructive migration 暂停问我”，并且把对应内容也写进 Stop if。
| 操作 | 命令 |
|---|---|
| 创建/替换目标 | /goal <objective> |
| 查看当前目标摘要 | /goal（不带参数） |
| 暂停 | /goal pause |
| 恢复 | /goal resume |
| 清空 | /goal clear |
| 退出 Plan 模式 | Shift+Tab |
| 跨会话恢复 thread | codex resume <id> |
状态标识：
pursuing / active — 正在自主推进paused — 被手动暂停achieved / complete — 完成审计通过，目标达成unmet — 未达成budget_limited — token 预算耗尽，软停止中每次发 /goal 之前，过一遍这个清单：
/goal 吗？（单轮能干完的别用）/goal 消息再说跑起来之后：
/goal pause，补上下文，再 /goal resume/goal 查进度/compact最近半年，prompt 写法明显在变化：
/goal 是这个方向走得最远的产物之一。它把”过程指挥”压到最低、把”结果声明”提到最高，然后用一套内置审计机制保证模型不偷懒。
但反过来，这也提高了对”会写需求”的要求。模型越来越能干，但它干得好不好，反过来更依赖你能不能把”到底要啥”说清楚。会写需求这件事，正在重新变成稀缺技能。
以前 prompt 糊一点没事，反正它也只跑几秒钟；现在它能跑一整天，你那条糊掉的 goal，换来的就是一整天的糊产出。
/goal 的真正价值不在于”它能跑一整天”，而在于它把”AI 真的能替你跑一整天”这件事，从一个需要外部脚本 + 反复试错的工程，变成了一条可以直接在终端里下的命令。剩下的事，是把目标写清楚。
GitNexus 被作者称作代码库的神经系统，核心理念只有一句话：AI Agent 不应该盲目编辑代码。它把代码仓库索引为知识图谱，再通过 MCP 协议把这份图谱喂给 Codex、Claude Code、Cursor 等 AI 编程助手，让它们在动手改代码之前就能完整地感知项目结构、依赖关系和”爆炸半径”。
🚀 本篇笔记所对应的视频：
传统 AI 编程工具最大的问题是：它们看到的是代码片段，而不是代码结构。
无论是 Claude Code、Codex 还是 Cursor，本质上都是通过 Glob / Grep 一段一段地读文件。如果不借助外部工具，它们对项目的全貌缺乏感知，很容易出现”盲改代码”的情况——改了一个函数的返回类型，根本不知道有几十个调用方会被破坏；重构一个模块，不知道下游有哪些隐藏依赖。
GitNexus 的解题思路是：在索引阶段就把调用链、聚类、置信度评分全部预计算好，AI 工具一次调用 MCP 就能拿到完整的结构化上下文。这样既提升了改动的可靠性，又节省了 Token，甚至让小模型也能胜任原本需要大模型才能处理的复杂任务。
GitNexus 内置了 7 个 MCP 工具，每一个都对应一个具体的开发痛点：
| 工具 | 用途 |
|---|---|
impact |
爆炸半径分析——改这个函数会波及哪些代码 |
context |
360 度符号视图——某个符号的完整上下游关系 |
query |
进程感知的混合搜索（BM25 + 语义向量） |
detect_changes |
Git diff 风险评估，配合 PR Review |
rename |
跨文件协调重命名 |
cypher |
原始图查询，给高级用户用 |
list_repos |
全局仓库注册表 |
这是 GitNexus 最值得称道的一点：索引、解析、聚类、图构建都是完全本地化的。即便是嵌入向量（用于语义搜索），它也是通过本地的 transformers.js 跑 Hugging Face 嵌入模型，不调用任何 LLM API，不消耗任何 Token。
你只在用 gitnexus wiki 自动生成项目文档时才会用到 LLM API（默认 OpenAI 的 gpt-4o-mini，可以通过 --base-url 切换到任意 OpenAI 兼容协议的服务）。日常的索引、查询、影响分析等核心功能，一个 API Key 都不需要。
支持主流的 TypeScript、JavaScript、Python、Java、Kotlin、C#、Go、Rust、PHP 等编程语言，覆盖绝大多数生产项目的技术栈。
不少朋友会问 GitNexus 和 Graphify 怎么选，这里直接给一个对照：
| 维度 | GitNexus | Graphify |
|---|---|---|
| 定位 | AI Agent 的代码地图 | 跨模态知识编译器 |
| 关注点 | 调用链、爆炸半径、类型解析 | 代码、文档、论文、图像、视频统一图谱 |
| 索引 LLM 开销 | 零 Token | AST 通道零开销，语义通道有 LLM 消耗 |
| 触发方式 | MCP 协议 | Skill 触发 |
| 输出 | 实时查询的结构化上下文 | Git 友好的静态产物（团队共享） |
简单概括：
两个项目互不冲突，叠加使用效果更好。
npm install -g gitnexus
如果你担心 npm 全局目录权限问题，可以提前把全局目录改到家目录下：
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
之后所有的 npm install -g 都不再需要 sudo。
gitnexus --version
输出版本号即说明安装成功。
gitnexus setup
这条命令会自动检测本地装的 Cursor、Claude Code、OpenCode、Codex、Windsurf 等 MCP 兼容编辑器，把 GitNexus 的 MCP server 配置一次性写入所有编辑器的全局 MCP 配置文件，同时安装对应的 Skill。
如果你只想配置 Claude Code，也可以单独执行：
claude mcp add gitnexus -- gitnexus mcp
Windows 用户请使用：
claude mcp add gitnexus -- cmd /c gitnexus mcp
配置完成后，完全退出再重启 Claude Code——MCP server 只在启动时初始化，配置改了必须重启才会生效。
下面以一个真实项目为例：为 OpenClaw 开发的记忆插件 memory-lancedb-pro，看看完整的索引流程。
cd ~/Desktop/project/memory-lancedb-pro
gitnexus analyze
这条命令会跑完整的 6 阶段管线：Structure → Parsing → Resolution → Clustering → Processes → Search，最终生成 .gitnexus/lbug 数据库，以及配套的 AGENTS.md 和 CLAUDE.md。
实测下来，167 个文件的项目大约 6 秒完成索引；几千文件的项目也只需要几分钟。索引完成后，会提示生成了多少节点、多少边、多少社区（cluster）、多少执行流（flow）——比如本期演示的项目就生成了 6400 个节点、1 万多条边、203 个簇、300 个 flow。
需要注意的是：基础索引不会生成语义向量、模块级 Skill 和诊断细节。也就是说在 Claude Code 里调用 GitNexus 时只能做关键词匹配，无法发挥真正的实力。
gitnexus analyze --embeddings
加上 --embeddings 参数后，GitNexus 会用本地 Hugging Face 嵌入模型为每个 symbol 生成向量。这样 query() 工具就能做真正的自然语言语义搜索，而不只是关键词匹配。
整个过程仍然零 Token、零 LLM 调用，只是索引时间会多 30%–100%（取决于 CPU/GPU 性能）。
gitnexus analyze --embeddings --skills --verbose
这是日常使用的推荐配置：
--embeddings 启用语义搜索--skills 把 Leiden 算法识别的每个功能社区生成独立的 SKILL.md，写到 .claude/skills/generated/<area>/，让 Claude Code 在不同模块工作时拿到精准的局部架构上下文--verbose 打印被跳过的文件，方便诊断索引覆盖率gitnexus list # 查看所有已索引的仓库
gitnexus status # 查看当前仓库索引状态
索引完成后，可以启动本地 HTTP 服务来浏览图谱：
gitnexus serve
默认监听 4747 端口，启动后保持终端运行即可。然后浏览器访问 https://gitnexus.vercel.app，UI 会自动检测本地 4747 端口的 backend，列出所有已索引的仓库。点击对应卡片就能进入图浏览界面。
实测体验：
如果你不想长期占着一个终端，可以把服务放到后台：
nohup gitnexus serve > ~/.gitnexus/serve.log 2>&1 &
需要停止时执行 pkill -f "gitnexus serve" 或 lsof -ti:4747 | xargs kill。
完成索引后，在 Claude Code 中输入斜杠，就能看到 GitNexus 自动注册的几个 Skill，比如 gitnexus exploring、gitnexus debugging、gitnexus pr review。下面分别测试几个高频场景。
直接输入：
分析项目架构
Claude Code 会调用 GitNexus 的 MCP 工具，输出结构化的分析报告：
分析这个项目中 A-MAC 的作用是什么
GitNexus 会基于图谱给出准确的回答：「A-MAC 是智能写入门控」，并给出具体的调用关系和上下文。
这是 GitNexus 最能体现价值的场景：
如果删除 A-MAC 功能会影响哪些代码
输出结果不仅列出了所有受影响的文件，甚至精确到具体的代码行号。这种粒度的分析，没有知识图谱根本做不到。
为了公平对比，我重新克隆了同样的项目，不做任何 GitNexus 索引，开一个干净的 Claude Code 窗口，提同样的问题。
然后再开第三个 Claude Code 窗口，把两边的回复都贴进去，让它客观评判：
「分析这两个 AI 回答的差别，哪个更详细？」
最终结论：
这个对比基本可以说明 GitNexus 在影响分析这类任务上的硬实力。
随便从项目里挑一个 issue，把链接贴给 Claude Code，再用 /gitnexus debugging 触发分析：
/gitnexus debugging 分析这个 issue：<issue 链接>
GitNexus 会输出：
选定路线（比如直接回复「路线 A」）后，Claude Code 会按 GitNexus 给出的方案完成修复，并提供改动摘要和验证方式。
通过 /gitnexus pr review Skill 加上 PR 链接：
/gitnexus pr review <PR 链接>
GitNexus 会基于图谱完成 review。继续追问「如果合并这个 PR 会影响哪些代码」时，它会输出：
gitnexus analyze
GitNexus 会比对已有索引，只处理变更的文件。如果你执行过 gitnexus setup，PostToolUse hook 会在每次 commit 后自动提醒 Claude Code 重新索引，多数情况下不用手动跑。
gitnexus status
会对比 meta.json 里的 lastCommit 和当前 HEAD，告诉你索引是否需要更新。
gitnexus analyze --force
升级 GitNexus 大版本、改动量过大、怀疑索引被污染时使用。
gitnexus clean # 清当前项目
gitnexus clean --all --force # 清所有已注册仓库
gitnexus wiki
这是 GitNexus 唯一会调用 LLM 的命令，默认走 OpenAI 的 gpt-4o-mini。如果想换模型，加 --model 和 --base-url 参数即可，对应的 API Key 通过环境变量提供。
如果你只想要一份能直接拷贝执行的脚本：
# 阶段 0：环境准备（可选）
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# 阶段 1：安装
npm install -g gitnexus
gitnexus --version
# 阶段 2：索引（在你的项目目录下执行）
cd ~/your-project-path
gitnexus analyze --embeddings --skills
# 阶段 3：启动 Web UI
gitnexus serve &
# 浏览器打开 https://gitnexus.vercel.app
# 阶段 4：配置 Claude Code
claude mcp add gitnexus -- gitnexus mcp
# 完全重启 Claude Code
# 阶段 5：日常维护
gitnexus list # 查看所有索引仓库
gitnexus status # 查看当前索引状态
gitnexus analyze # 增量更新
每一步是否成功，可以参考下面这张表自检：
| 阶段 | 验证命令 | 成功标志 |
|---|---|---|
| 安装 | gitnexus --version |
输出 1.6.3 或更新版本 |
| 索引 | cat .gitnexus/meta.json |
看到 nodes / edges / lastCommit 字段 |
| 注册 | cat ~/.gitnexus/registry.json |
出现你的仓库条目 |
| Context 文件 | ls AGENTS.md CLAUDE.md |
两个文件都存在且非空 |
| HTTP server | curl http://localhost:4747/api/mcp |
返回 JSON 而非 connection refused |
| Web UI | 访问 https://gitnexus.vercel.app |
看到仓库列表页面 |
| Claude MCP | 在 Claude Code 里问「列出 GitNexus 工具」 | 列出 7 个工具名 |
通过这一轮实测可以看到，借助 GitNexus，AI 编程工具就能对代码库有更深入、更全面的理解：
而且这一切的代价仅仅是一次本地索引，不消耗任何 Token，不需要任何 LLM API。对于希望让 Claude Code、Codex、Cursor 这类工具在自己代码库上变得真正靠谱的开发者来说，GitNexus 几乎是一个零成本的能力增强。
如果你前面已经在用 Graphify 处理跨模态知识，那么把 GitNexus 加进来，就等于把代码侧的”全局视野”也补齐了——一个负责语义，一个负责结构，配合起来才是完整的 AI 编程工作流。
本期内容到这里，欢迎大家点赞、关注和转发，谢谢大家观看。
]]>今天给大家介绍一个非常硬核的开源项目——notebooklm-py。它通过逆向 NotebookLM 的内部 API，把所有功能（包括 Web 端没暴露的）都做成了 Python API + CLI + AI Agent Skill 三件套。
⚠️ 重要提示：这是非官方库，使用的是 Google 未公开的内部接口，存在 API 随时变动的风险。适合做原型、做研究、做个人项目，不建议用在生产环境。
先看一张能力总览：
| 模块 | 能力 |
|---|---|
| 笔记本 | 创建、列出、重命名、删除 |
| 资料源 | URL、YouTube、PDF、Markdown、Word、音视频、图片、Google Drive、纯文本，都能批量导入 |
| 对话 | 提问、查看历史、自定义 Persona |
| 研究 | Web 研究 / Drive 研究 Agent，支持快速 / 深度两种模式，结果自动入库 |
| 分享 | 公开 / 私有链接、用户权限（查看 / 编辑） |
| 生成 | 音频概览、视频概览、PPT、信息图、测验、闪卡、报告、数据表、思维导图 |
这才是这个项目最值钱的地方：
光这几条就值得一试。
win4r 这个 fork 把版本锁定在 v0.3.4-hermes.4，附带了一份 SECURITY_AUDIT.md 安全审计报告，比直接装 PyPI 上的版本更稳。
pip install "git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
pip install "notebooklm-py[browser] @ git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
playwright install chromium
加上 [browser] extra 后就能用 Playwright 自动登录，省掉手动复制 cookie 的麻烦。
如果你是 Hermes 用户：
VIRTUAL_ENV=~/.hermes/hermes-agent/venv uv pip install \
"notebooklm-py[browser,cookies] @ git+https://github.com/win4r/notebooklm-py@v0.3.4-hermes.4"
~/.hermes/hermes-agent/venv/bin/playwright install chromium
mkdir -p ~/.local/bin
ln -sf ~/.hermes/hermes-agent/venv/bin/notebooklm ~/.local/bin/notebooklm
最后这行 ln -sf 是把 notebooklm 命令软链到 ~/.local/bin/，这样在终端任何位置都能调用。
NotebookLM 没有 OAuth，所以认证只能靠 cookie。项目提供了三种方案，首推方案一。
notebooklm login --browser-cookies chrome
notebooklm auth check --test
这条命令会自动从你已登录的 Chrome 里读 cookie，几乎零配置。
由于 Google session 通常 15-30 分钟就过期，强烈建议在 ~/.hermes/.env（或你常用的 shell rc 文件）里加一行：
NOTEBOOKLM_REFRESH_CMD=notebooklm login --browser-cookies chrome
设置后，cookie 过期时会自动透明刷新，你不会感知到。
notebooklm login
# 企业 SSO 用户用 Edge：
notebooklm login --browser msedge
会弹一个浏览器窗口让你扫码 / 输密码，登完自动保存。
装一个浏览器扩展叫 “Get cookies.txt LOCALLY”，导出 JSON 后：
python3 skills/notebooklm/import_browser_cookies.py /tmp/nb_cookies.json
rm /tmp/nb_cookies.json # ⚠️ 用完立刻删，里面是你的 Google 登录态
🔐 安全提示：
~/.notebooklm/storage_state.json存的就是你的 Google 登录凭证，当成密码看待。项目自带.gitignore屏蔽，但别手贱去git add -A。
CLI 是最适合脚本化的入口，下面是一份”从零到产出”的完整 demo。
notebooklm create "AI 研究"
notebooklm list # 列出所有笔记本
notebooklm use <notebook_id> # 把某个笔记本设为当前默认上下文
use 之后，后续所有命令都默认作用在这个笔记本上，不用每次都传 ID。
# 网页
notebooklm source add "https://arxiv.org/abs/2501.12345"
# 本地 PDF
notebooklm source add "./paper.pdf"
# 让 NotebookLM 自己去 Web 上找资料并自动入库
notebooklm source add-research "Diffusion Transformer"
source add-research 是真·杀器：传一个关键词，它会调用 NotebookLM 的 Research Agent 去全网检索，结果自动塞进笔记本，省掉你自己搜 + 整理的功夫。
notebooklm ask "总结一下这些论文的核心方法"
# 音频概览（播客）
notebooklm generate audio "make it engaging" --wait
# 视频概览（白板风格）
notebooklm generate video --style whiteboard --wait
# 电影感视频（纪录片风格）
notebooklm generate cinematic-video "documentary-style" --wait
# 测验
notebooklm generate quiz --difficulty hard
# 闪卡
notebooklm generate flashcards --quantity more
# PPT
notebooklm generate slide-deck
# 信息图
notebooklm generate infographic --orientation portrait
# 思维导图
notebooklm generate mind-map
# 数据表（用自然语言描述结构）
notebooklm generate data-table "对比各论文的核心方法、数据集、评测指标"
--wait 参数会一直 poll 到任务完成，省掉自己写轮询逻辑。
notebooklm download audio ./podcast.mp3
notebooklm download video ./overview.mp4
notebooklm download cinematic-video ./documentary.mp4
notebooklm download quiz --format markdown ./quiz.md
notebooklm download flashcards --format json ./cards.json
notebooklm download slide-deck ./slides.pdf # 也支持 .pptx
notebooklm download infographic ./infographic.png
notebooklm download mind-map ./mindmap.json
notebooklm download data-table ./data.csv
注意 quiz / flashcards 的 --format 选项，这是 Web UI 完全没有的能力。
notebooklm auth check --test # 检查登录状态
notebooklm metadata --json # 输出当前笔记本元数据
notebooklm share status # 查看分享设置
notebooklm language list # 列出 50+ 语言代码
CLI 适合写脚本，Python API 适合接进自己的应用。整个库基于 asyncio，下面是一个标准用法：
import asyncio
from notebooklm import NotebookLMClient
async def main():
async with await NotebookLMClient.from_storage() as client:
# 1. 创建笔记本，导入网页
nb = await client.notebooks.create("Research")
await client.sources.add_url(
nb.id,
"https://example.com",
wait=True,
)
# 2. 提问
result = await client.chat.ask(nb.id, "Summarize this")
print(result.answer)
# 3. 生成 + 下载播客
status = await client.artifacts.generate_audio(
nb.id,
instructions="make it fun",
)
await client.artifacts.wait_for_completion(nb.id, status.task_id)
await client.artifacts.download_audio(nb.id, "podcast.mp3")
# 4. 生成 + 导出测验为 JSON
status = await client.artifacts.generate_quiz(nb.id)
await client.artifacts.wait_for_completion(nb.id, status.task_id)
await client.artifacts.download_quiz(
nb.id,
"quiz.json",
output_format="json",
)
# 5. 生成 + 导出思维导图 JSON
await client.artifacts.generate_mind_map(nb.id)
await client.artifacts.download_mind_map(nb.id, "mindmap.json")
asyncio.run(main())
几个关键点：
NotebookLMClient.from_storage() 会自动读 ~/.notebooklm/storage_state.json，不需要你管 cookieasync with 会保证 client 优雅退出，连接不泄漏task_id，配合 wait_for_completion 实现异步轮询download_quiz 这种 API 多了一个 output_format 参数——这就是 Web UI 拿不到的”结构化导出”这是整个项目最有想象力的玩法——把 NotebookLM 变成 AI Agent 的工具。
npx skills add win4r/notebooklm-py
一行命令搞定。装完之后，Claude Code 就能用自然语言驱动整个 NotebookLM 流程，比如你跟它说：
“把这 10 篇论文导入新笔记本，生成一个深度播客和思维导图，导出到 ./output/”
它会自己去调 notebooklm create → source add → generate audio → download 全流程。
.agents/ 目录方式notebooklm skill install
会把 Skill 写到当前项目的 .agents/ 下，只在当前项目生效，适合给具体项目定制。
hermes skills tap add win4r/notebooklm-py
hermes skills install win4r/notebooklm-py/skills/notebooklm --force
记得先装 Python 包（参见第二节），并且把自动刷新命令塞到 ~/.hermes/.env：
NOTEBOOKLM_REFRESH_CMD=notebooklm login --browser-cookies chrome
Hermes 子进程会自动继承这个环境变量，cookie 过期不用你管。
每天早上跑一个定时任务：
source add 进同一个笔记本generate audio --wait通勤路上听昨天的论文摘要——比逛 Twitter 高效十倍。
老师 / 培训讲师特别适合：
接到 Claude Code / OpenClaw 之后：
“调研 NotebookLM 的所有竞品，每个都生成一份对比报告，最后产出一张数据表”
Agent 会自己跑 add-research → generate report → generate data-table → download data-table，全程不用你点鼠标。
API 不稳定性：Google 可能随时改内部接口。如果哪天突然报错，先 git pull 看看 fork 有没有更新，或者去 upstream 看 issue。
Cookie 过期：默认 15-30 分钟，一定要配 NOTEBOOKLM_REFRESH_CMD，否则跑长任务跑一半挂掉很烦。
Linux + Playwright：第一次装可能缺系统依赖，跑一下 playwright install-deps chromium 即可。
存储路径：~/.notebooklm/storage_state.json 是登录态文件，别上传到任何地方（包括 GitHub Gist、ChatGPT 截图）。
生产慎用：再说一遍，这是非官方接口，千万别接到生产业务——一旦 Google 改 API，你的服务就挂了。
如果你符合下面任何一条，这个项目值得花 10 分钟试一下：
项目地址再贴一遍：
如果只是普通用法、不需要 Hermes，建议直接用 upstream（更新更快）；如果你是 Hermes 用户或者特别在意安全审计，就用 win4r 这个 fork（带 audit report 和锁版本）。
NotebookLM 本身已经是 2026 年最被低估的 AI 工具之一，再叠加 notebooklm-py 之后，它从一个”网页版 AI 研究助手”直接升维成了”可编程的知识基础设施“。
值得玩。
]]>官方给它的定义只有一句话——
“A new era of image generation.”（图像生成的新纪元）
轻描淡写，却野心毕露。
如果说上一代AI画图是”听得懂话的画师”，那么2.0这一代，更像是一个”既懂设计、又懂排版、还懂文化”的全能创作搭子。
从官方放出的大量样图来看，这次升级主要踩在了几个关键词上：
以前你让AI画一幅海报，得到的可能是”大概那个意思”。现在，连一张桌面截图里的macOS图标、文件命名、窗口层级，它都能精细还原。Designer看了直呼内行。
中文、日文、韩文、阿拉伯文……以往AI一写非英文就变”鬼画符”的尴尬，这次被一次性按住。官方放出的日式漫画、韩屋（hanok）酒店宣传页、泰国街景海报，文字排版几乎可以直接拿去印刷。
Bauhaus风、Art Deco风、法国新浪潮拼贴风、杂志跨页风……这一次它不只是”画图”，而是在做完整的视觉设计。
从电影感人像、夜晚闪光灯抓拍，到超现实主义、seinen黑白漫画，AI的”审美颗粒度”肉眼可见地往上拔了一个段位。
这是最让人兴奋的一点：AI画图开始”先思考再下笔”。你让它解释康托尔对角线论证？它能给你画一张干净漂亮的教学信息图；你让它复刻GPT-1论文海报？它能像学术会议poster那样排版严谨。
官方放出的几十张样图里，几个场景特别有代表性：
看完只有一个感觉：设计师的工作流，要重新洗牌了。
坦白说，ChatGPT Images 2.0释放的信号，已经不只是”AI画图变强了”。
它意味着：
官方已经开放入口，直接在ChatGPT里就能体验（Try in ChatGPT）。有Horizontal / Square / Vertical三种画幅，还新增了Image mode和Classic mode两种模式切换。
建议你今晚就去玩一把，不夸张地说——
你今天玩到的，就是明年广告公司、自媒体、电商设计师正在卷的东西。
下面是本期视频中实测用到的所有Prompt，按场景分类整理，方便你直接复制使用。
用红线划出迷宫从入口到出口的最短路线图：
为这首宋词生成一幅与词中意境相匹配的画：
**长相思·伤春**
花又残，雨又寒，
一夜东风吹梦难。
啼莺隔小阑。
柳丝闲，雁书悭，
满地香尘不忍看。
春归人未还。
将这首词生成一张书法作品
还原成彩色照片
将图像改成油画风格
将图像还原为真实的照片风格
手绘涂鸦风格的射箭打卡日记，竖版构图，米黄色格纹笔记本纸张质感，拼贴风格。页面顶部写着"2026年4月22日 星期三"标题，右上角有黑色素描风格的拉弓射箭男人剪影和手写"ARCHERY"字样。中间部分是手绘的靶场射箭靶纸图案，红黄蓝黑白同心圆箭靶，上面用彩色（绿→黄→橙→红渐变）小箭头标注每一轮射箭的落点，标有第1箭、第2箭、第3箭、第4箭、第5箭节点和对应环数。左侧信息栏用蓝色、红色、绿色马克笔手写记录：地点"大王山射箭馆"、距离"30米"、类型"反曲弓训练"、心率"95bpm"、专注度"2-3区"、每轮得分数据。下方有红色折线图的命中环数曲线
生成这个毛坯房装修后照片，装修风格为现代简约
后续修改（北欧风格）：
再生成一张北欧风格的装修后的照片
将图中老者钓鱼的鱼竿换成路亚竿，老者的姿势改成路亚钓
阅读Agent Skills官方文档：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
然后画出Agent Skills的架构图
生成一张iOS端app的登陆页
超写实电影感概念摄影：一只巨型 机械鹤（同时是塔吊） 伫立在建筑工地上——鸟身与长颈由桁架钢架构成，红顶钢喙延伸成塔吊臂，钢索下方正吊起一块混凝土配重；地面有戴安全帽的小工人作尺寸对比，远景是黄昏城市天际线与在建高楼。金属工业细节高度写实，金色 magic hour 落日配冷蓝云层，低角度仰视构图，史诗感十足。视觉双关玩 "crane = 鹤 / 起重机"，4:5 竖版。
仿《TIME》杂志封面：标志性红色粗边框 + 白色衬线大号 "TIME" Logo。中央为电影感 CG 视觉：一个巨大暗色多面体悬浮在荒原湿地上，棱边发出蓝色霓虹光，落日余晖与远山剪影，一个小小的人物背影仰望它。下方白色无衬线大字副标题 "[AI超元域]" 与小字说明 "[突破10万粉丝]"。深蓝紫 + 橙色夕阳的高反差末世科技氛围，4:5 竖版。
短版prompt：
Make me a 360 image of Paris in 1920.
详细版prompt：
一张 1920 年代巴黎街头的 360° 全景照片，
等距圆柱投影格式（Equirectangular Projection），宽高比严格为 2:1，
分辨率 8192×4096，适合用于 VR 全景查看器与 Google Street View。
【场景设定】：1920 年的巴黎，春日午后，阳光明媚，
蓝天中飘着几朵松软的积云。画面以街道中央为观察点，
四周 360 度完整展开城市风貌。
【左前方】：经典的巴黎老式咖啡馆"Café de Flore"，
墨绿色遮阳棚、金色手写体店招、藤编椅与圆形大理石桌，
几位戴礼帽的绅士与穿及膝连衣裙、戴钟形帽的女士围坐喝咖啡，
一位穿白围裙黑马甲的侍者正端着托盘走出店门。
【正前方 / 街道中央】：奥斯曼风格的米白色石砌公寓
英文标题版：
创作一幅以 "visual polyglot（视觉通才）" 为主题的杂志风拼贴页，画面中央标题为 "Create Everything at Once"。采用非网格的、发散式的艺术排版，融合科学图解、元素周期表、太阳系、中世纪手稿、植物与解剖插图、古地图、工程图纸、多语言文字、漫画分格、UI 截图、蝴蝶标本、图表、建筑蓝图、像素艺术、雕塑、绘画等多元视觉元素。整体呈现高端研究宣言或博物馆式宣言的气质：优雅、有野心，色彩鲜艳（避免米色调）。4:5 竖版，除中央标题外不添加其他说明文字（作为画面一部分的文字可以保留）。
中文标题版：
杂志风拼贴艺术海报，中央大标题 "一次创造万物"。发散式自由排版（非网格），融合科学图解、周期表、太阳系、古地图、中世纪手稿、植物与解剖插画、建筑蓝图、漫画分格、UI 截图、蝴蝶标本、像素艺术、雕塑与绘画等多元视觉元素。博物馆宣言式的优雅气质，色彩鲜艳（避免米色调），4:5 竖版，除中央标题外不加额外说明文字。
一张放在木桌上的白色餐巾纸,上面用铅笔速写一位长发女性的正面肖像,旁边有一圈淡淡的咖啡渍,手机随手拍摄。
厚涂油画笔触的日系动漫插画：一位黑色齐刘海长发少女站在东京原宿街头，穿着宽松白色连帽卫衣，卫衣上点缀着随性的彩色油画笔触；背景是 "原宿"、"Laforet" 招牌和熙攘人群的色块化建筑。印象派厚涂油画质感，紫青橙黄的高饱和互补配色，青春文艺氛围，4:5 竖版。
手绘水彩插画风旅行攻略海报：以 [广州] 行政区划地图为主体，每个区用糖果色水彩块填色，虚线分界；地图上手绘当地地标建筑、山水、美食小图标。顶部糖果色描边手写体大标题 "[广州]吃货和游玩地图"，搭配太阳、彩虹、云朵、帆船等可爱贴纸。四周圆角卡片分区列出"玩/吃"要点并配美食插画；右下角戴渔夫帽、拿糖葫芦和相机的卡通女孩吉祥物，左下角木牌写 "快乐出游 快乐干饭"。暖米黄背景 + 高饱和糖果色，小红书治愈风，4:5 竖版。
19 世纪末美好年代学院派油画肖像（Sargent / Boldini 风格）：一位端庄优雅的年轻女士四分之三侧身站在昏暗的古典厅室内，深色盘发、柔光打亮面部。她身穿紧身胸衣 + 泡泡短袖的拖地长 A 字晚礼服，裙身如同一幅展开的风景油画——胸口是远方城堡，从腰际到裙摆绘着山谷、河流、树林与田园，颜料笔触与丝缎褶皱浑然一体。左侧有刺绣白纱帘与窗框，右侧深绿墙面前一张巴洛克雕花木桌与瓷瓶。厚涂油画技法，暖棕、奶白、墨绿的古典配色，戏剧性明暗对比，博物馆藏画气质，4:5 竖版。
桌面近摄照片：一页米白色笔记本纸斜放在深色木桌上，背景浅景深虚化，右上方一束柔和窗光。纸上是一枚用红蓝两色蜡笔涂鸦的卡通火箭（线条粗糙、颜色涂不均、有蜡笔颗粒感），旁边用黑色圆珠笔手写英文工程笔记，关键词加下划线并用手绘小箭头指向火箭部位，内容如 "Images 2.0 with thinking"、"Stage II — Liquid fuel, gimballed engine"、"Payload 3000 lbs"、"thrust"、"ORION"。童趣 + 工程手稿感，米色纸张 + 红蓝蜡笔 + 黑笔字的低饱和暖调，写实摄影质感，4:5 竖版。
字幕最后说还有很多图像没有逐一展示，prompt也一并放在笔记中，供大家继续探索。
一张仿《纽约时报》头版报纸被斜放在深色木桌上的 45° 俯拍写实照片，暖色侧光，纸张有真实褶皱与新闻纸质感。严格遵守 NYT 排版：哥特体报头、日期版次、多栏 Serif 衬线正文；大通栏主标题 "[AI超元域]"，副标题 "[突破10万粉丝]"；中央一张大幅黑白新闻摄影配图，左右两栏为 "Wall Street Reacts" 和 "What This Means" 分栏评论，底部含一条走势折线图。写实摄影风格，4:5 竖版。
复古剪贴拼贴海报（欧式老杂志 / 丝网印刷风），米白毛糙纸张质感。上半部为撕边拼贴：一位条纹衫黑白老照片女郎正看着一份旧报纸，背景由红、黄、蓝三色撕纸色块与黑白街景、法文字片拼接。中部是巨大、错落叠压的粗体无衬线三原色大标题 "GPT Image 2.0"（GPT 黑、Image 红、2.0 蓝），下方黑色粗笔刷横条压着白字 "即将上线"。底部大号黑色衬线中文标题 "OpenAI 正式推出 ChatGPT Images 2.0"，再下方一排社交平台图标与账号。红黄蓝三原色 + 黑白照片的达达主义配色，撕边毛边颗粒感，4:5 竖版。
瑞士国际主义 / 包豪斯风格海报，做旧米白褶皱纸张质感。左侧大号黑色无衬线粗体中文标题 "正式推出 ChatGPT Images 2.0"，下方红色副标题 "图像生成的新纪元"，再下方多段左对齐小字正文排版；右侧为蒙德里安式几何构成：正红圆形、蓝色矩形、黄色方块、黑色半圆与平行黑色细条纹，由垂直水平基准线精确切分。米白 + 红蓝黄 + 黑的克制三原色配色，理性克制的宣言式气质，4:5 竖版。
俯拍平铺摄影海报：浅灰色设计师桌面正上方视角，中央是一台显示彩色画面的宽屏显示器，周围对称整齐地排列着相机镜头、音箱、笔、剪刀、平板、调色盘、色卡、颜料瓶等创意工具。画面中央叠加大号白色无衬线中文标题 "一次创造万物"，下方小字 "即将上线"。写实摄影质感，整洁专业，4:5 竖版。
Color block 极简摄影美学,正面平视视角,一栋粉色平顶小屋孤立在橙红色沙漠中,天空是一整块纯钴蓝,屋顶有一根薄荷绿的烟囱;画面被水平分割成三大色块(天空 / 房子 / 地面),对称、安静、超现实,Palm Springs 中世纪建筑风格,强烈的几何秩序感。
Risograph 印刷风格插画,荧光粉与薄荷绿双色套印,一只坐着的胖橘猫正面肖像,轮廓用粗黑线勾勒,毛发以半调网点表现;背景是简单的几何图形和手写英文字母拼贴;油墨不均、略有错版、纸面有轻微颗粒与折痕,温暖的手工感,独立艺术家 zine 风格。
理想孔版印刷(Risograph)风格的双色海报,荧光粉红与荧光绿两种专色套印,画面中央是一个张大嘴尖叫的朋克青年,头发竖起呈锐利的尖刺状,背后有爆炸式放射图形;左右两侧拼贴着模糊的黑色人物剪影,边缘粗糙像被撕下的报纸;整体带有明显的半调网点、颗粒噪点、油墨错位和纸张折痕,低保真 DIY 朋克 zine 美学,1980年代地下音乐海报感。
维多利亚时代植物图鉴风格插页，泛米色旧纸质感。顶部页眉 "BOTANICAL ATLAS · PLATE XLVII · NATURAL HISTORY"，中央用花体 Serif 大字写学名 "[拉丁学名]"，下方副标题 "[植物俗名] / Family, [科名]"。中心是水彩钢笔线描的盆栽主图，周围环绕多个标号小图（Fig. 2 花正面、Fig. 3 花纵剖、Fig. 4 叶、Fig. 5 根茎、Fig. 6 雄蕊与雌蕊、Fig. 7/8 花苞），用细线引出各部位英文术语标注，说明文字为古典衬线小字。彩蛋：在其中一个花苞内藏着一位透翅花仙子，用同样严谨的博物学口吻把她作为物种描述。水彩 + 钢笔描边，典雅橙红与叶绿配色，四角有小卷草装饰
每一次OpenAI的更新，都像是在提醒我们一句老话——
“工具永远不会淘汰人，但会用工具的人，会。”
这一次，轮到图像生成了。
你准备好了吗？👀
]]>💡 方案一适合想要零配置、零成本快速上手的新手；方案二解决了聊天软件中使用 Hermes 的各种痛点，带来媲美 ChatGPT 的交互体验；方案三则是高阶省钱技巧——用主副模型分工策略大幅降低 Token 消耗。
Ollama 已内置 Hermes Agent，所以不需要单独部署 Hermes，只需要：
Step 1：下载并安装 Ollama
Step 2：查看集成项
打开 Ollama 后可以看到已集成：
Step 3：复制启动命令并在终端执行
在 Ollama 界面复制 Hermes 的启动命令，回到终端运行，进入模型选项界面。
Step 4：选择模型
推荐模型列表中，前几个模型后缀带 Cloud，表示可通过 Ollama 云端使用（不占用本地资源）。
演示中选择的是：MiniMax M2.7
Step 5：登录账号
Step 6：完成 Gateway 刷新与 App 连接
Step 7：验证模型
提问”你是什么模型”，返回：MiniMax M2.7 云端版本 ✅
| 特性 | 说明 |
|---|---|
| ✅ 部署方式 | 一条命令完成全部配置 |
| ✅ 费用 | 免费使用云端模型额度 |
| ✅ 资源占用 | 零本地资源占用 |
| ✅ 上手难度 | 适合新手小白快速上手 |
直接在聊天软件中使用 Hermes Agent 存在以下局限：
Hermes Agent 原生支持 Open WebUI，通过这种方式可以获得以下体验：
按照 Open WebUI 官方仓库的安装命令进行安装，复制官方给出的安装命令，在终端直接执行即可。
用编辑器（Antigravity / 记事本 / VS Code 均可）打开 Hermes Agent 配置文件，添加两个参数：
| 参数 | 作用 |
|---|---|
| 启用 API 服务参数 | 为 Hermes Agent 启用 API 服务 |
| API 密码参数 | 为 API 设置访问密码（可自定义） |
保存配置文件即可。
💡 懒人方案：也可以直接让 Codex / Claude Code 等任何支持操作本地文件的 Agent，用自然语言描述需求（告诉它配置文件位置和要添加的两个参数），自动完成配置。
在终端执行重启命令，让配置生效。
复制 Open WebUI 官方的启动命令，在终端执行启动。
浏览器访问：localhost:8080
配置项填写：
| 字段 | 填写内容 |
|---|---|
| URL | http://localhost:8642/v1（本地 Hermes Agent，端口 8642，后缀 /v1 表示兼容 OpenAI API 的接口） |
| 认证 | 刚才在配置文件中设置的 API 密码 |
点击 保存。
验证测试：提问”你可以调用哪些 Skill” → 返回 118 个 Skill ✅
可以直接在手机上通过 Open WebUI 与电脑上的 Hermes Agent 交互：
http://<电脑IP地址>:8080手机端效果：
如果需要在 公网环境 通过手机访问本机 Hermes Agent：
这是最高阶的玩法——通过配置 MiniMax-CN 主模型 + Gemini 副模型，让核心对话走高质量模型，辅助任务走免费/低价模型，从而大幅节省 Token 消耗。
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak-$(date +%Y%m%d-%H%M%S)
编辑 ~/.hermes/.env，确保以下三个 key 存在：
MINIMAX_CN_API_KEY=<你的 MiniMax 国内 key>
GOOGLE_API_KEY=<你的 Google AI Studio key>
OPENAI_API_KEY=<你的 OpenAI key>
编辑 ~/.hermes/config.yaml，将 model: 块改为：
model:
api_key: env:MINIMAX_CN_API_KEY
base_url: https://api.minimaxi.com/anthropic
default: MiniMax-M2.7
provider: minimax-cn
要点：
base_url 不要带 /v1（SDK 自动追加）MiniMax-M2.7provider 必须是 minimax-cn（国内端点）auxiliary: 块保持如下结构，全部走 Gemini 2.5 Flash（免费额度大、速度快）：
auxiliary:
approval:
provider: gemini
model: gemini-2.5-flash
timeout: 30
compression:
provider: gemini
model: gemini-2.5-flash
timeout: 120
flush_memories:
provider: gemini
model: gemini-2.5-flash
timeout: 30
mcp:
provider: gemini
model: gemini-2.5-flash
timeout: 30
session_search:
provider: gemini
model: gemini-2.5-flash
timeout: 30
skills_hub:
provider: gemini
model: gemini-2.5-flash
timeout: 30
title_generation:
provider: gemini
model: gemini-2.5-flash
timeout: 30
vision:
provider: gemini
model: gemini-2.5-flash
timeout: 30
download_timeout: 30
web_extract:
provider: gemini
model: gemini-2.5-flash
timeout: 360
compression:
enabled: true
protect_last_n: 20
target_ratio: 0.2
threshold: 0.5
⚠️ 不要在这里放
summary_model/summary_provider/summary_base_url，模型选择统一在auxiliary.compression中配置。
custom_providers:
- api_key: ""
api_mode: chat_completions
base_url: https://generativelanguage.googleapis.com/v1beta
name: google-ai
- api_key: ""
api_mode: anthropic_messages
base_url: https://api.minimaxi.com/anthropic
name: minimax-custom
要点：
name 不能与内置 provider 同名api_mode 必须与 base_url 端点格式一致：
/anthropic → anthropic_messages/v1 → chat_completions所有 mcp_servers.*.env 下的 key 都用 env: 前缀引用，不要写明文：
mcp_servers:
gbrain:
command: gbrain
args: [serve]
env:
OPENAI_API_KEY: env:OPENAI_API_KEY
connect_timeout: 15
timeout: 30
# YAML 语法检查
python3 -c "import yaml; yaml.safe_load(open('$HOME/.hermes/config.yaml'))" && echo OK
# 配置诊断
hermes doctor
# 功能测试
hermes chat -q "Say exactly 'pong' and nothing else." -Q
期望输出：
session_id: ...
pong
如果配置出现问题，随时可以回滚：
cp ~/.hermes/config.yaml.bak-<时间戳> ~/.hermes/config.yaml
| 方案 | 适合人群 | 核心优势 | 难度 |
|---|---|---|---|
| Ollama 一键集成 | 新手小白 | 零配置、免费模型、3分钟上手 | ⭐ |
| Open WebUI | 日常重度使用 | ChatGPT 级交互体验、多端访问 | ⭐⭐ |
| 主副模型分工 | 高阶玩家 | 大幅省 Token、灵活配置 | ⭐⭐⭐ |
三个方案可以组合使用：用 Ollama 快速启动 + Open WebUI 美化界面 + 主副模型分工省钱，打造最强 Hermes Agent 使用体验！
]]>