Claude Code v2.1.312 更新：OIDC 用户识别与多项修复

版本速览

Claude Code 发布了 v2.1.312 版本更新。这次发布延续了该项目高频迭代的节奏，更新内容以功能增补和问题修复为主，涉及身份认证、交互体验、模型适配与云会话等多个模块。对于日常依赖 Claude Code 进行开发的用户来说，几个看似细小的改动实际上会影响实际使用体验，值得逐条了解。

新增能力：OIDC 用户标识与点击发送

本次更新在 Claude apps 网关中新增了 oidc.user_id_claim 配置项。这意味着企业可以通过 id_token 中的声明来识别用户身份，而不再局限于默认的 sub 字段。发布说明中特别举了 Microsoft Entra ID 的 oid 作为例子——对于使用微软身份体系的组织，这一改动让用户标识与既有身份系统对齐，减少适配层的额外工作。

另一个面向日常操作的小改进是「点击发送」：在全屏模式下，排队中的消息下方会显示「to send now」提示，点击它即可立即发送该消息，效果与按下对应快捷键一致。对于习惯用鼠标操作或需要临时插队的用户，这减少了记忆快捷键的负担。

OIDC 与 id_token 声明

OIDC（OpenID Connect）是构建在 OAuth 2.0 之上的身份认证协议，其核心产物是 id_token——一个由身份提供方签名、以 JWT 格式承载用户身份信息的令牌。id_token 内部由若干「声明」（claim）字段组成，例如 sub 表示该用户在提供方处的唯一主体标识，email、name 等则承载其他属性。不同身份提供方对同一用户的标识方式并不统一：Microsoft Entra ID 除 sub 外还会给出 oid（对象 ID），后者在同一租户内保持稳定，常被用作跨应用的用户主键。Claude apps 网关新增 oidc.user_id_claim，本质是允许管理员指定用哪个声明字段作为用户标识，从而与企业现有的账号映射、审计与配额体系对齐，避免在网关侧额外维护一张 ID 映射表。

修复黑洞：从 CLAUDE.md 覆盖到 PDF 读取

本次修复列表中有一项值得单独讨论：此前 Claude 在只看到超大 CLAUDE.md、规则文件或子目录中 @ 引用文件的开头部分时，可能会直接覆盖整个文件。现在 Write 工具会要求 Claude 完整读取文件，或改为就地编辑。这类问题对项目配置文件的破坏性较大，修复后显著降低了误覆盖风险。

其他修复覆盖了多条使用路径：

• 从 VS Code 扩展登录后，托管设置与组织策略在当次会话剩余时间内未被拉取的问题；
• 在 Bash 中 cd 进入 git 仓库更深目录后，按目录配置和 paths: 定义的 skills 找不到的问题；
• 终端会话恢复后首次回复在下一次恢复时可能丢失的罕见情况；
• 无效名称的命令导致所有命令加载失败、进而使 claude -p 无输出；
• 清理旧会话文件与 PDF 读取并发时触发的 pdftoppm failed 错误。

此外，还修复了任务进行中切换 effort 等级时，spinner、OpenTelemetry 与 transcript 提前显示新等级的问题——现在它们只显示实际生效的等级。

CLAUDE.md 与 @ 引用文件

CLAUDE.md 是 Claude Code 读取的项目级指令文件，用于存放编码规范、构建命令、目录约定等长期上下文；在子目录中放置 CLAUDE.md 可以形成分层配置，而 @path 语法则允许在指令文件中引用其他文件的内容，实现上下文的模块化拆分。由于这些文件往往体量不小，模型在上下文受限时可能只读到开头片段。Write 工具此前允许基于不完整内容整体重写文件，一旦发生就会把未被读取的部分静默抹掉。改为「要求完整读取或就地编辑」，实际上是把破坏性写操作的门槛提高到与读取范围一致，属于对工具调用安全边界的一次收紧。

行为变更：提示词、钩子与模型识别

Bedrock、Vertex、Foundry 和 Mantle 现在对 Claude Code 无法识别的模型名称使用更短的系统提示词，这类名称包括自定义部署名和推理配置文件 ARN。即使这些名称背后实际指向 Sonnet 或 Haiku，也会套用短提示词。若需保留完整提示词，可设置 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0。

在消息被标记后触发的自动模型切换，现在也覆盖无法识别的模型名。要关闭该行为，可设置 CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=1。

钩子执行方面，提示词与 agent 钩子现在每个会话最多同时运行 24 个（含子代理），另外最多允许 12 个等待时间超过事件超时阈值的钩子；小于 1 秒的超时值现在按 1 秒计算。这类限制避免了钩子并发失控，对复杂自动化流程的稳定性有实际意义。

用量提示的措辞也做了调整：原来的「session limit」改称为「5-hour limit」，VS Code 端则改为显示具体重置时间，如「Resets at 3:10 PM」，比相对时间更直观。

Bedrock、Vertex、Foundry 与 Mantle

这几个名称对应 Claude 模型的不同托管与接入渠道：Amazon Bedrock 与 Google Cloud Vertex AI 是云厂商提供的模型托管服务，Anthropic 同时通过它们分发 Claude；Foundry 指 Microsoft Azure AI Foundry，Mantle 则是相关的部署与推理配置体系。在这些平台上，用户可以使用自定义部署名或推理配置文件 ARN 来调用模型，因此请求中的模型标识往往是一个平台侧生成的字符串，而非 claude-sonnet-4 这类规范名。Claude Code 无法据此判断背后实际是 Sonnet 还是 Haiku，只能按「未知模型」处理。默认套用更短的系统提示词，是在无法确认模型能力时的保守策略，代价是可能损失一部分指令细节，因此保留了 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0 这一手动退出开关。

钩子（hooks）机制

钩子是 Claude Code 提供的事件回调机制，允许用户在会话生命周期的特定节点（如工具调用前后、提示词提交时）自动执行外部命令或脚本，常用于格式化代码、运行检查、记录日志或注入额外上下文。钩子分为命令钩子、提示词钩子与 agent 钩子等类型，其中后两者会额外消耗模型调用。正因如此，钩子的并发数量直接关系到资源占用与事件队列的排队行为：一旦某个钩子执行缓慢或超时，后续事件就可能被阻塞。本次设定的「每会话最多 24 个并发（含子代理）」与「额外 12 个超时等待额度」构成了双层限流，并把小于 1 秒的超时统一抬到 1 秒，避免过于激进的超时配置导致钩子被频繁中断。

云会话与集成修复

云会话方面，创建或编辑云端运行的 routine 时，模型选择器新增了 effort 等级选项；云环境设置中的 setup 脚本框升级为带颜色、行号和复制按钮的 Bash 编辑器；Claude 向云会话添加仓库时，改为展示简短的结果表格而非原始 JSON。同时修复了发送失败后重发未改动消息可能执行两次、云环境创建失败的错误只以 toast 形式出现在对话框外等问题。

Slack 集成（Claude Tag）方面，重试提示现在会说明所用模型或指出触发了速率限制；修复了私有频道转为公开并获得新 ID 后开关与 agent 设置回退到工作区默认值、网络访问设为 None 的频道中 Claude 不回复、以及跨线程回复时文件发错线程等问题。

Code Review 修复了 GitHub 延迟推送事件导致审查过期提交或未审查的情况，现在会审查 PR 的当前提交。

小结

v2.1.312 没有引入颠覆性功能，但 OIDC 用户标识和企业级会话稳定性修复对团队用户价值明显。对于依赖 CLAUDE.md 等项目配置的开发者，文件覆盖问题的修复也降低了日常风险。