Claude Code 的 Harness 配完不生效？TaoToken 这样改 settings.json

1. 为什么你的 Harness 配置写完像没写如果你正在折腾 Claude Code 的 Harness 架构大概率遇到过这种场景照着文档把settings.json里的 Permission Manager 配好了Hook System 的PreToolUse也挂在Bashmatcher 上了CLAUDE.md写了block-secrets.sh也放到.claude/hooks/里了结果一跑——钩子不触发或者请求直接报错。你盯着终端分不清到底是配置层级写错了还是模型通道压根没通。这个问题在进阶玩家圈子里特别常见因为 Harness 的配置是分层的而模型通道是另一条独立的链路。两者混在一起排查就像同时调两个未知变量永远找不到根因。我试过的做法是先把模型通道单独验证通再回头核对settings.json的优先级和 matcher最后才去补第四章那套防密钥提交的钩子和 review 技能。这篇就按这个顺序来。凡是涉及模型通道和 Key 的部分都统一走 TaoToken注册后在控制台创建 Key把 Claude Code 的 Base URL 填成https://taotoken.net/api注意不带/v1也不带任何 UTM 参数。TaoToken 在这里只负责提供 Key 和 Base URL 这两样东西Hooks、SKILL.md、CLAUDE.md的写法你仍然照原文自己写它不替代你的配置文件。适合谁看已经过了「打开终端提问等输出」阶段开始动settings.json、写 Hook 脚本、配 Skill 的进阶用户。如果你还在黑盒使用阶段这篇的排查思路同样能帮你理解 Harness 到底在管什么。2. 先把模型通道和 Harness 配置拆开2.1 两条链路为什么容易互相甩锅Claude Code 的 Harness 架构里Permission Manager 管的是「哪些工具能用、哪些目录能读写」Hook System 管的是「在 29 个生命周期事件上挂你自己的 Shell 脚本」。这两者全部写在settings.json里优先级是全局 → 项目 → 用户。而模型通道管的是「请求能不能发出去、发到哪个 endpoint、用哪个 Key」。问题在于当 Hook 不触发时你第一反应是 matcher 写错了当请求报错时你第一反应是 Key 失效了。但实际情况经常反过来——Hook 不触发是因为 Claude Code 根本没启动成功通道没通请求报错是因为settings.json里某个字段格式错了导致整个配置加载失败。两条链路互相甩锅排查就卡住了。2.2 正确的排查顺序我建议的顺序是先确认通道本身没问题用一条最小请求验证再回到settings.json核对层级和 matcher最后才去写第四章的防密钥钩子和 review 技能。这个顺序的好处是每一步只动一个变量出错时能立刻定位。注意不要一上来就改settings.json里的 Hook 配置。如果通道没通你改再多 Hook 也不会触发只会让你误以为 Hook 写错了。2.3 TaoToken 在这里的角色TaoToken 只做一件事给你一个可用的 Key 和一个 Base URL。你拿到这两样之后Claude Code 的模型通道就通了。剩下的 Harness 配置——settings.json的优先级、PreToolUse的 Bash matcher、block-secrets.sh的 exit code 逻辑——全部照原文自己写。这样职责清晰通道问题找 TaoToken配置问题找自己的文件。3. 可复制的配置从 Key 到 settings.json3.1 创建 Key 并设置环境变量先去 TaoToken 官网注册账号然后在控制台创建一个 API Key。拿到 Key 之后不要硬编码到任何会提交到 git 的文件里用环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY你的Key如果你用的是 Claude Code 的配置文件方式也可以写进~/.claude/settings.json的env字段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key } }这里有个坑Base URL 一定不要带/v1。很多人习惯性写成https://taotoken.net/api/v1结果请求 404。TaoToken 的接入地址就是https://taotoken.net/api路径由 Claude Code 自己拼接。3.2 最小请求验证通道在动settings.json之前先用一条最小请求确认通道通了。最直接的方式是用 curlcurl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-6, max_tokens: 64, messages: [{role: user, content: ping}] }如果返回一个正常的 JSON 响应说明通道没问题。如果返回 401检查 Key返回 404检查 Base URL 是不是多带了/v1返回超时检查网络。3.3 核对 settings.json 的优先级通道通了之后再回来看settings.json。Permission Manager 的优先级是全局 → 项目 → 用户这意味着项目级配置会覆盖全局级用户级会覆盖项目级。很多人 Hook 不触发就是因为把 Hook 写在了全局配置里但项目级配置里有一个空的hooks字段把它覆盖了。一个正确的PreToolUse配置长这样{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: .claude/hooks/block-secrets.sh } ] } ] } }注意matcher是大小写敏感的Bash不能写成bash。另外command的路径是相对于项目根目录的如果你在子目录里启动 Claude Code路径就会错。3.4 block-secrets.sh 的 exit code 逻辑Hook 脚本的核心是 exit codeexit 2是硬阻断模型无法绕过exit 1只是警告。防密钥提交的脚本大概是这样#!/usr/bin/env bash input$(cat) if echo $input | grep -qE AKIA|sk-|ghp_; then echo 检测到疑似密钥已阻断 2 exit 2 fi exit 0记得给脚本加执行权限chmod x .claude/hooks/block-secrets.sh。没有执行权限Hook 会静默失败这也是「钩子不触发」的常见原因之一。4. 验证请求与成功结果4.1 用 Claude Code 本身验证环境变量设好之后直接跑claude --version claude 用一句话说明当前目录有几个文件如果 Claude Code 能正常响应说明通道和基础配置都通了。这时候再去触发 Hook让 Claude 执行一条包含sk-的 Bash 命令看它是否被阻断。4.2 观察 Hook 是否真的触发Hook 触发时你会在终端看到脚本的 stderr 输出。如果没看到先确认脚本有执行权限再确认settings.json里没有更高优先级的配置覆盖它。可以用claude --debug启动看配置加载日志里 Hook 有没有被注册。4.3 成功结果长什么样通道通了的标志是Claude Code 能正常对话、能执行工具调用。Hook 生效的标志是包含密钥特征的 Bash 命令被exit 2硬阻断模型收到阻断信号后不会继续尝试绕过。两个都验证过再接着按原文第四章把 review 技能和更多 Hook 补上。5. 本篇常见错排查5.1 Hook 不触发最常见的原因是三个脚本没有执行权限、matcher大小写写错、settings.json层级被覆盖。排查顺序是先用ls -l看权限再用claude --debug看配置加载最后检查项目级和用户级配置有没有冲突。5.2 请求报错401 是 Key 问题404 是 Base URL 多带了/v1超时是网络问题。还有一种情况是settings.json格式错误导致整个配置加载失败这时候 Claude Code 可能连启动都启动不了报错信息会指向 JSON 解析失败。5.3 分不清是配置还是通道用第 3.2 节的 curl 命令单独测通道。curl 通了就是配置问题curl 不通就是通道问题。这一步能省掉大量瞎猜的时间。5.4 CLAUDE.md 没生效CLAUDE.md要放在项目根目录Claude Code 每次启动会读它。如果你在子目录启动它读的是子目录的CLAUDE.md。另外CLAUDE.md的内容是作为上下文注入的不是硬约束真正的硬约束要靠 Hook 的exit 2。6. 通道通了之后Harness 才真正开始把模型通道和 Harness 配置拆开排查之后你会发现大部分「配完不生效」的问题都能快速定位。通道的事交给 TaoToken你只需要在控制台创建 Key把 Base URL 填成https://taotoken.net/api然后用一条最小请求验证。通道通了之后settings.json的优先级、PreToolUse的 matcher、block-secrets.sh的 exit code 逻辑才是你真正要花时间打磨的地方。如果你还在验证模型阶段可以先用模型对话确认通道稳定如果你准备长期跑编码任务和 Agent 编排Coding Plan 会更适合接入过程中遇到 Key 或 Base URL 的问题直接看接入文档和 API Keys 页面。通道是地基Harness 是房子地基没打好之前别急着装修。