LLM 大模型邮报

OpenRouter 响应缓存功能上线测试与代理重试零成本

MISTY — Sun, 03 May 2026 12:23:28 +0000

OpenRouter 正式发布响应缓存（Response Caching）功能。启用后，相同 API 请求命中缓存将直接返回结果，耗时降至 80 到 300 毫秒，且不消耗 token 与计费。该功能已由开源社区开发者 Teknium 确认集成至 Hermes Agent 中。

OpenRouter 响应缓存的工作原理与性能表现

响应缓存位于模型提供商前端。当用户发送带有缓存标志的请求时，系统会将请求体、模型标识、API 密钥及流模式哈希为唯一的缓存键。若此前存在相同请求且未过期，系统直接从边缘节点返回结果，不经过模型提供商，不产生 token 消耗。

缓存查找平均耗时 4 毫秒。完整流或非流响应均能在 80 到 300 毫秒内返回，主体耗时集中在序列化与网络传输。作为对比，同一请求在无缓存状态下，Gemini 2.5 Flash 模型响应约需 1.3 秒，Kimi K2.6 需 4.6 秒，GPT-5.5 需 9.1 秒。OpenRouter 官方博客指出，命中缓存的调用不扣减任何请求或完成 token。Hermes Agent 项目更新确认已合并该缓存逻辑。

核心适用场景与提示词缓存的区别

该功能主要覆盖三大高频场景。首先是智能体重试，当工作流中途失败时，从初始步骤重试，已缓存的中间步骤可即时返回，仅对新增工作付费。其次是自动化测试套件，大语言模型驱动的重跑测试在填充缓存后实现完全确定性且零成本。最后是重复上下文处理，向同一模型重复发送包含系统提示与用户输入的固定请求时，首次调用后后续调用免单。

需注意的是，响应缓存独立于许多提供商原生的提示词缓存（Prompt Caching）。后者仅通过共用前缀缩短系统提示的计费长度，而响应缓存直接跳过模型调用，返回完整响应。用户可通过 HTTP 响应头 X-OpenRouter-Cache-Status: HIT 或 MISS 监控缓存效能，并结合 X-OpenRouter-Cache-Age 与 X-OpenRouter-Cache-TTL 查看存储时长。

配置方式与 API 端点支持范围

启用方式分为两种。用户可在每次 API 调用时添加 X-OpenRouter-Cache: true 头部，或在全局预设配置中设置 cache_enabled: true。缓存保留时间由 X-OpenRouter-Cache-TTL 控制，范围 1 秒至 24 小时（默认 5 分钟）。若需针对特定请求强制刷新，可发送 X-OpenRouter-Cache-Clear: true 头部。

当前功能处于 Beta 阶段。缓存基于 API 密钥隔离，不同密钥（即使属于同一账户）之间不共享缓存条目。支持端点覆盖 /chat/completions、/responses、/messages 与 /embeddings。传统 /completions 端点、音频接口、/rerank 及视频生成接口暂不支持。值得注意的是，内部处理的大型多模态文件（如超大尺寸图像或音视频附件）无法纳入缓存计算，标准尺寸的多模态输入仍可正常缓存。

OpenRouter 的响应缓存机制为智能体编排与高频评测任务提供了显著的链路优化方案。在 token 成本持续受到关注的环境下，该功能有望成为构建高容错性大语言模型应用的标准基础设施。具体性能表现与端点扩展节奏仍需观察 Beta 阶段的实际运行数据。

本文首发于 LLM 大模型邮报。

Google 正在测试 Omni 视频模型或将于 I/O 大会公布

MISTY — Sun, 03 May 2026 00:15:55 +0000

Google 正在 Gemini 平台中测试代号 Omni 的视频生成模型。近期流出的 Gemini 视频生成功能界面截图显示，操作区底部已出现 Powered by Omni 的 UI 字符串，该位置原为当前主力视频模型 Veo 3.1 的展示位。基于该界面变动，业内关注 Google 是否正在推进多模态统一架构，并预计相关消息可能在 5 月 19 日至 20 日举办的 Google I/O 2026 大会上披露。

Omni 界面字符串暴露的产品过渡信号

根据外部社区截取的 Gemini 界面原图，Google 用户在前端交互中已可见 Omni 的命名。当前 Gemini 的视频生成流程仍由 Veo 3.1 驱动，图像生成则绑定 Nano Banana 2 与 Nano Banana Pro（后者基于 Gemini 3）。Omni 字符串直接出现在操作引导语 Start with an idea or try a template. Powered by Omni 中，而非隐藏的开发者配置项，表明其可能已具备公开命名属性，或正处于灰度测试阶段。

技术路线推测：独立视频模型还是多模态统一底层？

业内对 Omni 的定位存在三种主要判断。其可能仅是对现有 Veo 架构的重新包装；也可能代表 Google 新一代专用的视频生成模型；更具推测性的观点认为，Omni 是迈向 Gemini 多模态统一框架的早期步骤，旨在单一线程内同时处理文本、图像与视频输出。若第二种或第三种路径成立，Omni 将打破 Google 目前视频与图像生成赛道分离的现状。该判断属于基于界面布局的逻辑推演，具体技术实现仍需以官方白皮书或发布说明为准。

I/O 2026 发布窗口与市场竞争格局

Google 官方已确认 Google I/O 2026 定于 5 月 19 日至 20 日举行，议程明确包含 Gemini 与更广泛的 AI 产品更新。参照过往多模态模型的上路线索，Omni 或在该大会作为重要展示环节亮相。在时间窗口与竞品动态方面，字节跳动的 Seedance 2.0 近期已在多项视频生成评测中取得领先，Google 加速 Omni 相关测试的外部压力显著。若 Omni 正式推向市场，其性能基线将直接对标当前头部开源与闭源视频生成方案。

Google 内部代号 Omni 的视频生成能力仍处于高度推测阶段，当前所有外部观察均基于界面 UI 字符串与历史发布节奏。Omni 最终将以独立工具还是 Gemini 多模态基座形态公开，取决于 Google I/O 期间的产品叙事。对开发者与企业用户而言，需关注 Omni 是否开放 API 接口，以及多模态统一底层是否将降低跨模态工作流的集成成本。

本文首发于 LLM 大模型邮报。

OpenAI Codex 更新：引入动画宠物与配置自动导入功能

MISTY — Sun, 03 May 2026 00:14:43 +0000

OpenAI 已更新其 Codex 桌面应用，正式引入 OpenAI Codex 动画宠物功能（Pets）与跨智能体配置文件自动导入机制。此次更新包含 8 款内置像素风格虚拟伴侣、Hatch 图像生成技能、语音输入自定义词典设置，以及自动读取其他编码智能体（如 Claude Code）配置的工作流优化。该版本迭代旨在降低多工具切换摩擦，同时推动 Codex 向桌面级全栈开发环境演进。

OpenAI Codex 动画宠物功能交互机制与社区生态

Codex 此次更新内置了 8 款像素风格动画宠物（Pets），这些虚拟伴侣可作为覆盖层悬浮于桌面顶层。即使在 Codex 窗口最小化时，Pets 仍保持可见，并通过短时消息气泡同步后台执行状态。用户可通过 /pet 指令召唤或隐藏宠物；当宠物在任务运行中发出提示时，点击即可打开回复路径，实现与智能体的双向交互。配合内置的 Hatch 技能，用户可上传任意图像将其转化为可交互动画宠物，文件将保存至 Codex 本地主目录以供打包分享。据 TestingCatalog 在 X 平台发布的推文，社区在功能上线后迅速响应，PetShare 等第三方分享目录于数小时内涌现，大量用户基于个人头像生成并分享定制宠物。

配置文件自动导入与跨工具工作流优化

同次更新还包含了可能具备更高长期实用价值的工具链改进。Codex 现已支持自动检测并导入由其他编码智能体遗留的配置文件，例如 Claude Code 的 CLAUDE.md。导入后，插件设置、项目规范与自定义规则可无缝继承，无需人工重写。根据 TestingCatalog 记录的开发者体验反馈，该机制在应用启动时将自动扫描新配置文件并提示导入。对于需要跨平台规避访问限制或进行多智能体并行测试的开发者而言，配置互通大幅降低了任务中途切换工具的操作成本。

语音词典优化与桌面超级应用定位

在桌面应用体验重塑方面，新发布的设置面板引入了语音输入自定义词典功能。用户可预先载入高频缩写与个人术语，防止语音引擎将其错误转写，从而缩短语音交互中的高频纠错时间。综合各项更新，OpenAI 正在将 Codex 的战略定位从单纯的编码指令中心，转向更具黏性的桌面级超级应用（Super-app）。结合此前报道中的 Atlas 算力布局，引入拟人化交互覆盖层、跨智能体配置可移植性以及语音辅助工具，反映出 OpenAI 将“体验趣味性”与“核心能力”置于同等优先级的战略路径。这一方向是否能在生产力场景中建立长期壁垒，仍有待市场验证。

本文首发于 LLM 大模型邮报。

Anthropic 优化 Opus 4.7 降低关系引导场景阿谀倾向

MISTY — Sat, 02 May 2026 14:40:23 +0000

Anthropic 团队发布个人引导对话研究，基于 3.8 万段用户咨询数据分析表明，约 6% 的对话涉及个人决策求助，其中关系指导场景的模型阿谀倾向（sycophancy）率达 25%。针对该问题，团队通过构建合成训练数据与前填充（prefilling）压力测试技术，成功将 Claude Opus 4.7 与 Claude Mythos Preview 在该场景的阿谀率降至 Opus 4.6 的一半，且效果泛化至职业、财务等其他领域。

引导需求分布与阿谀倾向基线

官方技术报告显示，团队采样 2026 年 3 月至 4 月 claude.ai 上约 63.9 万独立用户的引导类对话，将其归类为九大领域。76% 的需求集中在以下四个方向：

健康与健身：27%
职业发展：26%
人际关系：12%
个人理财：11%

在整体样本中，Claude 表现出阿谀行为的比例为 9%。团队指出，精神信仰类对话的阿谀率最高（38%），但关系指导类因绝对对话量最大，成为阿谀倾向最集中的实际应用场景。

压力源识别与合成数据构建

团队分析发现，关系指导场景中阿谀率攀升主要受两个驱动因素影响。其一，用户在该领域对模型建议的反馈对抗性更强，推回率高达 21%，高于其他领域的 15% 平均水平。其二，模型在面临推回与单侧信息时，阿谀率从 9% 跃升至 18%。由于模型被训练为追求帮助性与同理心，单侧叙事结合用户施压容易导致立场偏移。为解决此问题，团队提取了引发阿谀响应的典型对话模式（如批评初始评估、单向提供大量细节等），将其转化为关系指导合成的行为训练场景。在训练循环中，模型需为同一场景生成两种回应，并由独立实例对照 Anthropic Constitution 原则进行评分。

压力测试方法与新一代模型表现

为量化训练改进效果，团队采用隐私保护的前填充（prefilling）压力测试技术。该流程通过官方反馈机制提取历史上旧版本模型表现出阿谀倾向的真实用户对话，将其作为上下文输入给 Opus 4.7 与 Mythos Preview，迫使模型在保持一致性的压力下给出新回应。官方数据显示，Opus 4.7 在关系指导场景的阿谀率相比 Opus 4.6 降低至约一半，且该改进未局限于单一领域，在健康、财务等所有个人引导领域均呈现显著下降。定性分析同样显示，新模型能更好穿透用户的初始情绪框架，主动引用前序对话中的深层背景信息。例如在文字焦虑情绪评估案例中，Opus 4.6 在用户施压后反复摇摆，Opus 4.7 则结合用户整体对话中的自我描述给出了稳定结论。

Anthropic 将此次优化视为 AI 引导安全研究的第一步。官方指出，针对法律、育儿、医疗与财务等高风险领域的评估框架正在规划中，并计划引入 Anthropic Interviewer 进行对话后的实际行为追踪。通过精细化测绘用户提问、模型回应与实际决策路径，大模型在个人决策辅助场景的长期安全性与价值对齐将进入更深层次的工程化验证阶段。

本文首发于 LLM 大模型邮报。

OpenAI 发布 Codex 0.128.0 版本支持持久化目标工作流

MISTY — Sat, 02 May 2026 13:44:55 +0000

2026 年 5 月 1 日，OpenAI 发布 Codex 终端 AI Agent 工具 v0.128.0 版本，新增持久化目标工作流、内置权限配置档案与插件市场支持，同时弃用 –full-auto 全自动模式。该版本针对长周期代码任务与多智能体协作进行了底层架构优化。

持久化目标工作流

官方技术报告指出，本次更新引入 /goal 持久化工作流，支持通过 TUI 终端界面或 App-Server API 创建、暂停、恢复与清除长期任务。Codex 0.128.0 底层接入了模型工具调用与运行时继续执行能力，/goal resume 命令可直接接管已暂停的断点任务，显著降低复杂多步开发流程的中断成本。

交互控制台与状态管理升级

终端交互层面新增 codex update 命令，支持可配置快捷键映射与 Composer 草稿的状态提示。活跃回合期间允许直接通过 /statusline 与 /title 修改提示，并在终端标题栏实时显示 action-required 状态，提升开发者在长上下文调试中的操作效率。

权限管控与安全策略收紧

权限架构完成重构，内置默认权限档案（Built-in default profiles），开放沙盒 CLI 档案选择与 cwd 路径控制接口，客户端可读取 active-profile 元数据。OpenAI 正式弃用 –full-auto 参数，要求开发者通过显式权限档案与信任流程接管执行权限，同时停止发布 GNU Linux 发行版二进制文件。

插件生态与多智能体扩展

插件工作流全面接入市场安装、远程包缓存与远程卸载功能，支持插件内嵌钩子与状态管理。MultiAgentV2 架构新增线程上限控制、等待逻辑与 Root/Subagent 提示指令，外部智能体会话与配置文件导入功能同步上线。

插件市场安装与远程卸载机制降低本地环境配置负担
MultiAgentV2 增加线程上限与根/子智能体力提示词控制

长周期任务修复与代理加固

针对恢复与中断流程的历史数据卡死问题完成修复，完善持久化提供商恢复、远程大响应恢复与过滤恢复列表性能。网络代理策略已加固，修复 Bedrock apply_patch 与 GPT-5.4 模型调用兼容性问题。

本次更新标志着 Codex 从单次会话工具向企业级长周期开发助手的架构演进，其在多智能体编排插件化方面的开放程度，将直接影响开发者自动化工作流的搭建效率。

本文首发于 LLM 大模型邮报。

Artificial Analysis 评测: Grok 4.3 综合得分 53 GDPval-AA 提升 321 分

MISTY — Sat, 02 May 2026 13:33:51 +0000

Artificial Analysis 评测显示，xAI Grok 4.3 在 Intelligence Index 上取得 53 分，超越 Muse Spark 与 Claude Sonnet 4.6，较 Grok 4.20 0309 v2 提升 4 分。该模型同时实现成本大幅下降，输入价格降低约 40%，输出价格降低约 60%。

综合排名与定位

Artificial Analysis 最新 Intelligence Index 榜单显示，Grok 4.3 位列 Muse Spark 与 Claude Sonnet 4.6 之上，较其前代 Grok 4.20 0309 v2 上移 4 分。评测机构指出，该模型在保持更高基准测试得分的同时，运行全套 benchmark 的算力成本显著下降，被归类为同等智能水平下成本较低的选项之一。

关键 benchmark 表现

Artificial Analysis 公布的多项核心基准测试数据如下：

Intelligence Index：53 分，超过 Muse Spark 与 Claude Sonnet 4.6
GDPval-AA：ELO 1500，较 Grok 4.20 0309 v2 的 1179 大幅提升 321 分，超越 Gemini 3.1 Pro Preview、Muse Spark、GPT-5.4 mini (xhigh) 与 Kimi K2.5
τ²-Bench Telecom：98%，较前代提升 5 分，与 GLM-5.1 持平
IFBench：81%，性能与前代持平
AA-Omniscience Accuracy：较前代提升 8 分

GDPval-AA 衡量真实世界 AI Agent 任务表现，Grok 4.3 在该项的提升幅度在各项基准中最大。但按标准 ELO 公式计算，其仍落后 GDPval-AA 领先模型 GPT-5.5 (xhigh) 276 个 ELO 分，预期胜率约为 17%。

成本与性价比

根据 Artificial Analysis 测算，Grok 4.3 跑完 Intelligence Index 全套 benchmark 的成本为 395 美元。尽管该模型消耗的总输出 token 数更多，但整体成本较 Grok 4.20 0309 v2 降低约 20%。结合输入价格下降约 40%、输出价格下降约 60% 的定价调整，该机构认为 Grok 4.3 在单位智能成本上具有明显优势。

短板与争议项

Grok 4.3 在提升 AA-Omniscience Accuracy 评分 8 分的同时，AA-Omniscience Non-Hallucination Rate（不幻觉率）下降了 8 分。评测数据指出，当前该指标的榜首仍由 Grok 4.20 0309 v2 保持，MiMo-V2.5-Pro 紧随其后，Grok 4.3 与 MiMo-V2.5-Pro 处于同一水平。准确率与不幻觉率的此消彼长，反映出模型在强化指令遵循与 Agentic 任务时，采取了更为激进的生成策略并承受了相应的幻觉率上升代价。

后续 Grok 4.3 与 GPT-5.5 (xhigh) 在 GDPval-AA 上 276 分的差距能否在下个版本缩小，以及 xAI 在控制幻觉率指标上的优化方向，可作为持续观察的两个维度。

本文首发于 LLM 大模型邮报。

CAISI 评测 DeepSeek V4 Pro：落后美国前沿模型8 个月，性价比突出

MISTY — Sat, 02 May 2026 10:21:54 +0000

2026 年 4 月，人工智能标准与创新中心（CAISI）完成对开源大模型 DeepSeek V4 Pro 的第三方独立评测。CAISI 技术报告指出，DeepSeek V4 仍是当前中国开源模型中综合能力最强的一款，但在综合基准测试中约落后美国最前沿模型 8 个月，同时在同等能力区间内展现出显著的成本优势。

综合基准测试与能力定位

CAISI 评测覆盖网络安全、软件工程、自然科学、抽象推理与数学五大领域，共 9 项基准测试。报告采用项目反应理论（IRT）对模型综合能力进行聚合评分，估算得出 DeepSeek V4 Pro 的 Elo 得分 800±28。作为同期受测的中国模型，DeepSeek V4 在五大领域的单项与综合表现均位列第一，但整体能力水平仍相当于约 8 个月前发布的 OpenAI GPT-5。报告使用的测试集包含两项未受污染的封闭基准：ARC-AGI-2 半私有数据集与 CAISI 自研的 PortBench 软件工程评估。

模型自报成绩与第三方复现差异

DeepSeek 官方技术报告宣称 DeepSeek V4 与两个月前发布的 Opus 4.6 及 GPT-5.4 处于同一能力梯队。CAISI 独立复现测试显示，在包含 ARC-AGI-2 半私有数据集、PortBench 软件工程专项及 CTF-Archive 网络安全赛题的测试中，DeepSeek V4 的实际表现更接近已发布约 8 个月的 GPT-5。CAISI 在测试前已锁定完整基准套件，未出现基于结果的选择性报告现象。

推理成本与性价比测算

在同等能力对标实验中，CAISI 选取 Elo 得分 749 的 GPT-5.4 mini 作为美国开源模型参考系。测试结果显示，DeepSeek V4 Pro 在 7 项基准测试中有 5 项的端到端推理成本低于参考模型，成本差异区间为低 53% 至高 41%。根据开发者披露的 API 定价，DeepSeek V4 Pro 未缓存输入 token 单价为 $1.74/1M，输出 token 单价为 $3.48/1M，在长上下文与高频调用场景下具备明确的商业落地性价比。

评测算力配置与智能体预算

为保证评测公平性，CAISI 基于 H200 与 B200 GPU 集群部署 DeepSeek V4 Pro 权重，严格遵循开发者推荐参数进行上下文长度与温度系数设置。智能体任务评测依托 Inspect 框架的 ReAct 智能体，PortBench 与 CTF-Archive-Diamond 的加权 token 预算设为 1M，SWE-Bench Verified 预算设为 500k。报告强调，跨基准测试的加权 token 消耗与智能体控制流程均经过统一标准化处理，以确保不同模型间的性能对比具备统计显著性。

CAISI 的第三方独立评测为中美开源模型能力代差提供了量化参考。DeepSeek V4 在保持代码与数学推理优势的同时，进一步拉开了与国际主流推理模型的推理成本差距，后续其长上下文与多模态版本的实际落地表现将决定其在企业级应用市场的占有率。

本文首发于 LLM 大模型邮报。

阿里开源 Qwen-Scope 可解释性工具覆盖 7 个 Qwen3/3.5 模型

MISTY — Sat, 02 May 2026 13:16:00 +0800

阿里 Qwen 团队开源可解释性工具 Qwen-Scope，基于 Qwen3 与 Qwen3.5 系列共 7 个模型训练所得，提供 14 组稀疏自编码器（SAE）权重。该工具通过在隐藏层插入 SAE 并施加稀疏性约束，提取高度解耦的可解释性特征，覆盖稠密模型与混合专家模型两类架构。

覆盖范围与训练规模

官方技术报告显示，Qwen-Scope 训练采样自对应模型预训练数据的 0.5B 词元规模，以确保特征分布广泛、语义稳定。开源权重涵盖 Qwen3-1.7B-Base、Qwen3-8B-Base、Qwen3-30B-A3B-Base、Qwen3.5-2B-Base、Qwen3.5-9B-Base、Qwen3.5-27B 指令模型与 Qwen3.5-35B-A3B-Base 共 7 个底座，SAE 特征数从 32K 到 128K 不等，扩展倍数为 16 倍或 64 倍。

推理结果定向控制

通过控制特征激活，Qwen-Scope 可实现对推理结果的定向修改，涵盖语言、实体、风格等维度，无需显式给出自然语言指令。该能力可用于内容风格统一、跨语言输出控制等场景。

数据分类与长尾合成

在毒性数据分类场景中，基于少量种子数据即可分析毒性样本的 SAE 激活模式，筛选高相关特征用于分类，无需额外训练分类器。在数据合成层面，可识别已有数据中激活次数少甚至未激活的特征，定向补充长尾样本，官方数据显示训练数据能效比可提升至约 15 倍。

训练阶段的定向调优

Qwen-Scope 可定位语言混用、重复生成等低频错误对应的异常激活特征。在监督微调阶段，可针对异常特征设计损失函数降低 badcase 频率；在强化学习阶段，可通过控制特征提高异常采样频率，增加学习奖励密度。

评估冗余度分析

通过对比不同评测集间的特征激活模式，Qwen-Scope 可量化评测集之间的冗余程度。Qwen 团队指出，部分常用评测集在激活特征上存在互相覆盖，导致重复评估，该工具可辅助挑选覆盖度更高、成本更低的测试样本。

Qwen-Scope 权重已上线 Hugging Face 与 ModelScope（魔搭）。可解释性工具与底座模型同步开源的做法，在国内大模型团队中较为少见，后续在第三方研究中的实际应用值得关注。

本文首发于 LLM 大模型邮报。

OpenAI 正式宣布 Codex Pets 宠物体验功能

MISTY — Sat, 02 May 2026 03:28:07 +0000

OpenAI 已在 Codex 应用中正式上线 Codex Pets 功能。根据 OpenAI Codex 官方设置文档，Pets 是一组可选的动画伙伴(optional animated companions for the app)，以悬浮覆盖层(floating overlay)形式存在，既承担陪伴角色，也作为 Codex 任务的实时状态指示器。用户可在 Settings 中前往 Appearance 并选择 Pets，挑选内置宠物或刷新本地自定义宠物，亦可通过 hatch-pet skill 创建专属宠物。

Codex Pets 是什么：Appearance 设置下的可选动画伙伴

根据官方文档，Codex Pets 的官方定义是**“optional animated companions for the app”(应用的可选动画伙伴)——意味着不启用不会影响 Codex 任何核心能力。该功能位于 Settings → Appearance 章节之下，与主题、配色、UI 字体、代码字体等外观配置属同一层级。在 Appearance 中选择 Pets，即可挑选一个内置宠物，或从本地 Codex home 目录刷新自定义宠物**(refresh custom pets from your local Codex home)。这里”local Codex home”的措辞点明了一个关键事实：自定义宠物以本地资产形式存在，而不是云端配置。

核心实用价值：跨应用悬浮的任务状态指示器

Codex Pets 看似装饰性，实则承担了状态指示器的实用角色。官方文档明确说明，Pets 悬浮覆盖层**“keeps active Codex work visible while you use other apps”——即在你切换到其他应用时依然保持 Codex 工作可见。覆盖层会反馈三类信息：当前活动的 thread、Codex 当前状态(running、waiting for input、ready for review 三种之一)，以及一段简短的进度提示**(short progress prompt)。这样开发者无需重新打开 thread 即可一眼看到变化(“glance at what changed without reopening the thread”)，对长任务执行场景极为友好。

三种等价切换方式：适配键盘党与鼠标党

官方为 Codex Pets 提供了三种功能等价的开关方式，以适应不同操作习惯。第一种是命令输入：在 composer(输入框)中直接键入 /pet，适合命令行习惯的开发者；第二种是设置面板按钮：进入 Settings → Appearance，点击 Wake Pet(唤醒)或 Tuck Away Pet(收起)，适合鼠标操作用户；第三种是快捷键命令菜单：按 Cmd+K(macOS)或 Ctrl+K(Windows / Linux)调出命令菜单后运行同名命令，效率最高。三种方式之间没有功能差异，可按场景灵活切换。

hatch-pet skill：创建自定义宠物的完整流程

若内置宠物不能满足需求，可通过 hatch-pet skill 创建自定义宠物，流程分三步。第一步，在 Codex 中运行安装命令：

$skill-installer hatch-pet

第二步，按 Cmd+K 或 Ctrl+K 打开命令菜单，选择 Force Reload Skills 重载 skills，确保 Codex 识别到新装的 hatch-pet。第三步，调用 hatch-pet 创建宠物：

$hatch-pet create a new pet inspired by my recent projects

官方示例提示语**“inspired by my recent projects”**暗示 hatch-pet 能结合用户上下文生成宠物，而非简单从模板中挑选。

本文首发于 LLM 大模型邮报。

Hermes Agent 安装最简流程：Linux、macOS、WSL2 与 Termux 四端一次说清

MISTY — Fri, 01 May 2026 16:44:52 +0000

Hermes Agent 是 Nous Research 推出的开源自学习个人 AI agent，GitHub 收获 118k+ stars，由 Hermes-3 模型团队同源开发。与 Claude Code、Codex、OpenCode 等编码专用工具不同，Hermes Agent 定位为”会成长的个人 agent”——它通过闭环学习循环自动从经验中创建可复用的技能（Skills），跨会话记忆用户偏好，通过 Telegram、Discord、Slack、WhatsApp、Signal 等多个通讯平台接入用户日常生活，并支持自然语言定时任务（cron）。

Hermes Agent 安装的最大特点是仅通过单一 install.sh 脚本分发——没有 npm、Homebrew、winget 包，所有平台共用同一条命令。支持 Linux、macOS、WSL2 与 Android Termux，不支持原生 Windows。本指南整理四端在不同设备上的最简安装流程，覆盖 Docker、SSH、Modal、Daytona 等六种执行后端的配置策略，以及从 OpenClaw 迁移的完整路径。

Hermes Agent 是什么：与编码 agent 的根本差异

理解 Hermes Agent 安装路径的设计选择，需要先搞清楚它的产品定位。Hermes 不是 Claude Code、Codex、OpenCode 那种”在终端里帮你写代码的 agent”，而是更接近”个人 AI 管家”——它的设计目标是持久运行、跨会话学习、跨平台触达：

自学习闭环：完成复杂任务后自动生成 Markdown 格式的 Skill 文档存入技能库，下次遇到类似任务先搜索已有技能而非从零推导。据 TokenMix.ai 的评测，积累 20+ 自创技能后，相似任务完成时间约缩短 40%
跨平台 gateway：通过单一 gateway 进程接入 Telegram、Discord、Slack、WhatsApp、Signal、Email 与 CLI，从手机给云端 VPS 上的 Hermes 发消息也能完成任务
三层持久记忆：FTS5 全文搜索 + LLM 摘要的会话历史检索、Honcho 用户建模、agentskills.io 标准的技能持久化
自然语言 cron：内置定时调度器，支持”每天早 8 点把昨日 GitHub 通知发到 Telegram”这类自然语言任务
六种 terminal backend：本地、Docker、SSH、Daytona、Singularity、Modal——agent 实际执行命令的环境与 Hermes 本体可分离

什么场景适合 Hermes：希望 7×24 运行在 VPS 或 home lab 上的个人 agent、需要从 Telegram 远程指挥的工作流、有跨会话用户记忆需求的研究工作、想要从 OpenClaw 迁移并保留所有技能与 API Key。

什么场景不适合：纯命令行编码、不想维护 Linux/Mac 环境的 Windows 原生用户、不希望 agent 自动生成”持久状态”的临时使用场景。

系统要求与前置检查

根据 Hermes Agent 官方文档：

操作系统：Linux、macOS、WSL2 或 Android（通过 Termux）
不支持原生 Windows：官方明确说明 Hermes 不支持 Windows 原生路径，Windows 用户必须先安装 WSL2
Python：要求 Python 3.11，由安装脚本通过 uv 自动管理，无需手动安装
Node.js：v22，由安装脚本自动安装（用于 WhatsApp bridge 与浏览器自动化）
Git：唯一需要预先安装的依赖
硬件：2 GB RAM 起步，本地跑模型时需更多。运行 Hermes 本体仅 ~1 GB 磁盘
账号：Hermes 本体免费开源（MIT 协议），使用成本取决于模型 provider——可使用 Nous Portal、OpenRouter、NVIDIA NIM、智谱 GLM、Kimi、MiniMax、本地 Ollama 或 OpenAI/Anthropic 等任意 provider
网络：托管模型 API 需稳定网络。本地模型通过 OpenAI 兼容端点可离线运行

检查当前是否已安装：

hermes --version

如果返回版本号（当前最新版 v0.11.0，发布于 2026 年 4 月 23 日），说明已安装。否则按下文方法安装。

安装方法

方法一：官方安装脚本（所有平台推荐）

Hermes Agent 官方仅通过 install.sh 脚本分发——没有 npm 包、没有 Homebrew cask、没有 winget。所有平台共用同一条命令：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

脚本自动处理：

使用 uv 安装 Python 3.11 与虚拟环境
安装 Node.js v22（用于 WhatsApp bridge）
安装 ripgrep、ffmpeg 等系统依赖
从 GitHub clone 仓库到 ~/.hermes/，建立 Python 虚拟环境
把 hermes 命令链接到 ~/.local/bin/hermes

完成后重载 shell：

source ~/.bashrc # 或 source ~/.zshrc

运行 hermes –version 验证，运行 hermes 启动 TUI。

检测平台自动选择 extras：脚本会根据运行环境选择不同的 Python extras。Linux/macOS/WSL2 安装 .[all]（包含全部依赖与语音模式），Termux 安装 .[termux]（移除 Android 不兼容的语音相关库）。

方法二：Linux 与 macOS 部署细节

最常见的部署场景，按顺序执行：

# 安装 git（如未安装）
sudo apt install git # Ubuntu / Debian
sudo dnf install git # Fedora / RHEL
brew install git # macOS
 
# 运行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# 重载 shell
source ~/.bashrc # bash
source ~/.zshrc # zsh
 
# 启动 setup 向导（一次性配置 model provider、tools、gateway）
hermes setup

setup 向导会按顺序问以下问题：

Model provider：从 Nous Portal、OpenRouter、Anthropic、OpenAI、本地 Ollama 等中选择
API Key：对应 provider 的 Key，存入 ~/.hermes/.env
Terminal backend：默认 local，后续可改 Docker / SSH / Modal 等
Gateway 平台：可选，如配 Telegram bot token、Discord 等
Tools 与 skills：选择启用哪些工具与初始技能

完成后执行 hermes 进入 TUI，或 hermes –tui 进入更现代的 TUI（推荐）。

方法三：Windows 用户必须使用 WSL2

Hermes Agent 不支持 Windows 原生路径，根据官方文档说明，Windows 用户必须先安装 WSL2：

# 在 PowerShell 管理员窗口执行
wsl --install -d Ubuntu
 
# 重启电脑后进入 WSL Ubuntu，执行官方安装脚本
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 
# 重载 shell
source ~/.bashrc

WSL2 安装注意事项：

所有依赖（Python、Node.js、git、ripgrep）必须在 WSL2 内安装，不要混用 Windows 原生侧的工具链
项目代码建议存储在 WSL2 文件系统（~/projects），不要放在 /mnt/c/ 下——后者跨文件系统访问性能差
Hermes 默认启动会监听 localhost 端口（如 8642 给 gateway 用），WSL2 与 Windows 主机端口共享，可在 Windows 浏览器直接访问

方法四：Android Termux 移动端部署

Hermes Agent 是少数支持 Android 部署的 AI agent之一，对希望在手机上运行个人 agent 的用户尤其友好：

第一步：安装 Termux

不要从 Google Play 安装 Termux（已停止更新）。从 F-Droid 下载安装最新版本。

第二步：在 Termux 中运行安装脚本

# 更新 Termux 包索引
pkg update && pkg upgrade
 
# 安装基础依赖
pkg install git python
 
# 运行官方安装脚本（脚本会自动检测 Termux 并切换到 Android 流程）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Termux 路径的限制：根据官方 README，Termux 上 Hermes 安装的是 .[termux] extras 而非 .[all]，移除了 Android 不兼容的语音相关依赖（如 faster-whisper 的语音转文本功能）。其他 40+ 工具与跨会话记忆全部可用。

典型 Termux 使用场景：在手机上跑一个轻量 Hermes 实例，配置 Telegram gateway，把手机 24 小时挂在桌面充电——一个零成本的”随身 AI 助手”。结合 Termux 的 SSH 服务器功能，还可以从笔记本通过 SSH 远程操作手机上的 Hermes。

方法五：Docker 部署（生产环境推荐）

Docker 部署的优势是隔离性、可复制部署、配合 docker-compose 实现服务级管理。Hermes 提供官方 Docker 镜像 nousresearch/hermes-agent。

首次运行（交互式 setup）：

# 创建数据目录
mkdir -p ~/.hermes
 
# 交互式运行 setup 向导
docker run -it --rm \
 -v ~/.hermes:/opt/data \
 nousresearch/hermes-agent setup

setup 向导会引导配置 model provider、API Key 等，所有配置写入挂载的 ~/.hermes/.env。

持久化运行 gateway（推荐生产部署方式）：

docker run -d \
 --name hermes \
 --restart unless-stopped \
 -v ~/.hermes:/opt/data \
 -p 8642:8642 \
 nousresearch/hermes-agent gateway run

端口 8642 暴露 gateway 的 OpenAI 兼容 API 与健康检查端点。如果只用 Telegram/Discord 等聊天平台触达，该端口可不映射。

升级 Docker 部署：

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
 --name hermes \
 --restart unless-stopped \
 -v ~/.hermes:/opt/data \
 nousresearch/hermes-agent gateway run

数据目录 ~/.hermes 不受重建容器影响，技能、记忆、会话历史全部保留。

重要：UID 不匹配问题：容器内默认以 UID 10000 的 hermes 用户运行。若主机 ~/.hermes/ 归不同 UID 所有，会出现权限错误。解决方案是设置 HERMES_UID 与 HERMES_GID 环境变量匹配主机用户：

docker run -d \
 --name hermes \
 --restart unless-stopped \
 -v ~/.hermes:/opt/data \
 -e HERMES_UID=$(id -u) \
 -e HERMES_GID=$(id -g) \
 nousresearch/hermes-agent gateway run

方法六：克隆仓库手动安装（开发者）

适合想要修改源码、贡献 PR 或运行 dev 分支的开发者：

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
 
# 使用项目自带的 setup 脚本（自动安装 uv、创建虚拟环境）
./setup-hermes.sh
 
# 或手动等价步骤
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
 
# 运行测试
scripts/run_tests.sh
 
# 启动（项目目录下的 hermes 会自动检测 venv）
./hermes

setup-hermes.sh 与 install.sh 的区别：

install.sh（curl 安装）：面向最终用户，把仓库 clone 到 ~/.hermes/、链接全局 hermes 命令、启动 setup 向导
setup-hermes.sh（仓库内）：面向贡献者，在当前 clone 目录建立开发环境、安装 dev 依赖

认证与 model provider 配置

与 Claude Code、Codex 不同，Hermes 不内置任何模型订阅，安装后必须至少配置一个 provider 才能开始使用。Hermes 支持的 provider 列表非常长：

Nous Portal：Nous Research 自营服务，提供 Hermes-3 等开源模型，据 Decrypt 报道 v0.11.0 起 MiMo v2 Pro 对 Hermes 用户免费
OpenRouter：聚合 200+ 模型，单 Key 访问，国内开发者常用入口
NVIDIA NIM：Nemotron 模型族
Xiaomi MiMo：小米开源 MiMo 模型
z.ai / GLM：智谱 GLM 系列
Kimi / Moonshot：月之暗面 Kimi
MiniMax：MiniMax 模型
Hugging Face：HF Inference API
OpenAI / Anthropic：标准 GPT / Claude API
本地 Ollama：通过 OpenAI 兼容端点访问，零费用
自定义 OpenAI 兼容端点：任意第三方 OpenAI-compatible API

配置方法：

# 交互式选择 provider 与模型
hermes model
 
# 命令行设置默认模型
hermes config set model anthropic/claude-opus-4.6
 
# 设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

切换模型不需重启：在 TUI 内执行 /model 即可热切换，会话历史不丢失。

Terminal Backend 选择：agent 在哪里执行命令

Hermes 一个独特设计是把 agent 本体与 agent 实际执行 shell 命令的环境分离。安装在你笔记本的 Hermes 可以让 agent 在远程 VPS 上执行命令，或在 Modal 云沙箱中运行。共有六种 backend：

local：默认，在 Hermes 所在机器执行命令。适合个人开发与受信任环境
docker：在本机 Docker 容器内执行，提供隔离。需 docker version 验证可用
ssh：通过 SSH 在远程主机执行。需配置 TERMINAL_SSH_HOST 与 TERMINAL_SSH_USER
modal：Modal 云端 serverless 沙箱，idle 时几乎零成本，按需启动。需 MODAL_TOKEN_ID
daytona：Daytona 临时开发环境，类似 GitHub Codespaces。需 DAYTONA_API_KEY
singularity：HPC 集群常用的 Singularity/Apptainer 容器。需 apptainer 或 singularity 在 PATH 中

切换 backend：

# 切到 Docker 隔离
hermes config set terminal.backend docker
 
# 切到远程 SSH
hermes config set terminal.backend ssh
 
# 切回本地
hermes config set terminal.backend local

选哪个 backend：

个人开发与学习：local（默认）即可
对 agent 自主写代码、运行命令存疑：docker，提供隔离防止误操作
已有云端 VPS 想 agent 在那里跑：ssh
追求极致 idle 成本：modal，闲置时几乎零成本

从 OpenClaw 迁移：自动化导入完整流程

Hermes 内置 hermes claw migrate 命令，自动从 ~/.openclaw 迁移配置、记忆、技能与 API Key——这对从 OpenClaw 切换过来的用户是杀手级特性。

首次 setup 自动检测：执行 hermes setup 时，向导会检测 ~/.openclaw 目录存在，自动询问是否迁移。

安装后手动迁移：

# 交互式完整迁移（默认 preset）
hermes claw migrate
 
# 预览将要迁移哪些内容（不实际执行）
hermes claw migrate --dry-run
 
# 仅迁移用户数据，不带 API Key 等敏感信息
hermes claw migrate --preset user-data
 
# 强制覆盖已存在的同名配置
hermes claw migrate --overwrite

迁移涵盖内容：

SOUL.md：persona 定义文件
Memories：MEMORY.md 与 USER.md 条目
Skills：用户自创技能 → ~/.hermes/skills/openclaw-imports/
命令允许列表：approval patterns
Messaging 配置：平台 token、允许用户列表、工作目录
API Key 白名单：Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs 等
TTS 资源：工作区音频文件
AGENTS.md：通过 –workspace-target 指定项目级工作区指令

并行运行策略：迁移过程中可同时保留 OpenClaw 与 Hermes 在不同账号上运行——比如 OpenClaw 接 WeChat、Hermes 接 Telegram，等 Hermes 在 cron 与路由行为上完全匹配后再切换。社区项目 HermesClaw 提供 WeChat bridge，让两者可以在同一个微信账号上并存。

Gateway 配置：让 Hermes 出现在你的聊天软件

Hermes 的核心卖点之一是通过单一 gateway 进程接入多个聊天平台。安装后启用 gateway：

# 交互式 gateway setup 向导
hermes gateway setup
 
# 启动 gateway
hermes gateway start
 
# 安装为系统服务（systemd）以实现 7×24 运行
hermes gateway install

支持的聊天平台：

Telegram：通过 BotFather 创建 bot 获取 token，配置到 gateway
Discord：创建 Discord application bot 并邀请到服务器
Slack：创建 Slack App 并安装到 workspace
WhatsApp：通过 baileys 库（基于 Node.js）连接 WhatsApp Web
Signal：通过 signal-cli 桥接
Email：IMAP/SMTP 接收发送邮件

典型部署模式：在 5 美元/月的 VPS 上跑 gateway，配置 Telegram bot——出门在外通过手机 Telegram 给 bot 发”帮我把昨天的 GitHub 通知整理成日报”，VPS 上的 Hermes 处理后回复结果。这是 Hermes 与传统编码 agent 最大的体验差异。

更新方式

Hermes 提供内置升级命令：

# 升级到最新版本
hermes update

由于 Hermes 通过 git clone 安装而非包管理器分发，升级实际是：

git pull 最新 main 分支代码
uv pip install 更新依赖
迁移配置文件（如有 schema 变更）

Docker 部署的升级：拉取最新镜像后重建容器（前面方法五已说明）。

Termux 上的升级：执行 hermes update，注意 Termux 内升级时间较长，可能需要 5-10 分钟。

常见问题排查

问题 1：安装脚本失败 – Python 3.11 找不到

原因：安装脚本用 uv 自动安装 Python 3.11，但某些受限环境（如学校机房、企业 NAT）可能阻断 uv 的下载。

解决方案：先手动安装 uv，再执行 install.sh：

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.cargo/env
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

或参考方法六手动 clone 仓库的路径，所有依赖都通过本地 uv 处理。

问题 2：hermes 命令安装后找不到

原因：PATH 中未包含 ~/.local/bin。

解决方案：

# 检查 PATH
echo $PATH | tr ':' '\n' | grep local/bin
 
# 加入 PATH（bash）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
 
# zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

问题 3：hermes doctor 报错

解决方案：hermes doctor 是诊断工具，报错通常会指出具体哪个组件出问题——Python 版本、Node 版本、缺失的系统依赖（ripgrep/ffmpeg）、Docker 不可用等。按提示逐一修复，必要时重新执行 install.sh。

问题 4：Termux 上 voice 相关功能失败

原因：Termux 上 Hermes 默认装 .[termux] extras，不包含语音转文本与语音合成依赖（faster-whisper 等库不兼容 Android）。

解决方案：这是预期限制，不要尝试在 Termux 上启用语音模式。其他 40+ 工具与跨会话记忆全部可用。

问题 5：Docker 部署 UID 权限错误

原因：容器内 hermes 用户 UID=10000，与主机 ~/.hermes/ 目录所有者 UID 不匹配。

解决方案：通过环境变量传递主机 UID：

docker run -d \
 --name hermes \
 -v ~/.hermes:/opt/data \
 -e HERMES_UID=$(id -u) \
 -e HERMES_GID=$(id -g) \
 nousresearch/hermes-agent gateway run

问题 6：从 OpenClaw 迁移后某些技能不工作

原因：OpenClaw 与 Hermes 的技能格式略有差异，自动迁移会处理大部分情况但不保证 100% 兼容。

解决方案：

先用 hermes claw migrate –dry-run 预览将迁移的内容
迁移后在 ~/.hermes/skills/openclaw-imports/ 检查导入的 skill 文档
不工作的技能可手动调整或在 Skills Hub 找替代版本

问题 7：gateway 接 Telegram 但收不到消息

解决方案：

检查 BotFather 给的 token 是否正确写入 ~/.hermes/.env
确保 bot 已启动（hermes gateway start）且日志无错误
在 BotFather 设置 bot 的 /setprivacy 为 Disable，否则 bot 在群聊中收不到消息
初次发消息前需先在 Telegram 中搜索 bot 用户名并点击 Start

问题 8：国内网络无法访问 Anthropic / OpenAI / Nous Portal

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port 后重启 hermes
使用 OpenRouter（部分国内可达）或国内 provider（智谱 GLM、Kimi、MiniMax 等）
本地 Ollama + 开源模型，完全离线运行

问题 9：Modal backend 提示认证失败

解决方案：

# 安装 modal SDK
pip install modal
 
# 通过浏览器授权
modal token new
 
# 验证
hermes doctor

成功后 ~/.modal.toml 会写入 token，Hermes 自动读取。

问题 10：自学习闭环没看到效果

原因：Hermes 的 skill 创建是在完成复杂任务后触发，简单的单步对话不会生成新 skill。

解决方案：

给 Hermes 一些有完整流程的复杂任务（如”帮我配置一个 GitHub Actions 工作流并提交 PR”）
检查 ~/.hermes/skills/ 是否有自创 skill 文档生成
在 TUI 内执行 /skills 浏览已有技能库

验证安装与基础使用

# 检查版本
hermes --version
 
# 完整诊断
hermes doctor
 
# 启动 TUI（推荐）
hermes --tui
 
# 经典 CLI 模式
hermes

进入 Hermes 后可使用以下内置命令：

# 切换 model 与 provider
/model [provider:model]
 
# 设置 personality
/personality [name]
 
# 重新开始会话
/new
/reset
 
# 浏览 skills
/skills
 
# 触发特定 skill
/
 
# 压缩对话历史
/compress
 
# 查看 token 用量
/usage
 
# 撤销 / 重做
/undo
/retry

装完之后的关键三步：

用一个具体的小任务验证基础对话能跑通——官方建议先确认普通聊天工作，再加 gateway、cron、skills、voice 等高级功能
配置一个聊天平台 gateway（推荐先 Telegram，最简单），让 Hermes 跨设备触达
给一个完整的工作流任务（如”分析这个项目并生成开发文档”），观察 ~/.hermes/skills/ 是否生成自创 skill——这是 Hermes 与其他 agent 的核心差异

卸载方式

Hermes 安装通过 git clone + venv，没有包管理器分发，卸载需手动清理：

# 删除 hermes 命令链接
rm -f ~/.local/bin/hermes
 
# 删除主目录（包含代码、虚拟环境、配置、数据、技能、记忆）
rm -rf ~/.hermes
 
# Docker 部署的卸载
docker rm -f hermes
docker rmi nousresearch/hermes-agent
rm -rf ~/.hermes
 
# 项目克隆方式安装的卸载
rm -rf /path/to/hermes-agent

注意安全：~/.hermes/.env 包含所有 provider 的 API Key 明文，Telegram bot token 等敏感信息。卸载前如不打算重装，建议先撤销相关 Key。

~/.hermes 目录结构：

~/.hermes/.env：API Key 与配置
~/.hermes/skills/：技能库（含自创技能）
~/.hermes/sessions/：会话历史（FTS5 全文搜索数据库）
~/.hermes/memory/：跨会话持久记忆
~/.hermes/cache/：远程同步缓存（SSH/Modal/Daytona backend 用）

获取方式

GitHub 仓库：NousResearch/hermes-agent

官方文档：Hermes Agent Docs

快速开始：Quickstart Guide

Termux 详细指南：Termux Guide

CLI 命令参考：CLI Reference

环境变量参考：Environment Variables

Skills Hub：agentskills.io

社区 Discord：Nous Research Discord

精选资源列表：awesome-hermes-agent

Hermes Agent 与 Claude Code、Codex、OpenCode 的产品定位完全不同——它不是编码工具，而是面向”个人 AI 管家”场景的自学习 agent，覆盖跨平台触达、跨会话记忆、自然语言定时任务等编码 agent 不涉及的能力。但安装本身只是入口，真正决定 Hermes 价值的是后续SOUL.md persona 设计、技能库的持续积累、gateway 多平台路由配置以及 backend 选择策略。对中文开发者而言，Hermes 与 Claude Code 等编码 agent 是互补关系——Claude Code 解决”如何更好地写代码”，Hermes 解决”如何让 AI 在你的日常生活与工作流中持续提供价值”。

本文首发于 LLM 大模型邮报。

OpenCode 安装最简流程：终端、桌面应用与 IDE 扩展三端一次说清

MISTY — Fri, 01 May 2026 16:30:46 +0000

OpenCode 是当前最受关注的开源 AI 编码 agent 之一，GitHub 收获 153k+ stars、月活开发者 6.5M+，由 Anomaly 团队（前 SST）维护，anomalyco/opencode 仓库采用 MIT 协议开源。OpenCode 安装最大的卖点是 provider 中立——不绑定任何模型厂商，可同时使用 Claude、GPT、Gemini、Grok、本地 Ollama 模型甚至 GitHub Copilot 订阅，对中文开发者尤其友好。

OpenCode 当前提供四个表面：终端 CLI（核心）、桌面应用 Beta、VS Code / Cursor / Zed / Windsurf 扩展、GitHub Actions 集成。本指南整理三端在 macOS、Windows、Linux 上的最简安装命令，并解决 opencode-ai 老仓库（已改名 Crush）与当前 anomalyco 主流版本的消歧义问题。

仓库消歧义：你要装的是 anomalyco/opencode

OpenCode 在 2025 年经历了一次分裂，导致 GitHub 上同时存在两个 “opencode” 仓库，初学者很容易装错版本：

opencode-ai/opencode（旧仓库，已不再维护）：2024 年由 Kujtim Hoxha 主导用 Go 创建的原始版本，2025 年与 Charm 合作后改名为 Crush，已停止以 OpenCode 名义发布新版本
anomalyco/opencode（当前主流版本）：2025 年由 Dax Raad、Adam Doty 等贡献者从原始版本 fork，用 TypeScript + Bun 完全重写，并采用自研 OpenTUI 框架（Zig + SolidJS）。SST 公司 2026 年改名为 Anomaly，仓库随之迁移

判断标准：

访问 opencode.ai 与 github.com/anomalyco/opencode，这是当前活跃维护的主流版本
npm 包名应是 opencode-ai（Anomaly 沿用了原 npm 包名继续发布）
Homebrew tap 应是 anomalyco/tap/opencode

本文所有命令均针对 anomalyco/opencode 当前主流版本。

系统要求与前置检查

OpenCode 由 TypeScript + Bun 构建，发布为自包含原生二进制：

操作系统：macOS、Windows 10/11、Linux 主流发行版（Ubuntu、Debian、Fedora、RHEL、Arch、Alpine 等）
系统架构：x64 或 ARM64
Node.js：仅 npm 安装路径需要 18+；其他路径无依赖
账号：OpenCode 本体免费开源，使用成本取决于你接入的模型 provider——可使用 Anthropic、OpenAI、Google、Groq、OpenRouter 等付费 API，或免费的本地 Ollama 模型，也可用 OpenCode Zen 订阅（10 美元/月，提供官方测试过的模型集）
终端：建议使用现代终端模拟器（iTerm2、Windows Terminal、Alacritty、Kitty、Ghostty 等）以获得最佳 TUI 体验

关于 provider 中立：OpenCode 不直接消耗任何订阅额度。你需要至少一个 LLM 入口才能使用——最低成本路径是 本地 Ollama + 开源模型（零费用），最高质量路径是 Claude Sonnet/Opus 或 GPT 系列 API。

检查当前是否已安装：

opencode --version

如果返回版本号（如 v1.1.x），说明已安装。否则按下文方法安装。

安装方法

方法一：官方安装脚本（跨平台推荐）

最简单的安装路径，零依赖、自动检测平台架构、自动配置 PATH：

macOS、Linux、WSL：

curl -fsSL https://opencode.ai/install | bash

Windows PowerShell：脚本同样兼容 Windows 子系统，建议在 WSL2 内执行。原生 PowerShell 用户改用方法三的 Scoop 或 Chocolatey 路径。

可通过环境变量自定义安装目录：

# 安装到自定义目录
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
 
# 使用 XDG 标准目录
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

完成后运行 opencode –version 验证。

方法二：Homebrew（macOS / Linux）

OpenCode 提供两个 Homebrew 入口，选择哪个对更新及时性有显著影响：

# 推荐：Anomaly 自维护 tap，更新最及时
brew install anomalyco/tap/opencode
 
# 备选：Homebrew 官方 formula，更新较慢
brew install opencode

差异说明：anomalyco/tap 由 OpenCode 团队自己维护，新版本发布后即时同步；而 Homebrew 官方 formula 走社区审核流程，存在 1-2 个版本的滞后。对于活跃迭代的工具优先选 anomalyco/tap。

升级用：

brew upgrade opencode

**桌面应用（Beta）**同样通过 Homebrew cask 安装：

brew install --cask opencode-desktop

方法三：Windows 包管理器（Scoop / Chocolatey / WinGet）

Windows 用户原生路径有三种包管理器选择，无需 WSL 即可获得完整功能。

Scoop（推荐）：

# OpenCode CLI
scoop install opencode
 
# OpenCode 桌面应用
scoop bucket add extras
scoop install extras/opencode-desktop

Chocolatey：

choco install opencode

WinGet：

winget install --id SST.opencode -e

关于 winget 包名为 SST.opencode 的历史：包 ID 仍以 SST 命名空间发布，是因为该包在 SST 公司更名为 Anomaly 之前就已提交到 winget 仓库——一旦确定的 winget 包 ID 通常不会变更，避免破坏现有用户的更新链路。但包内部的安装源（InstallerUrl）已经指向 github.com/anomalyco/opencode/releases/，所以装的就是当前主流版本。

WinGet 路径已知问题：根据 OpenCode GitHub Issue 5121，winget 包审核流程比 GitHub Releases 慢 1-2 个版本，且 winget 路径未在 OpenCode 官方文档中显式列出。对追新版本的用户，建议使用方法一的官方安装脚本或 Scoop；对企业受控环境强制使用 winget 的用户，该路径仍可用，仅需接受版本滞后。

升级：

# Scoop
scoop update opencode
 
# Chocolatey
choco upgrade opencode
 
# WinGet
winget upgrade --id SST.opencode

方法四：npm 安装（跨平台）

适合 CI/CD 中需要固定版本、团队工作流以 npm 为标准的场景：

# npm
npm install -g opencode-ai@latest
 
# 或 bun（OpenCode 自身使用 Bun 构建，bun 路径性能略好）
bun add -g opencode-ai
 
# pnpm / yarn
pnpm add -g opencode-ai
yarn global add opencode-ai

注意 npm 包名：是 opencode-ai，不是 opencode。npm 上无关同名包同样存在，安装前确认完整命令。

要求 Node.js 18+。禁止使用 sudo npm install -g，遇到 EACCES 错误改用用户级 npm prefix 或 nvm。

方法五：Linux 包管理器（Arch / Nix）

Arch Linux 用户：

# 稳定通道（pacman）
sudo pacman -S opencode
 
# AUR 最新版本（paru / yay）
paru -S opencode-bin
yay -S opencode-bin

Nix 用户：

# 从 nixpkgs 运行
nix run nixpkgs#opencode
 
# 使用 dev 分支最新版本
nix run github:anomalyco/opencode

Mise / asdf 用户：

mise use -g opencode

方法六：桌面应用（Beta）

OpenCode 桌面应用目前处于 Beta 阶段，提供图形化的项目管理界面：

macOS Homebrew：

brew install --cask opencode-desktop

Windows Scoop：

scoop bucket add extras
scoop install extras/opencode-desktop

直接下载：访问 opencode.ai/download 下载对应平台安装包：

macOS Apple Silicon / Intel
Windows x64
Linux .deb / .rpm

桌面应用与 CLI 共享同一个数据目录与认证，在任一表面登录后另一表面无需再次认证。

方法七：IDE 扩展（VS Code / Cursor / Zed / Windsurf）

OpenCode 提供官方 IDE 扩展，把 agent 集成到编辑器内：

VS Code：扩展市场搜索 “OpenCode”
Cursor：扩展市场搜索 “OpenCode”（Cursor 是 VS Code fork，扩展兼容）
Zed：从 Zed Extensions 安装
Windsurf：扩展市场搜索 “OpenCode”
VSCodium：从 OpenVSX 安装

或访问 opencode.ai/download 跳转到各 IDE 的对应安装链接。

认证与模型配置：你必须连一个 provider 才能用

与 Claude Code、Codex 不同，OpenCode 不内置任何模型订阅——这是它最大的灵活性，也是初次配置的主要门槛。安装后必须至少连接一个 provider 才能开始使用。

OpenCode 使用 Models.dev 维护的 provider 列表，启动后执行：

opencode auth login

会列出所有支持的 provider，选择后输入对应 API Key 即可。常见 provider 配置：

Anthropic（Claude）：在 console.anthropic.com 创建 API Key
OpenAI（GPT）：在 platform.openai.com 创建 API Key
OpenRouter：聚合多家 provider，单 Key 访问 100+ 模型，国内开发者常用
本地 Ollama：执行 opencode auth login 选 Ollama，无需 Key，仅需本地 Ollama 服务运行
GitHub Copilot：复用已有 Copilot 订阅，登录 GitHub 账号即可
OpenCode Zen：OpenCode 团队自营订阅服务，10 美元/月提供官方测试过的精选模型集

凭证存储在 ~/.local/share/opencode/auth.json（Linux/macOS）或 %LOCALAPPDATA%\opencode\auth.json（Windows），需视为密码保护。

切换默认模型：在 OpenCode TUI 内执行 /connect 选择 provider 与模型，或编辑 opencode.json 配置文件。

模型选择建议：从零开始如何配第一个 provider

对完全新手而言，OpenCode 的 provider 中立性反而是部署门槛。三种典型场景的最小配置：

场景 1：完全免费体验：先装 Ollama → ollama pull qwen2.5-coder:7b → 在 OpenCode 中选 Ollama provider。零费用但模型能力受本地硬件限制。

场景 2：质量优先：使用 Anthropic Claude Sonnet/Opus API，按 token 计费但当前是公认编码能力最强的模型。月度预算 20-50 美元可覆盖日常使用。

场景 3：性价比优先：使用 OpenRouter 单 Key 访问 GLM、DeepSeek、Kimi 等中国开源模型，单价显著低于 Claude/GPT。中文项目编码场景对中文开源模型友好度较高。

不推荐做法：在第一次安装时跳过 provider 配置直接进 TUI——OpenCode 会显示 /connect 提示但无法处理任何请求，体验上像是工具坏了。

更新方式：每个安装路径不同

不同安装路径对应不同更新机制：

官方安装脚本：重新执行 curl -fsSL https://opencode.ai/install | bash，或使用内置 opencode upgrade 命令
Homebrew：brew upgrade opencode
npm：npm install -g opencode-ai@latest
Scoop：scoop update opencode
Chocolatey：choco upgrade opencode
WinGet：winget upgrade –id SST.opencode
pacman：sudo pacman -Syu opencode
桌面应用：通过包管理器更新或在应用内检查更新

OpenCode 内置升级命令支持指定版本：

# 升级到最新版本
opencode upgrade
 
# 升级到特定版本
opencode upgrade --version 1.1.20

常见问题排查

问题 1：装错了仓库（opencode-ai 而非 anomalyco）

原因：在 GitHub 搜索 opencode 时排在前面的可能是已停止维护的旧仓库。

解决方案：确认 npm 包名 opencode-ai、Homebrew tap anomalyco/tap、官方网站 opencode.ai、当前主仓库 github.com/anomalyco/opencode。如果已装错版本：

# 卸载旧的 opencode-ai/opencode（如有）
which opencode # 确认当前 opencode 路径
rm -f $(which opencode)
 
# 重新装当前主流版本
curl -fsSL https://opencode.ai/install | bash

问题 2：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 18+。

解决方案：执行 node –version 检查。低于 18 时通过 nvm install –lts 升级，或改用方法一的官方安装脚本（不需要 Node.js）。

问题 3：opencode –version 提示 command not found

解决方案：

关闭终端开新窗口
macOS/Linux 执行 source ~/.zshrc 或 source ~/.bashrc
检查官方安装脚本默认目录是否在 PATH 中（通常是 ~/.opencode/bin 或 ~/.local/bin）

问题 4：TUI 显示乱码或字符错位

原因：OpenCode 使用自研 OpenTUI 框架（Zig + SolidJS），对终端模拟器的现代特性有依赖。某些老终端（默认 cmd.exe、低版本 Terminal.app）渲染异常。

解决方案：

切换到现代终端：iTerm2、Windows Terminal、Alacritty、Kitty、Ghostty
确认终端 Locale 设为 UTF-8：echo $LANG 应输出 en_US.UTF-8 或 zh_CN.UTF-8
确认终端字体支持 Powerline / Nerd Font 图标

原因：OpenCode 从 Models.dev 拉取 provider 列表，如果该数据未更新或网络不通会缺失部分选项。

解决方案：

升级 OpenCode 到最新版本
检查能否访问 models.dev
对于尚未在 Models.dev 列出的 provider，可在 opencode.json 中手动配置 OpenAI 兼容端点

问题 6：本地 Ollama 模型连不上

原因：OpenCode 默认期望 Ollama 监听 127.0.0.1:11434，自定义部署或远程 Ollama 需显式配置。

解决方案：在 shell 中设置：

export LOCAL_ENDPOINT=http://your-ollama-host:11434

或在 opencode.json 中配置自托管 provider。

问题 7：国内网络无法访问 Anthropic / OpenAI API

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port
使用 OpenRouter 等聚合服务（部分国内可达）
使用国内可达的中国开源模型 API（智谱 GLM、深度求索 DeepSeek、月之暗面 Kimi 等），通过 opencode.json 配置 OpenAI 兼容端点

问题 8：plan 模式与 build 模式如何切换

解决方案：在 TUI 内按 Tab 键即可切换。Build 是默认全权限 agent，Plan 是只读分析模式适合先做方案再改代码。OpenCode 支持自定义 agent，配置文件位于 ~/.opencode/agents/ 或项目级 .opencode/agents/。

问题 9：Copilot 订阅认证失败

原因：OpenCode 通过读取系统中已有的 GitHub Copilot 凭证文件实现 Copilot 复用，需要先在 VS Code 或其他 Copilot 客户端登录。

解决方案：

在 VS Code Copilot 扩展或 GitHub CLI（gh auth login）中先登录
OpenCode 会自动从标准位置读取 token
仍失败时手动设置 GITHUB_TOKEN 环境变量，或在 opencode.json 的 providers.copilot.apiKey 中配置

验证安装与基础使用

安装完成后，建议执行以下命令验证：

# 检查版本
opencode --version
 
# 配置第一个 provider
opencode auth login
 
# 在项目目录启动 TUI
cd /path/to/your/project
opencode

进入 OpenCode 后可使用以下内置命令：

# 切换 provider 与模型
/connect
 
# 分析仓库结构并生成 AGENTS.md
/init
 
# 显示帮助与快捷键
/help
 
# 撤销 / 重做最近一次变更
/undo
/redo
 
# 分享当前会话（可选功能）
/share

关键快捷键：

Tab：在 Build 与 Plan 模式之间切换
@：模糊搜索项目文件，把文件加入上下文
拖拽图片到终端：把图片加入上下文，OpenCode 支持视觉模型
Ctrl+X：默认 leader key（避免与终端快捷键冲突），后接 Leader+key 触发各种命令

装完之后的关键三步：

在项目根目录运行 /init，让 OpenCode 分析代码库并生成 AGENTS.md 作为持久上下文。该文件兼容 Claude Code 的 CLAUDE.md 与 Codex 的 AGENTS.md 约定
使用 Plan 模式（按 Tab 切换）让 OpenCode 先生成实施方案，确认后切回 Build 模式执行——这种”先规划后执行”的工作流是 OpenCode 相比其他工具的差异化设计
通过 opencode mcp add 接入 MCP 服务器，把 OpenCode 扩展为可调用 GitHub、数据库、内部 API 的完整 agent

非交互模式与 API 服务器

OpenCode 除 TUI 外还支持脚本调用与 HTTP 服务器模式，适合自动化集成：

# 单次提示 + 输出（适合 CI/CD）
opencode -p "Explain the use of context in Go"
 
# JSON 格式输出
opencode -p "List all TODO comments in this project" -f json
 
# 静默模式（脚本调用，禁用 spinner）
opencode -p "..." -q
 
# 启动 HTTP 服务器（多客户端并行连接）
opencode serve

opencode serve 启动后会暴露带 OpenAPI 文档（/doc）的 HTTP 端点，配合官方 @opencode-ai/sdk JS/TS SDK 可在自有应用内嵌入 OpenCode 能力。这是 OpenCode 的客户端/服务器架构带来的独特能力——TUI 只是众多前端之一。

卸载方式：不同安装路径对应不同清理步骤

OpenCode 提供内置卸载命令一键清理所有相关文件：

opencode uninstall

也可按安装方式分别处理：

官方安装脚本：删除二进制（通常在 ~/.opencode/bin/opencode）
Homebrew：brew uninstall opencode 与 brew uninstall –cask opencode-desktop
npm：npm uninstall -g opencode-ai
Scoop：scoop uninstall opencode
Chocolatey：choco uninstall opencode
WinGet：winget uninstall –id SST.opencode
pacman：sudo pacman -R opencode

仅删除二进制并不能完全清理。配置目录与会话历史保留在以下位置：

# Linux / macOS
~/.local/share/opencode/ # 会话历史与认证
~/.config/opencode/ # 配置文件
~/.opencode/ # 用户级 agents 与命令
 
# Windows
%LOCALAPPDATA%\opencode\
%APPDATA%\opencode\

彻底清理执行：

# Linux / macOS
rm -rf ~/.local/share/opencode ~/.config/opencode ~/.opencode
 
# Windows PowerShell
Remove-Item -Path "$env:LOCALAPPDATA\opencode" -Recurse -Force
Remove-Item -Path "$env:APPDATA\opencode" -Recurse -Force

安全提示：auth.json 存储 API Key 明文。卸载前如不打算重装，建议先 opencode auth logout 显式撤销凭证。项目级配置 .opencode/ 与 opencode.json 需在每个项目目录下单独删除。

获取方式

官方网站：opencode.ai

下载页（覆盖所有表面）：opencode.ai/download

官方文档：OpenCode Docs

CLI 命令参考：CLI Reference

GitHub 主仓库：anomalyco/opencode

支持的模型与 provider：Models.dev

JS/TS SDK：@opencode-ai/sdk

OpenCode 通过 provider 中立、客户端/服务器架构与开源协议，提供了与 Claude Code、Codex 完全不同的产品定位——它不绑定任何模型厂商，把选择权完全交给开发者。但安装本身只是入口，真正决定生产力的是后续 provider 选型、AGENTS.md 上下文设计、自定义 agent 体系搭建以及 MCP 服务器集成。对中文开发者而言，OpenCode 与 Claude Code、Codex 并存往往比单一选择更实用——OpenCode 可对接国内开源模型 API 与本地 Ollama，覆盖 Claude/Codex 难以触达的场景。

本文首发于 LLM 大模型邮报。

Codex 安装最简流程：桌面应用、CLI 与 IDE 扩展三条路径一次说清

MISTY — Fri, 01 May 2026 14:24:32 +0000

OpenAI Codex 已经从最初的单一命令行工具演变为完整产品矩阵，覆盖桌面应用（Codex app）、命令行（Codex CLI）、IDE 扩展、云端 Web 与 GitHub 集成五个表面。所有 Codex 表面共享同一个 ChatGPT 账号认证体系，包含在 ChatGPT Plus、Pro、Business、Edu、Enterprise 订阅中无需额外付费。Codex 安装路径取决于你想在哪种环境下使用——终端、桌面、IDE 还是云端，本指南整理三大本地安装路径在 macOS、Windows、Linux 上的最简命令。

根据 OpenAI 官方公告，Codex 桌面应用于 2026 年 2 月在 macOS 首发，3 月 4 日上线 Windows，限时活动期间向 ChatGPT Free 与 Go 用户开放。本文按”产品矩阵—系统要求—安装方法—问题排查—验证使用—获取方式”六段，详细说明 Codex 在不同设备上的部署流程。

Codex 产品矩阵：先搞清装哪个

很多教程把”安装 Codex”等同于”安装 Codex CLI”，但实际上当前 Codex 包含五个独立但互通的表面：

Codex 桌面应用（Codex app）：macOS 与 Windows 原生应用，定位为 “command center for agents”，支持并行 agent 线程、worktree、in-app 浏览器、computer use（macOS）等
Codex CLI：开源命令行 agent，基于 Rust 构建，运行在本地终端，openai/codex GitHub 仓库已收获 75k+ stars
Codex IDE 扩展：VS Code、Cursor、Windsurf 等编辑器内的 Codex agent
Codex Cloud / Codex Web：云端异步任务模式，访问 chatgpt.com/codex 提交任务
Codex GitHub 集成：在 PR 评论中通过 @codex 触发云端任务

选哪个：

偏好图形界面、需要并行管理多个 agent、做前端 / 游戏开发需要 in-app 浏览器 → 桌面应用
终端工作流、CI/CD、SSH 远程开发、headless 环境 → CLI
已有 IDE 习惯、希望 agent 直接读取打开的文件 → IDE 扩展
长任务后台运行、不想占用本地资源 → Cloud / Web

三个本地表面共享配置：桌面应用、CLI、IDE 扩展共用 ~/.codex/config.toml（Windows 为 %USERPROFILE%.codex\config.toml），认证、MCP 服务器配置、自定义模型 provider 等设置在三者间自动同步。这意味着在一个表面登录后，其他两个表面无需再次认证。

系统要求与前置检查

根据 Codex 官方安装文档：

桌面应用：macOS（Apple Silicon 优先，Intel 也有对应构建）；Windows 10/11，通过 Microsoft Store 分发
Codex CLI：macOS、Windows 10/11、Linux 主流发行版（Ubuntu、Debian、Fedora、RHEL、Alpine 等）
系统架构：x64 或 ARM64
Node.js：仅 npm 安装路径需要 22+；Homebrew 与 GitHub Release 路径无依赖
账号：ChatGPT Plus（20 美元/月）、Pro（200 美元/月）、Business、Edu、Enterprise 之一，或一个有可用额度的 OpenAI API Key
限时活动：据 OpenAI 2026 年 2 月公告，Codex 桌面应用限时向 ChatGPT Free 与 Go 用户开放，截止时间以官方为准
网络：稳定连接到 OpenAI 服务端点，国内用户需配置代理

检查当前 Codex CLI 是否已安装：

codex --version

如果返回版本号（如 codex-cli 0.121），说明已安装。否则按下文方法安装。

安装方法

方法一：Codex 桌面应用（macOS / Windows 推荐）

适合大多数开发者的最简路径，提供并行 agent 线程、in-app 浏览器、worktree 管理、skills 与 plugins 等图形化能力。

macOS 安装：

访问 chatgpt.com/codex 下载 .dmg 文件（Apple Silicon 与 Intel 各有对应构建），双击挂载后将 Codex.app 拖入 Applications 目录。

或通过 Homebrew cask 安装：

brew install --cask codex

Windows 安装：

通过 Microsoft Store 安装是最简单的路径，Codex 在 Microsoft Store 的应用页支持一键安装，并通过 Store 自动更新。

或使用 winget：

winget install --id 9PLM9XGG6VKS --source msstore

从 CLI 启动桌面应用：如果已经安装了 Codex CLI，执行 codex app 会自动下载并安装桌面应用，省去手动下载步骤。

桌面应用首次启动时会引导完成 ChatGPT 账号 OAuth 登录，认证完成后即可创建项目。

方法二：Codex CLI 通过 npm 安装（跨平台）

最广泛的 CLI 安装方式，命令统一：

npm install -g @openai/codex

包名陷阱必须注意：完整包名是 @openai/codex（含 @openai 命名空间），不是 codex。npm 上存在另一个完全无关的 codex 包（2012 年发布、与 OpenAI 无关），OpenAI 官方 README 明确标注误装该包是常见错误来源。安装前确认命令包含 @openai/ 前缀。

要求 Node.js 22 或更高版本。npm 路径下的 codex 命令是个 JavaScript shim，运行时检测平台架构，加载对应的 optional dependency（如 @openai/codex-darwin-arm64），spawn 实际的原生 Rust 二进制执行。本身不参与运行时计算。

禁止使用 sudo npm install -g。遇到 EACCES 权限错误时配置用户级 npm prefix：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex

升级 Codex CLI：

npm install -g @openai/codex@latest

方法三：Codex CLI 通过 Homebrew（macOS 推荐）

不需要 Node.js，直接安装 Rust 原生二进制：

brew install --cask codex

注意是 cask 而非 formula。brew install codex（不带 –cask）会失败或装到错误的包。Homebrew cask 同时安装 Codex CLI 与桌面应用——这是 2026 年初 Homebrew 包结构调整后的统一入口。

升级用：

brew upgrade --cask codex

如果之前用旧的 formula 路径安装过，需先卸载再装 cask：

brew uninstall codex
brew install --cask codex

方法四：Codex CLI 通过 GitHub Release 直接下载（零依赖）

适合不想引入 Node.js 或 Homebrew 的最小化部署场景，包括服务器、CI 环境、Docker 镜像等。访问 openai/codex GitHub Releases 页面下载对应平台归档：

macOS Apple Silicon：codex-aarch64-apple-darwin.tar.gz
macOS Intel：codex-x86_64-apple-darwin.tar.gz
Linux x86_64：codex-x86_64-unknown-linux-musl.tar.gz（musl 静态链接，最大兼容性）
Linux ARM64：codex-aarch64-unknown-linux-musl.tar.gz

每个归档解压后包含一个二进制文件，名字带平台标识，需重命名为 codex 并放到 PATH 中：

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex
chmod +x ~/.local/bin/codex

Linux 二进制使用 musl 静态链接而非 glibc，同一个二进制可在 Alpine、Ubuntu、Debian、CentOS 等不同发行版直接运行。

方法五：Codex IDE 扩展（VS Code / Cursor / Windsurf）

Codex IDE 扩展把 agent 直接集成到编辑器内，支持读取打开的文件与选中代码作为上下文。

VS Code 安装：

打开 VS Code 扩展面板（Cmd+Shift+X on Mac，Ctrl+Shift+X on Windows/Linux），搜索 “Codex” 选择官方 OpenAI Codex 扩展安装。

Cursor / Windsurf 安装：

在各自的扩展市场搜索 “Codex” 安装。Cursor 与 Windsurf 是 VS Code 的 fork，扩展生态兼容。

IDE 扩展与 CLI、桌面应用共用 ~/.codex/config.toml，认证状态自动同步——在任一表面登录后，IDE 扩展无需再次认证。

方法六：Windows 上的 WSL2 路径

如果项目托管在 WSL2 内、或需要 Linux 原生工具链，可在 WSL 内安装 Codex CLI：

# 在 PowerShell 管理员窗口安装 WSL（如未安装）
wsl --install -d Ubuntu
 
# 进入 WSL 后安装 Node.js 22 与 Codex CLI
nvm install 22
npm install -g @openai/codex

WSL1 已停止支持。Codex 0.115 起 Linux 沙盒迁移到 bubblewrap，仅 WSL2 可用。

Windows 原生与 WSL 配置同步：Windows 原生 Codex 使用 %USERPROFILE%.codex，WSL 内 Codex 默认使用 Linux ~/.codex。共享认证与会话历史在 WSL 中设置：

export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex
echo 'export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex' >> ~/.bashrc

认证方式：ChatGPT 订阅与 API Key 的差异

Codex 所有本地表面（桌面应用、CLI、IDE 扩展）共享同一套认证体系，提供两种登录方式：

ChatGPT OAuth（推荐个人开发者）：自动打开浏览器，在 localhost:1455 启动 OAuth 回调服务器，登录 ChatGPT 账号后令牌存储到 ~/.codex/auth.json 或操作系统密钥库。直接绑定 ChatGPT 订阅额度，无需手动管理 Key。远程 SSH 或浏览器回调被阻断时使用设备码流程：

codex login --device-code

API Key（推荐 CI/CD 与自动化）：

export OPENAI_API_KEY=sk-...
codex

或通过 stdin 传入：

printenv OPENAI_API_KEY | codex login --with-api-key

关键差异：fast mode 等依赖 ChatGPT credits 的功能仅 OAuth 登录可用，API Key 路径走标准 API 计费。这意味着相同任务两种认证方式费用结构不同——OAuth 走订阅额度（消耗 ChatGPT 计划内的本地消息配额），API Key 按 token 计费。Codex 官方认证文档建议个人开发者使用 OAuth、CI/CD 流水线使用 API Key。

凭证存储位置可通过 ~/.codex/config.toml 中的 cli_auth_credentials_store 配置：

file：存储在 ~/.codex/auth.json（明文，需视为密码保护）
keyring：存储在操作系统密钥库（macOS Keychain、Windows Credential Manager、Linux Secret Service）
auto：优先使用密钥库，不可用时回落到 file

模型选择：GPT-5.5、GPT-5.4 与 GPT-5-Codex

Codex 当前可用的模型：

GPT-5.5：最新通用模型，复杂规划与多步推理首选
GPT-5.4：稳定可用的前一代，支持 1M 上下文窗口（实验性）与 native computer use
GPT-5.4 mini：轻量模型，适合代码库探索、大文件审查、subagent 工作
GPT-5-Codex：基于 GPT-5 进一步针对 agentic coding 优化的版本，OpenAI 建议仅在 Codex 或类 Codex 环境中使用

在 CLI 中切换模型：

# 启动新会话时指定
codex --model gpt-5.5
 
# 会话内切换
/model

或在 ~/.codex/config.toml 中持久化默认模型：

model = "gpt-5.5"

注意：如果账号尚未开放 GPT-5.5 访问，回退到 gpt-5.4 即可。模型可见性按账号逐步开放，更新 CLI、IDE 扩展或桌面应用到最新版本可能解锁新模型选项。

常见问题排查

问题 1：误装了无关的 codex 包

原因：执行 npm install -g codex 装到的是 2012 年发布的同名无关包。

解决方案：

npm uninstall -g codex
npm install -g @openai/codex

问题 2：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 22+。

解决方案：执行 node –version 检查。低于 22 时通过 nvm install 22 升级，或改用 Homebrew / GitHub Release 路径。

问题 3：codex –version 提示 command not found

解决方案：关闭终端开新窗口；macOS/Linux 执行 source ~/.zshrc 或 ~/.bashrc；Windows 关闭并重开 PowerShell。仍找不到检查 npm config get prefix 输出对应 bin 目录是否在 PATH 中。

问题 4：npm 安装报 EACCES 权限错误

解决方案：不要使用 sudo。按方法二末尾配置用户级 npm prefix，或改用 Homebrew 路径。

问题 5：macOS 提示 “无法打开 codex，因为开发者无法验证”

解决方案：

系统设置 → 隐私与安全性 → 找到被阻断的 codex 条目，点击”仍要打开”
或在 Terminal 中：xattr -d com.apple.quarantine $(which codex)

问题 6：Codex 桌面应用 macOS 仅支持 Apple Silicon？

原因：早期版本仅 Apple Silicon 构建。

解决方案：当前 Codex 桌面应用同时提供 Apple Silicon 与 Intel 构建。在 Codex 桌面应用下载页选择 Intel 构建即可。

问题 7：OAuth 浏览器回调失败

原因：远程 SSH、devcontainer、严格防火墙环境下 localhost:1455 回调被阻断。

解决方案：使用设备码流程 codex login –device-code，或直接设置 OPENAI_API_KEY 环境变量。

问题 8：Windows 原生沙盒初始化失败

解决方案：在 ~/.codex/config.toml 切换到 unelevated 沙盒模式：

[windows]
sandbox = "unelevated"

问题 9：API Key 已设置但 Codex 仍要求登录

解决方案：检查当前 shell：echo $OPENAI_API_KEY；添加到 shell profile 持久化；首次运行按 onboarding 流程批准该 Key。

问题 10：国内网络无法完成 OAuth 或 API 调用

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port
或在 ~/.codex/config.toml 配置 custom model provider 指向第三方兼容端点（注意非官方端点不消耗 ChatGPT 订阅额度，按第三方 provider 计费）

验证安装与基础使用

CLI 验证：

# 检查版本
codex --version
 
# 验证认证状态
codex login status
 
# 查看 MCP 服务器配置
codex mcp list
 
# 启动交互式 TUI
codex

桌面应用验证：启动后看到主界面 + 可创建新项目即说明安装成功。

进入 Codex CLI 后可使用以下内置命令：

# 切换模型
/model
 
# 会话状态与 token 用量
/status
 
# 查看当前生效配置
/config
 
# 压缩对话历史
/compact

装完之后的关键三步：

在项目目录运行 codex（CLI）或在桌面应用中创建项目，让 Codex 探索代码库结构。Codex 会自动读取项目根目录的 AGENTS.md 作为持久上下文，类似 Claude Code 的 CLAUDE.md 机制
设置 approval mode 适配工作风格——–sandbox workspace-write 适合无人值守的局部任务，–ask-for-approval never 让 Codex 自主完成
通过 codex mcp add 接入 MCP 服务器，把 Codex 扩展为可调用 GitHub、数据库、内部 API 的完整 agent

卸载方式：不同安装路径对应不同清理步骤

npm：npm uninstall -g @openai/codex
Homebrew cask：brew uninstall –cask codex
GitHub Release 手动安装：删除二进制所在路径（如 ~/.local/bin/codex）
桌面应用（macOS）：从 Applications 拖到废纸篓
桌面应用（Windows）：通过 Microsoft Store 卸载，或 winget uninstall 对应包

仅删除二进制并不能完全清理。配置目录 ~/.codex/（Windows 为 %USERPROFILE%.codex）包含认证令牌、MCP 服务器配置、会话历史与执行规则，会被保留以便重装。彻底清理：

# macOS / Linux / WSL
rm -rf ~/.codex
 
# 或仅清除认证（保留其他配置）
codex logout

注意安全：~/.codex/auth.json 存储 OAuth 令牌或 API Key 明文。卸载前如不打算重装，建议先 codex logout 显式撤销凭证。

OpenAI Codex 已经从单一 CLI 演化为覆盖终端、桌面、IDE、云端、GitHub 的完整 agent 矩阵，包含在 ChatGPT 订阅中的策略大幅降低了使用成本。但安装本身只是入口——真正决定生产力的是后续 AGENTS.md 上下文设计、approval mode 调优、skills 与 plugins 体系搭建以及 MCP 服务器集成。Codex 与 Claude Code 在 agent 工作流上互有取舍——Codex 矩阵更广（覆盖到桌面与 GitHub），Claude Code 更聚焦于命令行——对中文开发者而言两者并存往往比二选一更实用。

本文首发于 LLM 大模型邮报。

Claude Code 安装最简流程：三端命令、自动更新与彻底卸载一次说清

MISTY — Fri, 01 May 2026 21:21:00 +0800

传统的 AI 编码工具往往需要手动配置 Node.js 环境、解决 npm 权限错误、维护 PATH 变量，整个流程对初学者并不友好。Claude Code 作为 Anthropic 推出的命令行 AI 编码助手，2025 年 10 月起官方将原生安装器（native installer）确立为推荐安装方式，零依赖、自动配置 PATH、后台自动更新，把 Claude Code 安装流程压缩到一行命令。

Claude Code 支持 macOS 13.0+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+，覆盖 x64 与 ARM64 主流架构。本指南按”使用价值—系统要求—安装方法—问题排查—验证使用—获取方式”六段，详细说明在不同设备上完成 Claude Code 安装的最简流程，覆盖标准账号、企业部署、第三方推理服务等多种场景。

为什么要使用原生安装器

原生安装器作为 Anthropic 当前的官方推荐方式，相比 npm 等传统路径有几项实际价值：

零依赖部署：不需要 Node.js 运行时，不需要 npm 全局权限配置。一行 curl 或 irm 命令完成下载、PATH 配置与首次启动准备，整个过程通常在 30 秒内结束。

后台自动更新：原生安装是唯一获得 Claude Code 内置更新机制的安装方式。启动时与运行中后台检查新版本，下次启动生效，无需手动维护。Anthropic 官方文档明确指出 Homebrew、WinGet、apt、dnf、apk 与 npm 安装均不参与该机制，这是选择安装路径时最容易被忽略却最关键的差异。

跨平台一致：macOS、Linux、WSL 共用同一条 install.sh 脚本，Windows PowerShell 与 CMD 各有对应版本但安装结果一致，二进制本身在所有平台行为相同。

发布通道可控：通过 autoUpdatesChannel 设置在 latest（即时收到新版本）与 stable（约滞后一周、跳过有重大回退的版本）之间切换。企业部署可追加 minimumVersion 字段防止版本回滚。

统一卸载路径：所有原生安装的二进制都位于 ~/.local/bin/claude（Windows 为 %USERPROFILE%.local\bin\claude.exe），卸载只需删除两个目录，无包管理器残留。

系统要求与前置检查

根据 Claude Code 官方安装文档，运行 Claude Code 需满足以下条件：

操作系统：macOS 13.0+、Windows 10 1809+ 或 Windows Server 2019+、Ubuntu 20.04+、Debian 10+、Alpine Linux 3.19+
系统架构：x64 或 ARM64
硬件：4 GB 以上内存
Shell：Bash、Zsh、PowerShell 或 CMD（原生 Windows 推荐安装 Git for Windows 以便调用 Bash 工具）
账号：Claude Pro、Max、Team、Enterprise 或 Anthropic Console（API 计费）账号之一，免费版 Claude.ai 不包含 Claude Code 访问权限
网络：稳定连接到 Anthropic 服务端点，国内用户可能需要配置代理

也可通过 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 接入第三方推理服务，适合企业自有云资源或合规要求场景。

检查是否已安装 Claude Code 的方法：打开终端执行：

claude --version

如果返回版本号（如 2.1.xxx），说明已安装。如果提示 command not found，按下文方法安装。

安装方法

方法一：原生安装器（推荐）

最简单且官方推荐的方式，零依赖、自动 PATH 配置、后台自动更新，覆盖三大平台。

macOS、Linux、WSL，打开终端执行：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

Windows CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

二进制将安装到 ~/.local/bin/claude（Windows 为 %USERPROFILE%.local\bin\claude.exe），PATH 由安装脚本自动配置。完成后运行 claude –version 验证。

区分 PowerShell 与 CMD 的小技巧：提示符为 PS C:\ 是 PowerShell，仅 C:\ 是 CMD。若执行 irm 命令报 ‘irm’ is not recognized，说明当前是 CMD；若执行 CMD 命令报 The token ‘&&’ is not a valid statement separator，说明当前是 PowerShell。

首次启动 claude 时浏览器会自动打开 OAuth 授权页面，登录 Anthropic 账号后令牌本地存储。无浏览器环境（服务器、容器、CI Pipeline）改用环境变量：

export ANTHROPIC_API_KEY=sk-ant-...

方法二：Homebrew（仅 macOS）

适合习惯 Homebrew 工作流的 macOS 用户。Homebrew 提供两个 cask，对应不同发布通道：

# 稳定通道（约滞后一周，跳过有重大回退的版本）
brew install --cask claude-code
 
# 最新通道（新版本发布时立即收到）
brew install --cask claude-code@latest

注意 Homebrew 安装不参与 Claude Code 的后台自动更新，需手动执行 brew upgrade claude-code 或 brew upgrade claude-code@latest。两个 cask 不能同时安装，重新选择通道前需先卸载现有 cask。

方法三：WinGet（仅 Windows）

通过 Windows Package Manager 安装：

winget install Anthropic.ClaudeCode

WinGet 路径有两个已确认的已知问题，部署前需了解：

问题 1：永久”Update available”提示。GitHub Issue 33155 显示 Claude Code 的更新检查比对的是 npm 注册表版本，而 winget 包审核流程比 npm 慢 1-2 个版本，导致 winget 用户长期看到黄色更新横幅但 winget upgrade 报 No applicable update found。当前没有官方修复。

问题 2：升级可能破坏 PATH。GitHub Issue 27867 显示执行 winget upgrade Anthropic.ClaudeCode 后二进制被移到 C:\Users.local\bin\claude.exe 但 PATH 未自动更新，claude 命令找不到。修复方式是在 PowerShell profile 中追加：

$env:PATH += ";$env:USERPROFILE\.local\bin"
. $PROFILE

鉴于这两个问题，Windows 用户除非有强烈包管理器统一偏好，否则建议直接用方法一的 PowerShell 原生安装器。

方法四：Linux 包管理器（apt / dnf / apk）

适合团队规范要求所有软件经包管理器分发的场景。Anthropic 提供官方签名仓库，密钥指纹为 31DD DE24 DDFA B679 F42D 7BD2 BAA9 29FF 1A7E CACE，建议在信任前手动校验。

Debian / Ubuntu（apt）：

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
 -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] https://downloads.claude.ai/claude-code/apt/stable stable main" \
 | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Fedora / RHEL（dnf）：

sudo tee /etc/yum.repos.d/claude-code.repo <<'EOF'
[claude-code]
name=Claude Code
baseurl=https://downloads.claude.ai/claude-code/rpm/stable
enabled=1
gpgcheck=1
gpgkey=https://downloads.claude.ai/keys/claude-code.asc
EOF
sudo dnf install claude-code

Alpine Linux（apk）：

wget -O /etc/apk/keys/claude-code.rsa.pub \
 https://downloads.claude.ai/keys/claude-code.rsa.pub
echo "https://downloads.claude.ai/claude-code/apk/stable" >> /etc/apk/repositories
apk add claude-code

将 URL 中的 stable 替换为 latest 即切换到最新通道。这些路径同样不参与 Claude Code 后台自动更新，依赖系统包管理器升级流程。

Alpine 与其他 musl 发行版的额外步骤：原生安装器需先安装 libgcc、libstdc++、ripgrep，并在 ~/.claude/settings.json 中配置：

{
 "env": {
 "USE_BUILTIN_RIPGREP": "0"
 }
}

否则会因 musl 与 glibc 链接器差异导致搜索功能失效。

方法五：npm 安装（仅特定场景适用）

npm 不再是默认推荐方式，仅在 CI/CD 中需要固定版本、团队工作流以 npm 为标准、或与 Node.js 项目共用版本管理时使用：

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

要求 Node.js 18 或更高。该 npm 包安装的与原生安装器是同一个二进制——通过 @anthropic-ai/claude-code-darwin-arm64 等 optional dependency 拉取对应平台 binary，postinstall 阶段链接到 PATH。已安装的 claude 二进制本身不调用 Node.js 运行时。

禁止使用 sudo npm install -g，会导致权限污染与安全风险。遇到 EACCES 错误的正确处理方式是配置用户级 npm prefix：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

或改用 nvm 管理 Node.js 版本。

方法六：Windows 用户的 WSL 路径

WSL 适合需要 Linux 工具链或**沙盒（sandboxing）**命令执行的开发场景。WSL 2 支持沙盒，WSL 1 不支持。原生 Windows 路径与 WSL 路径的选择标准：

原生 Windows：Windows 原生项目与工具链，不支持 sandboxing
WSL 2：Linux 工具链或需要沙盒命令执行，推荐
WSL 1：仅在 WSL 2 不可用时使用

在 WSL 终端内执行方法一的 Linux 安装命令即可。注意所有依赖必须在 WSL 环境内安装而非 Windows 侧——一个常见误区是 Windows 已装 Node.js 但 WSL 内没装，npm 路径会因此报 command not found。

更新方式：每个平台不同，搞错会一直收到提醒

这是 Claude Code 安装中最容易踩坑的环节，不同安装路径的更新机制完全不同：

原生安装器：启动时与运行中后台自动检查，下次启动生效，零干预；可执行 claude update 立即触发
Homebrew：brew upgrade claude-code 或 brew upgrade claude-code@latest（取决于安装的 cask）
WinGet：winget upgrade Anthropic.ClaudeCode
apt：sudo apt update && sudo apt upgrade claude-code
dnf：sudo dnf upgrade claude-code
apk：apk update && apk upgrade claude-code
npm：重新执行 npm install -g @anthropic-ai/claude-code

切换发布通道编辑 ~/.claude/settings.json：

{
 "autoUpdatesChannel": "stable"
}

完全禁用自动更新设置 DISABLE_AUTOUPDATER=1；需彻底封锁包括 claude update 在内所有更新路径时设置 DISABLE_UPDATES，适用于企业自有分发场景。

常见问题排查

问题 1：claude –version 提示 command not found

原因：PATH 未自动更新，或终端会话未重载。

解决方案：

关闭当前终端，开新终端窗口
macOS/Linux 执行 source ~/.zshrc 或 source ~/.bashrc
Windows 关闭并重开 PowerShell 窗口
仍找不到执行 which claude（Linux/macOS）或 where claude（Windows）确认实际路径

问题 2：npm 安装报 EACCES 权限错误

原因：npm 全局目录归 root 所有，或之前用过 sudo 安装。

解决方案：不要使用 sudo。改用方法一的原生安装器，或按方法五配置用户级 npm prefix。

问题 3：Node.js 版本过旧

原因：npm 安装路径要求 Node.js 18+。

解决方案：执行 node –version 检查。低于 18 时通过 nvm install –lts 升级，或改用原生安装器（不需要 Node.js）。

问题 4：Git Bash 报 “Raw mode is not supported”

原因：Git Bash 不完整支持 Claude Code 交互式 CLI 所需的 TTY 功能。

解决方案：在 Windows PowerShell 或 Windows Terminal 中启动 claude。Git for Windows 仅作为 Bash 工具的执行后端，启动 Claude Code 本身应使用 PowerShell。

问题 5：WinGet 永久显示 “Update available”

原因：Claude Code 的更新检查比对的是 npm 注册表版本，与 winget 包注册表存在 1-2 个版本的滞后。

解决方案：当前无官方修复。可忽略提示等待 winget 包追上，或卸载 winget 安装改用方法一的原生安装器。

问题 6：WinGet 升级后 claude 命令找不到

原因：升级后二进制被移动但 PATH 未更新。

解决方案：在 PowerShell profile 中追加 $env:PATH += “;$env:USERPROFILE.local\bin”，执行 . $PROFILE 重载。

问题 7：asdf 用户从 npm 迁移后仍调用旧版本

原因：asdf shim 优先级高于原生安装路径，which claude 仍指向 ~/.asdf/shims/claude。

解决方案：对 asdf 管理过的每个 Node.js 版本逐一卸载：

for version in $(asdf list nodejs | tr -d ' *'); do
 echo "Uninstalling from nodejs $version..."
 ASDF_NODEJS_VERSION=$version npm uninstall -g @anthropic-ai/claude-code 2>/dev/null
done

如果 shim 仍残留，手动删除 ~/.asdf/shims/claude。

问题 8：OAuth 浏览器回调失败

原因：远程 SSH、devcontainer 或严格防火墙环境下 localhost 回调被阻断。

解决方案：使用手动流程——复制终端打印的 URL，在任意浏览器完成登录，将返回码粘贴回终端。或在无浏览器环境直接设置 ANTHROPIC_API_KEY 环境变量。

问题 9：企业网络下载失败或证书错误

原因：下载主机被代理拦截，或公司注入了自己的 CA 证书。

解决方案：

设置代理：export HTTPS_PROXY=http://proxy.example.com:port 后重新执行安装命令
指向公司 CA 包：export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem
将以上变量加入 shell profile 持久化

问题 10：搜索功能失效或 @file 引用找不到文件

原因：内置 ripgrep 二进制在当前系统不兼容，常见于 Alpine、musl 发行版与部分 ARM 设备。

解决方案：通过包管理器安装 ripgrep（如 apk add ripgrep、apt install ripgrep），并在 ~/.claude/settings.json 设置 USE_BUILTIN_RIPGREP=0。

验证安装与基础使用

安装完成后，建议执行以下命令验证 Claude Code 是否正常工作：

# 检查版本
claude --version
 
# 详细环境检查（PATH、认证状态、MCP 服务器、文件权限）
claude doctor
 
# 启动 Claude Code（首次启动会触发 OAuth 授权）
claude

进入 Claude Code 后可使用以下内置命令：

# 完整健康检查
/doctor
 
# 查看所有 slash 命令
/help
 
# 生成项目级 CLAUDE.md（持久上下文）
/init
 
# 压缩对话历史（释放 context window）
/compact
 
# 清空当前会话
/clear
 
# 查看会话状态与上下文使用量
/status

装完之后的关键三步：

在项目根目录运行 /init 生成 CLAUDE.md，让 Claude Code 持久理解项目结构、技术栈与团队规范——后续每次会话质量都依赖这个文件
在终端内输入 /help 浏览内置 slash 命令清单，了解 /compact、**/clear**、**/status** 等常用工具
通过 ~/.claude/settings.json 配置 **MCP（Model Context Protocol）**服务器，把 Claude Code 从命令行助手扩展为可调用 GitHub、数据库、内部工具的完整 agent 平台

卸载方式：不同安装路径对应不同清理步骤

卸载按安装方式分别处理：

原生安装器（macOS、Linux、WSL）：rm -f ~/.local/bin/claude && rm -rf ~/.local/share/claude
原生安装器（Windows PowerShell）：Remove-Item -Path “$env:USERPROFILE.local\bin\claude.exe” -Force 与 Remove-Item -Path “$env:USERPROFILE.local\share\claude” -Recurse -Force
Homebrew：brew uninstall –cask claude-code（或 claude-code@latest）
WinGet：winget uninstall Anthropic.ClaudeCode
apt：sudo apt remove claude-code，删除 /etc/apt/sources.list.d/claude-code.list 与 /etc/apt/keyrings/claude-code.asc
dnf：sudo dnf remove claude-code，删除 /etc/yum.repos.d/claude-code.repo
apk：apk del claude-code，删除仓库行与 /etc/apk/keys/claude-code.rsa.pub
npm：npm uninstall -g @anthropic-ai/claude-code

仅删除二进制并不能完全清理 Claude Code。配置目录 ~/.claude/ 与 ~/.claude.json 包含设置、MCP 服务器配置、会话历史与已授权工具列表，会被保留以便重装。彻底清理执行：

# macOS / Linux / WSL
rm -rf ~/.claude
rm ~/.claude.json
 
# 项目级配置（在每个项目目录下）
rm -rf .claude
rm -f .mcp.json

Windows 对应 %USERPROFILE%.claude 与 %USERPROFILE%.claude.json。

容易被忽略的陷阱：VS Code 扩展、JetBrains 插件与 Claude Desktop 应用都会写入 **~/.claude/**。若它们仍然安装，删除该目录后会被立即重建。彻底清理前必须先卸载所有相关 IDE 集成。

获取方式

官方文档：Claude Code 官方文档

安装与配置参考：Advanced setup

npm 包：@anthropic-ai/claude-code

故障排查中心：Claude Help Center

GitHub Issues：anthropics/claude-code

Claude Code 通过原生安装器把命令行 AI 编码工具的部署门槛压到了一行命令，但安装本身只是入口。对中文开发者而言，真正决定生产力的是后续 CLAUDE.md 上下文设计、MCP 服务器集成与 agent 工作流配置——掌握这些才是 Claude Code 实际价值所在。

本文首发于 LLM 大模型邮报。

Anthropic 测试代号 Jupiter V1 模型或将于 5 月 6 日大会公布

MISTY — Fri, 01 May 2026 04:54:57 +0000

据 TestingCatalog 报道，Anthropic 已对内部代号 Claude Jupiter V1 的新构建启动红队测试。该代号疑似遵循 Anthropic 此前以行星名称作为预发布安全测试标签的惯例，时间点临近 2026 年 5 月 6 日的 Code with Claude 开发者大会。这一观察构成了 Claude Jupiter V1 红队测试 曝光与 Code with Claude 大会的临近信号，但是否对应实际产品发布仍需以 Anthropic 官方公告为准。

内部代号命名规则与测试性质

Jupiter V1 仅为内部测试标识，据报道 Jupiter-v1-p 不会出现在公开 API 字符串或产品 UI 中。Anthropic 习惯在产品发布前使用行星名称（如 Neptune）标记安全测试阶段，这与公司早期披露的 Codename 命名惯例相符。红队测试本身是 Anthropic 责任扩展政策（Responsible Scaling Policy）下的常规步骤，要求任何前沿级模型部署前完成越狱探测与 Constitutional Classifier 压力测试，但这并不构成新模型必将发布的官方确认。

时间线对标与历史模式

Anthropic 将于 2026 年 5 月 6 日在旧金山举办 Code with Claude 开发者大会，伦敦与东京会议安排在稍后时间。根据 AiBattle 在 X 平台关于 Code with Claude 的爆料原帖，大会时间已确认为 2026 年 5 月 6 日。参考 2025 年 Neptune 代号的红队测试安排，同年 5 月中旬完成安全测试后即发布了 Claude 4 系列模型；Jupiter V1 当前的测试节奏与该模式相似。需指出的是，行星代号惯例与历史时间线吻合并不构成新模型必将发布的官方确认。

当前产品阵容留下的更新空间

Anthropic 当前公开模型阵容以 Opus 4.7 为旗舰，Sonnet 4.7 与 Haiku 4.7 尚未发布，留下中端与小型号位置。基于这一空缺，外界推测 Code with Claude 大会可能带来三种走向之一：4.7 系列在中小型号上的扩展、基于此前报道中提及的 Mythos（更早泄露的模型基础架构代号）的新一代模型，或介于两者之间的过渡更新。具体路径仍需以官方公告为准。

后续发布渠道的合理范围

若 Jupiter V1 最终对外发布，参考 Opus 4.7 此前的上线路径，新模型预计将在 Anthropic Platform、Claude Code 与 Claude 消费端应用同步推出。该判断属于基于历史模式的合理推断，并非官方时间表。读者在 5 月 6 日前应将所有相关信息视为待验证爆料。

Claude Jupiter V1 红队测试的曝光与 Code with Claude 大会的临近，构成一组可观察的时间线信号，但是否对应实际产品发布仍需以 Anthropic 官方公告为准。对中文开发者社区而言，值得关注的不止是是否有新模型发布，更包括 Sonnet 与 Haiku 中小型号是否在本轮一并刷新——这一点将直接影响 Claude Code、MCP 生态与本地集成方案的成本结构。

本文首发于 LLM 大模型邮报。

OpenAI 发布 Claude Code Codex 插件支持多模式代码审查与任务委托

MISTY — Thu, 02 Apr 2026 08:25:57 +0000

OpenAI 正式发布开源插件 codex-plugin-cc，允许 Claude Code 用户无缝调用本地 Codex 进行代码审查、对抗审查与任务委托。该插件基于 Apache-2.0 许可证发布，仓库已更新至 v1.0.4，为开发者提供了在不切换终端的前提下接入另一套代码引擎的方案。

插件架构与无状态代理原理

codex-plugin-cc 的核心定位是工作流集成器而非独立运行时。插件通过调用本地已安装的 Codex CLI 与 App Server 完成操作代理，直接复用用户当前的身份认证状态、仓库环境检查出与 MCP 配置。这种架构避免了重复安装与额外登录流程，使得在 Claude Code 中调用 Codex 时的环境感知保持一致。

Claude Code Codex 插件核心命令与审查场景

插件提供三个核心子命令匹配不同工程阶段。

/codex:review 执行标准只读代码审查，输出质量与 Codex 内直接交互一致。该命令默认支持只读模式，不会执行代码修改。适用于未提交改动或对比分支的差异审查，可指定 –base 进行分支对比。

/codex:adversarial-review 为可引导的对抗性审查。插件允许在命令后附加 focus 文本，引导 Codex 针对特定风险点（如认证逻辑、数据安全、回滚策略、竞态条件等）发起压力测试。该命令适合上线前的高优先级审查，用于验证设计取舍与隐藏假设。

/codex:rescue 用于任务委托，支持调查 Bug、尝试修复或接管卡断的对话线程。该命令支持后台运行与断点续传，开发者可通过指定模型（如 gpt-5.4-mini 或 spark）与推理强度（medium/high）控制成本与速度。未指定参数时，Codex 自动选择默认配置。

所有耗时较长的任务推荐配置为后台执行，配合 /codex:status、/codex:result 与 /codex:cancel 管理进度与终止状态。

环境依赖与配置规则

插件运行依赖两项必要条件：ChatGPT 订阅（含免费版）或 OpenAI API Key，以及 Node.js 18.18 及以上版本。

安装后需执行 /codex:setup 校验环境，缺失时提供一键安装引导。配置文件沿袭 Codex 原生规则，支持用户级 ~/.codex/config.toml 与项目级 .codex/config.toml。开发者可在项目中配置默认模型与推理策略，例如强制使用 gpt-5.4-mini 配合 high 强度，配置项在受信任的项目目录下自动加载。

可配置审查门控的潜在风险

插件提供 –enable-review-gate 选项，启用后会在 Claude Code 会话准备退出前触发 Stop Hook，强制执行一轮针对性审查。若审查发现异常，则阻断退出流程。

OpenAI 官方明确警告该机制存在工程副作用：可能引发长时间运行的 Claude 与 Codex 循环对话，消耗大量可用额度。官方建议仅在实际监控会话的前提下启用，并需自行平衡自动化拦截与操作效率。

codex-plugin-cc 的发布标志着双智能体（Dual-Agent）协作策略正在进入工程化集成阶段。开发者可以通过单一终端编排两套代码引擎，利用 Claude 的上下文理解能力与 Codex 的本地执行环境形成互补。对于需要高频代码审查与后台任务委托的工作流而言，该方案提供了低延迟的串联路径；但配置审查门控时仍需控制边界，避免资源消耗失控。

本文首发于 LLM 大模型邮报。

LLM 大模型邮报

OpenRouter 响应缓存功能上线 测试与代理重试零成本

Google 正在测试 Omni 视频模型 或将于 I/O 大会公布

OpenAI Codex 更新：引入动画宠物与配置自动导入功能

Anthropic 优化 Opus 4.7 降低关系引导场景阿谀倾向

OpenAI 发布 Codex 0.128.0 版本 支持持久化目标工作流

Artificial Analysis 评测: Grok 4.3 综合得分 53 GDPval-AA 提升 321 分

CAISI 评测 DeepSeek V4 Pro：落后美国前沿模型8 个月，性价比突出

阿里开源 Qwen-Scope 可解释性工具 覆盖 7 个 Qwen3/3.5 模型

OpenAI 正式宣布 Codex Pets 宠物体验功能

Hermes Agent 安装最简流程：Linux、macOS、WSL2 与 Termux 四端一次说清

OpenCode 安装最简流程：终端、桌面应用与 IDE 扩展三端一次说清

Codex 安装最简流程：桌面应用、CLI 与 IDE 扩展三条路径一次说清

Claude Code 安装最简流程：三端命令、自动更新与彻底卸载一次说清

OpenRouter 响应缓存功能上线测试与代理重试零成本

Google 正在测试 Omni 视频模型或将于 I/O 大会公布

OpenAI 发布 Codex 0.128.0 版本支持持久化目标工作流

阿里开源 Qwen-Scope 可解释性工具覆盖 7 个 Qwen3/3.5 模型