Claude Code 请求 GLM（智谱）部分人报错 `APIError: 400 API 调用参数有误，请检查文档。` 排查与解决方案

Claude Code 请求 GLM（智谱）报错 APIError: 400 API 调用参数有误，请检查文档。 排查与解决方案

错误现象：Claude Code（CLI / VS Code 插件）通过 newapi 等网关请求 GLM 系列模型（如 glm-5.3-flash）时，偶发（仅部分人、部分会话）直接报错：

APIError: 400 {"error":{"code":"1210","message":"API 调用参数有误，请检查文档。"}}

本文记录一次完整的定位过程，并给出全部可行的解决方案（含网关清洗、关闭功能开关、回退 Claude Code 版本）。

TL;DR（一分钟版）

• 根因：新版 Claude Code 会按账号下发灰度开关（feature flag tengu_umber_stile），命中后 Artifact 工具的 schema 里会多出一个 field 参数，其正则校验使用了 Unicode 属性类 \p{Cc}、\p{Cf}、\p{Zl}、\p{Zp}。智谱（GLM）服务端的正则校验器不支持 \p{...} 语法，编译失败，直接拒绝整个请求。
• 为什么"偶发"：开关按账号/userID 分桶，同版本 Claude Code，有人命中有人不命中；命中的人无论开多少新会话都必现。
• 最快的解决方案（任选其一）：
  1. 在个人 ~/.claude/settings.json 里加环境变量 CLAUDE_CODE_ARTIFACT_DB_STR_REPLACE: "false" 强制关闭该功能（推荐，立即生效）；
  2. 在网关（newapi / 自建 GLM 网关）转发前清洗请求体，删除 tools[].function.parameters 中含 \p{ 的 pattern 字段（推荐，一劳永逸兜住所有人）；
  3. 回退 Claude Code 到没有该参数的旧版本（临时可用，后续升级会复发）。
• 不是智谱账号、密钥、模型名、会话状态的问题，和 newapi 本身也无关。

1. 现象与环境

从网关抓包拿到三份请求体（均为 /chat/completions 的 body JSON）：

• 1.txt：152 KB，带 32 个工具定义（tools）→ 报 400
• 2.txt：3.6 KB，不带工具（会话命名请求）→ 200
• 3.txt：3.6 KB，与 2.txt 完全相同 → 200

2. 排查历程

2.1 第一步：确认只有 1.txt 报错

用同一密钥把三份 body 原样 POST 到智谱：

结论：问题在请求体本身，且与工具定义相关。

2.2 第二步：二分定位到单个工具

对 1.txt 逐层做减法测试（每次改动后重新请求智谱）：

1. 去掉 tools → 200 ✅ ⇒ 问题在 tools；
2. 32 个工具分 4 组测试 → 只有 tools[0:8] 这组报 400；
3. 8 个工具逐个单独测 → 只有 Artifact 工具单独带上就 400。

2.3 第三步：二分到单个参数的正则

继续对 Artifact 工具的 parameters 做二分：

1. 30 个属性分两半测 → 前 15 个报 400；
2. 前 15 个逐个测 → 只有 field 这个属性报 400。

field 的定义：

{
  "description": "write_db with db_op 'str_replace' only: the top-level string field of the document to edit (one plain key, e.g. \"html\").",
  "pattern": "^(?!__.*__$)[^\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}\"\\\\./[\\]]{1,200}$",
  "type": "string"
}

罪魁祸首就是 pattern 里的 \p{Cc} / \p{Cf} / \p{Zl} / \p{Zp} —— Unicode 属性类（Unicode Property Class）语法。这种写法在 Java / ICU / .NET / PCRE 体系是合法的，但智谱服务端的正则校验引擎不认识，正则编译直接失败，于是整个请求被判为"调用参数有误"。

2.4 第四步：交叉验证

最小复现实验（单工具 + 两句话 messages）：

结论明确：智谱不兼容 JSON Schema pattern 中的 \p{...} Unicode 属性类。

最终验证：把 1.txt 里这一处 pattern 替换为不含 \p{...} 的写法，其余内容一字不动重发 → 200，正常流式响应。

2.5 第五步：为什么只有她报错、重开会话也没用？

版本号相同（2.1.267.fc3 vs 其他正常同事），但请求体里她是唯一带 field 参数的。反编译/解包 Claude Code 可执行文件（内嵌打包的 JS），找到了这段逻辑：

function kYe() { return a.CLAUDE_CODE_ARTIFACT_DB ?? true }              // Artifact DB 总开关，默认开
function DEe() {
  return kYe() && (a.CLAUDE_CODE_ARTIFACT_DB_STR_REPLACE                  // ① 环境变量覆盖（优先）
    ?? P("tengu_umber_stile", false)) === true                            // ② 服务端灰度开关（GrowthBook feature flag）
}

Artifact 工具 schema 组装处：

...i && g1t(o),          // db 能力相关参数
// g1t(e) 内部：
...e && {
  field:      s().regex(tyt).optional().describe("write_db with db_op 'str_replace' only: ..."),
  old_str:    s().min(1).max(qU).optional().describe("..."),
  new_str:    s().max(qU).optional().describe("..."),
  replace_all:IS(O().optional()).describe("...")
}

即：只有 tengu_umber_stile 开关为 true 时，field / old_str / new_str / replace_all 四个参数才会被加进 Artifact 工具 schema。这是 Anthropic 对 Artifact 数据库 db_op: "str_replace" 新能力的灰度发布。

开关值的落盘位置：~/.claude.json → cachedGrowthBookFeatures["tengu_umber_stile"]（服务端下发后缓存在本地）。

实测对比：

一切现象全部对上了：

• 同版本行为不同 → 开关按账号/userID 分桶，不是版本差异；
• 新开会话没用 → flag 与会话无关，绑定账号；
• 别人都正常 → 没命中灰度。

顺带说明这个 field 参数本身是干嘛的：它是 Artifact 数据库 str_replace 编辑功能的"文档顶层字符串字段名"入参，正则用来防注入——挡 __proto__、路径穿越（. / [ ]）、JSON 破坏字符（" \）以及不可见 Unicode 字符（\p{Cc} 控制符、\p{Cf} 零宽字符、\p{Zl} 行分隔符、\p{Zp} 段落分隔符）。防御性的正则反而因为语法不兼容打死了请求。

3. 解决方案（按推荐度排序）

方案一（个人，立即生效，推荐）：关闭功能开关

Claude Code 留了本地覆盖口子（环境变量优先于服务端 flag）。在报错用户机器的 ~/.claude/settings.json 里加：

{
  "env": {
    "CLAUDE_CODE_ARTIFACT_DB_STR_REPLACE": "false"
  }
}

重启 Claude Code 生效。之后 field / old_str / new_str / replace_all 不再进 schema，智谱即恢复 200。

• 优点：一条配置，立刻解决，不影响其他功能；
• 代价：失去 Artifact 数据库的 str_replace 编辑能力（很冷门，基本无感）；
• 备注：也可以直接手改 ~/.claude.json 里的 cachedGrowthBookFeatures["tengu_umber_stile"] = false，但那是缓存，服务端下次同步会覆盖回去，不如环境变量稳定。
• 更暴力的等价选项：CLAUDE_CODE_ARTIFACT_DB: "false"（把 Artifact 的 db 能力整个从 schema 拿掉），无必要不推荐。

方案二（网关，一劳永逸，强烈推荐同时做）：转发前清洗 tools schema

在 newapi / 自建网关的 chat completions 转发链路上，对请求体做一次幂等清洗：递归遍历 tools[].function.parameters，删除值中含 \p{ 的 pattern 字段（整个 pattern 删除，不要只删 \p{...} 片段）。

实测验证：

删除 pattern 的唯一副作用：模型生成参数时少了这条客户端校验的"提示"。真正的校验仍在 Anthropic 服务端执行，功能不受影响。若在意校验提示，可用方案 B 的显式区间改写，例如 \p{Cc} → \x00-\x1f\x7f-\x9f、\p{Cf} → 零宽/双向控制字符区间枚举、\p{Zl} → \u2028、\p{Zp} → \u2029，语义完全一致（已实测）。

Python 网关实现：

import re

UNICODE_CLASS = re.compile(r'\\[pP]\{[A-Za-z_]+\}')  # 匹配 \p{Cc} / \p{L} 等

def clean_tools_for_zhipu(body: dict) -> dict:
    """就地清洗 body['tools'] 中智谱不支持的 pattern"""
    for tool in body.get('tools') or []:
        params = (tool.get('function') or {}).get('parameters')
        if not params:
            continue
        stack = [params]
        while stack:
            node = stack.pop()
            if isinstance(node, dict):
                pat = node.get('pattern')
                if isinstance(pat, str) and UNICODE_CLASS.search(pat):
                    del node['pattern']          # 整个删掉
                stack.extend(node.values())
            elif isinstance(node, list):
                stack.extend(node)
    return body

Go 网关实现：

var unicodeClassRe = regexp.MustCompile(`\\[pP]\{[A-Za-z_]+\}`)

func cleanPatterns(v interface{}) {
    switch t := v.(type) {
    case map[string]interface{}:
        if p, ok := t["pattern"].(string); ok && unicodeClassRe.MatchString(p) {
            delete(t, "pattern")
        }
        for _, child := range t {
            cleanPatterns(child)
        }
    case []interface{}:
        for _, child := range t {
            cleanPatterns(child)
        }
    }
}

// handler 中：
// var body map[string]interface{}
// json.Unmarshal(rawBody, &body)
// if tools, ok := body["tools"].([]interface{}); ok {
//     for _, tool := range tools { cleanPatterns(tool) }
// }
// out, _ := json.Marshal(body)

注意事项：

1. 范围：只处理 tools[].function.parameters（含嵌套），不要碰 messages —— 那里的 \p{...} 是普通文本，智谱不校验；
2. 幂等：清洗幂等，可放最外层中间件重复执行无害；
3. 日志：清洗时打一条 log（工具名 + 字段路径），便于观察 Anthropic 后续又新增了什么 schema；
4. 可扩展：将来智谱再报 1210 且与其他 schema 语法冲突（如 anyOf、propertyNames），同一清洗入口加规则即可。

方案三（临时）：回退 Claude Code 版本

确认"是否带 field 参数"与版本有关的部分：旧版本二进制里没有这个 schema 分支就不会发出去。可用低版本临时绕过：

# npm 方式安装固定版本
npm install -g @anthropic-ai/claude-code@<旧版本号>

# 或使用原生安装器对应的降级方式（Windows 原生版在 ~/.local/bin/claude.exe）

• 注意：
  1. 降级只能救自己一时。这个 schema 是随版本演进来的，只要服务端 flag 仍命中，将来升级到带该代码的版本就复发；
  2. VS Code 插件有自动更新，降级后注意关闭自动更新，否则会被悄悄更回去；
  3. 需要配合关闭自动更新：~/.claude/settings.json 中 "autoUpdates": false（或环境变量 DISABLE_AUTOUPDATER=1）；
  4. 由于该参数实际由账号级灰度开关控制，回退版本是三者中唯一"治标且会复发"的方案，仅建议作为临时手段。

方案四（推动上游修复，可选）：给智谱提工单

\p{...} 是 JSON Schema pattern（基于 ECMA-262 正则语义）中常见且合法的写法，Java / ICU / .NET / PCRE 生态广泛支持。智谱的 1210 校验器应对未知正则语法做降级兼容（忽略或宽松处理），而不是直接拒绝整个请求。可附上最小复现：

{
  "model": "glm-5.3-flash",
  "messages": [{"role": "user", "content": "hi"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "t",
      "description": "x",
      "parameters": {
        "type": "object",
        "properties": {
          "f": {"type": "string", "pattern": "^\\p{Cc}{1,200}$"}
        }
      }
    }
  }]
}

以及等价的不含 \p{...} 版本可 200 的对照，说明是 \p{...} 单一因素导致。

4. 排查同类问题的通用方法论

1. 先二分请求体：把报错 body 和正常 body 都拿到（网关抓包），按 tools → 单工具 → 单参数逐层做减法，每次改动直接重发上游验证。本次从 152 KB 的 body 到 1 个正则只用了 7 轮请求。
2. 不要信"版本一样所以行为一样"：现代 AI 客户端大量使用账号级灰度（feature flag / 实验分组），同版本不同账号的工具 schema 可能不同。Claude Code 的 flag 缓存就在 ~/.claude.json 的 cachedGrowthBookFeatures，可以直接对比。
3. 三方 LLM 网关对 OpenAI 协议的兼容性差异集中在 schema 校验：pattern 正则方言（\p{...}、(?<=...) 等）、anyOf / oneOf 深度、$schema / additionalProperties / propertyNames 等字段，都是常见雷区。网关侧做一层 schema 白名单/清洗是通用兜底。
4. 找客户端的控制开关：客户端二进制（Bun 打包的 JS 可直接 strings/grep 出可读源码）里的 ?? 链通常暴露了"env 覆盖 → flag → 默认值"三级开关，找到环境变量名就能本地压制服务端行为。

5. 速查表

研究日期：2026-09-10。环境：Claude Code 2.1.267（CLI + VS Code 插件）、newapi 自建网关、智谱开放平台 glm-5.3-flash。所有实验均使用真实密钥对智谱线上 API 完成，结论可直接复现。