1. 从一次“工具不生效”的排查说起Claude Code 本身已经能读写文件、跑命令、查代码但真正让它从“会聊天的终端”变成“懂你项目的工程助手”的是自定义 Tooling。简单说Tooling 就是给 Claude Code 挂上一批它自己能调用的外部能力查内部 API 文档、跑项目专属的 lint、连你们自建的工单系统、按团队规范生成脚手架。适合谁适合已经用 Claude Code 写代码、但发现它总在“通用知识”和“你的私有上下文”之间断层的开发者。我遇到最多的问题不是“不会写工具”而是“写完了 Claude Code 根本不知道有这个工具”。表现很典型你在配置文件里加了一个自定义命令重启会话后问它“帮我查一下订单服务的接口定义”它要么装作没看见要么用训练数据里的通用答案糊弄你。根因通常有三个配置文件放错位置、工具描述没被正确加载、或者 API 通道没走通导致工具调用请求发不出去。这篇就按“能跟做”的标准来先给 settings.json 和 config.toml 的可复制骨架再演示怎么通过 TaoToken 统一 Key 和 API 通道把自定义工具接进来最后用一条验证请求确认 Tooling 真的生效。全程不需要你改 Claude Code 的源码配置层面就能完成。2. TaoToken 前置把 Key 和通道先理顺在写任何 Tooling 配置之前得先解决一个前置问题Claude Code 调用模型和调用你的自定义工具走的是同一条 API 通道。如果通道本身没配好工具配置写得再漂亮也是空转。TaoToken 在这里的角色是统一入口——你只需要维护一个 Key模型对话、工具调用、后续的 Coding Plan 都从同一个地址出去省得在多个环境变量之间来回切换。先拿 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建时建议按用途命名比如claude-code-tooling方便后面排查是哪个 Key 在调用。拿到 Key 之后API 基地址统一用 https://taotoken.net/api 注意这个地址不带任何查询参数。Claude Code 兼容 Anthropic 的接口协议所以你在环境变量里配置的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个。如果你用的是 Claude Code 的 Anthropic 兼容模式接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的字段说明。注意Key 只存在本地环境变量或配置文件里不要写进会提交到 Git 的 settings.json。下面给的骨架里我用占位符你替换成自己的值即可。这一步做完先别急着配工具。用模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一条消息确认 Key 和通道是通的。通道不通的情况下配 Tooling你会把时间浪费在错误的方向上。3. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两层一层是全局的settings.json管模型、权限、环境变量另一层是项目级的config.toml管这个项目里有哪些自定义工具、怎么调用。两层配合工具才会被加载。先看settings.json。它通常放在~/.claude/settings.jsonWindows 下是%USERPROFILE%\.claude\settings.json。下面这份骨架你可以直接复制把 Key 换成自己的{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-your-taotoken-key-here, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Bash(git status), Bash(git diff:*), Read, Write, Edit ], deny: [ Bash(rm -rf:*), Bash(curl:* | sh) ] }, tools: { enabled: true, configPath: ./.claude/config.toml } }这里有几个点值得展开。env块里的ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址Claude Code 会把所有模型请求发到这里。permissions块控制工具能干什么allow是白名单deny是黑名单建议把危险命令先 deny 掉。tools.configPath指向项目级的工具配置文件相对路径是相对于项目根目录。再看config.toml放在项目根目录的.claude/config.toml。这份骨架定义了两个自定义工具一个查内部 API 文档一个跑项目专属的代码规范检查。# .claude/config.toml [project] name order-service root . [[tools]] name query_internal_api description 查询内部 API 文档。输入接口名或关键词返回接口定义、参数和示例。当用户询问内部服务接口时使用此工具。 command python3 args [.claude/tools/query_api.py, --query, {{input}}] input_schema { type object, properties { input { type string, description 接口名或关键词 } }, required [input] } timeout 30 [[tools]] name run_team_lint description 运行团队自定义的代码规范检查。输入文件路径返回违规项列表。在提交代码前或用户要求检查规范时使用。 command bash args [.claude/tools/team_lint.sh, {{file}}] input_schema { type object, properties { file { type string, description 要检查的文件路径 } }, required [file] } timeout 60description字段是重中之重。Claude Code 靠这段文字判断“什么时候该调用这个工具”。写得越具体命中率越高。比如“当用户询问内部服务接口时使用”就比“查询 API”强得多。input_schema用 JSON Schema 描述入参Claude Code 会按这个结构生成调用参数。command和args是实际执行的命令{{input}}和{{file}}是占位符会被替换成模型传入的值。配套的工具脚本也得有。query_api.py的最小实现#!/usr/bin/env python3 import argparse import json API_DOCS { createOrder: { method: POST, path: /api/v1/orders, params: {userId: string, items: array}, example: POST /api/v1/orders {\userId\: \u123\, \items\: []} }, getOrder: { method: GET, path: /api/v1/orders/{orderId}, params: {orderId: string}, example: GET /api/v1/orders/o456 } } def main(): parser argparse.ArgumentParser() parser.add_argument(--query, requiredTrue) args parser.parse_args() key args.query.strip() result API_DOCS.get(key) if result: print(json.dumps(result, ensure_asciiFalse, indent2)) else: matches {k: v for k, v in API_DOCS.items() if key.lower() in k.lower()} print(json.dumps(matches or {error: not found}, ensure_asciiFalse, indent2)) if __name__ __main__: main()team_lint.sh可以先用一个简单版本验证链路#!/bin/bash FILE$1 if [ ! -f $FILE ]; then echo {\error\: \file not found: $FILE\} exit 1 fi # 示例检查是否有多余的空格结尾 VIOLATIONS$(grep -n $ $FILE | head -20) if [ -z $VIOLATIONS ]; then echo {\status\: \pass\, \violations\: []} else echo {\status\: \fail\, \violations\: \$VIOLATIONS\} fi给脚本加执行权限chmod x .claude/tools/team_lint.sh。到这里配置骨架和工具脚本就齐了。4. 验证请求确认 Tooling 真的生效配置写完不代表生效。Claude Code 加载工具是在会话启动时完成的所以改完配置必须重启会话。重启后先做一次“工具是否被识别”的检查。启动 Claude Code输入/tools或者直接问它“你现在有哪些可用的工具”。如果配置正确你应该能在返回列表里看到query_internal_api和run_team_lint这两个名字。看不到的话先别往下走回到第 5 节排查。确认工具被识别后发一条会触发工具调用的请求。比如帮我查一下 createOrder 这个内部接口的定义和调用示例。预期行为是Claude Code 识别出这需要调用query_internal_api传入inputcreateOrder执行python3 .claude/tools/query_api.py --query createOrder拿到 JSON 结果后组织成自然语言回答。你看到的输出应该包含POST /api/v1/orders、参数列表和示例。再验证第二个工具检查一下 src/order.py 是否符合团队代码规范。这次应该触发run_team_lint传入文件路径返回违规项或 pass。如果文件里确实有行尾空格你会看到具体的行号和内容。提示如果工具被识别但调用失败先手动在终端跑一遍command args拼出来的命令确认脚本本身没问题。脚本能跑通、Claude Code 调不动问题多半在参数占位符或权限配置上。验证通过后你可以把这两个工具换成自己项目真正需要的能力。比如把query_api.py换成读你们内部 Swagger 的脚本把team_lint.sh换成跑 ESLint 或 golangci-lint 的封装。配置结构不用变只换command和args。5. 本篇常见错排查工具列表里看不到自定义工具。最常见的原因是config.toml路径不对。settings.json里的tools.configPath是相对项目根目录的如果你在子目录启动 Claude Code相对路径就会解析错。解决办法是用绝对路径或者确保始终在项目根目录启动。另一个原因是 TOML 语法错误比如[[tools]]写成了[tools]后者是单表前者才是数组。用python3 -c import tomllib; tomllib.load(open(.claude/config.toml,rb))可以快速校验语法。工具被识别但调用时报“command not found”。这是环境变量问题。Claude Code 执行工具命令时的 PATH 可能和你终端里的不一样。把command写成绝对路径比如/usr/bin/python3而不是python3。或者在你的 shell 配置里把需要的路径 export 出去重启会话。模型不调用工具直接用自己的知识回答。这是description写得不够具体。Claude Code 判断是否调用工具主要看描述和用户意图的匹配度。把描述改成“当用户询问内部服务接口定义、参数或调用示例时必须使用此工具”加上“必须”这类强约束词命中率会明显提升。另外input_schema的description也要写清楚模型生成参数时会参考它。调用返回了结果但模型说“工具执行失败”。检查你的脚本输出格式。Claude Code 期望工具把结果打到 stdoutstderr 用于错误信息。如果你的脚本把日志打到了 stdout模型会把这些日志当成工具返回值解析失败。确保业务结果走 stdout调试信息走 stderr。改了配置但行为没变。Claude Code 不会热加载配置文件。每次改完settings.json或config.toml都要完全退出会话再重新启动。如果你用的是 IDE 插件形态重启插件宿主进程。API 请求 401 或 403。回到第 2 节确认ANTHROPIC_API_KEY是 TaoToken 控制台里创建的那个且没有多余空格。ANTHROPIC_BASE_URL必须是https://taotoken.net/api结尾不要带斜杠。如果 Key 没问题但还是 401去控制台看看这个 Key 的额度或权限是否被限制。6. 把 Tooling 用起来从验证到日常配置跑通之后真正提升效率的是把工具嵌进日常工作流。比如你可以加一个search_commit_history工具让 Claude Code 在改代码前先查这个文件最近谁改过、改了什么加一个run_migration工具让它按项目规范生成数据库迁移脚本加一个query_ticket工具把工单系统和编码会话连起来。如果你打算长期用 Claude Code 做编码和 Agent 任务Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有针对这类场景的通道说明。模型对话验证在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。最后给一个实用技巧工具脚本的返回值尽量用 JSON字段名保持稳定。这样即使你后面换了实现语言Claude Code 侧的解析逻辑不用动。另外每个工具的timeout别设太大30 到 60 秒足够超时会让整个会话卡住。工具数量也别一次加太多先加两三个高频的跑顺了再扩。