GLM-5.1：Claude Code 工具发现与系统角色适配 Workaround

一句话结论

在 Claude Code 或多 Agent 框架中使用 GLM-5.1 时，必须在系统提示词中显式注入 tool_reference 解析规则以防工具死锁，并拦截 messages[] 中的 system 角色以避免 HTTP 422 报错。

适用场景

• 适合的任务：使用 Claude Code CLI、OpenCode、Cline、Roo Code 通过 Anthropic 兼容接口或本地代理驱动 GLM-5.1 执行多工具、多代理协作任务。

• 不适合的任务：完全不给系统提示词约束，直接使用原生 Anthropic 客户端运行包含 ToolSearch 延迟加载工具的复杂工作流。

• 适用的模型版本：GLM-5.1、GLM-5.2。

• 适用的客户端、Agent 或 API：Claude Code CLI (2.1.x+)、Z.ai API (/api/anthropic)、BigModel.cn API、本地 SGLang/vLLM 代理。

• 推荐的推理档位和参数：标准 Agent 参数，关闭客户端未经处理的 role: "system" 注入，或关闭 ENABLE_TOOL_SEARCH。

可直接使用的内容

针对 Claude Code / CLAUDE.md 的工具理解系统提示词

将以下内容加入项目根目录的 CLAUDE.md 或全局系统提示词中，修复 GLM-5.1 遇到 tool_reference 时误判“未找到工具”并停机的缺陷：

## Understanding tool_reference Response Type

When ToolSearch returns a response containing:
{"type": "tool_reference", "tool_name": "<ToolName>"}

This means the tool is now registered and available. You must proceed immediately to invoke the tool directly:
<ToolName>({ ...parameters... })

Never respond with "The tool search didn't return any tool" when a tool_reference block is present.

Claude Code 环境变量与配置 Workaround

在 Claude Code 配置文件 ~/.claude/settings.json 或环境变量中增加配置，避免 ToolSearch 循环与端点 422 校验失败：

# 方案 A：通过环境变量直接禁用延迟工具搜索（直接预加载全部工具）
export ENABLE_TOOL_SEARCH=false

# 方案 B：配置 Anthropic 兼容端点
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="your-api-key"

测试/工作流步骤

1. 在 Claude Code 中配置 GLM-5.1 为后端模型。

2. 触发多代理或带有动态工具搜索（如 ultracode、Workflow）的任务。

3. 检查返回日志：若未注入上述 Prompt，GLM-5.1 在收到 {"type": "tool_reference", "tool_name": "Workflow"} 时会回复“未找到工具”并终止。

4. 将上述 Markdown 注入 CLAUDE.md 后再次运行，验证 GLM-5.1 能正确识别 tool_reference 并直接发起 Workflow({...}) 调用。

5. 若使用注入 SessionStart hook 的插件（如 superpowers），需通过本地中间件将 messages[] 内的 system 角色消息折叠并入顶层 system 字段，以防 GLM 端点抛出 HTTP 422。

原始证据与数据

• GitHub Issue #76 记录：在 Claude Code 中触发 ultracode 工作流时，GLM-5.1 无法原生识别 Anthropic 的 tool_reference 协议块，对比测试中 Claude Sonnet 4 与 Xiaomi Memo 能正确处理，而 GLM-5.1 会终止执行。

• GitHub Issue #74 记录：Claude Code 注入 {"role": "system", "content": "..."} 至 messages[] 数组，Anthropic 官方端点正常折叠，但 GLM 兼容端点会抛出 HTTP 422: Input should be 'user' or 'assistant'。

适用边界

• 该 Workaround 针对 Anthropic 协议层与工具发现层的不兼容问题，无法解决模型本身的底层代码逻辑错误。

• 如果模型后端部署于自建 SGLang/vLLM，可直接升级包含工具解析修复的最新分支。

来源摘录或观察（仅做合规短引）

Issue 贡献者指出：“GLM-5.1's training data does not appear to include the tool_reference response type... Adding explicit guidance about tool_reference in the system prompt enables GLM-5.1 to handle it correctly.”