★ FEATURED ARTICLE 1. 从一次“算错账”说起Claude code 工具使用入门到底解决什么问题如果你让 Claude 直接算1984135 × 9343116它大概率会给你一个看起来很像样、但实际错得离谱的数字。我实测过几次同一道题能给出好几个不同答案偏差动辄几百亿。这不是模型“笨”而是大语言模型本质上在做概率预测不是在做精确计算。Claude code 工具使用tool use要解决的就是这类问题让模型不再“硬算”而是学会在需要的时候调用你写好的函数。你给它一个计算器工具它就会把operationmultiply, operand11984135, operand29343116这样的参数交回来由你的代码去算再把正确结果喂回去。整条链路走通之后模型负责“决定用什么工具、传什么参数”你的代码负责“真正执行”。这篇文章面向的是刚接触 Claude code 工具使用的开发者尤其是想在国内网络环境下稳定跑通第一个工具调用示例的人。我会从零写一个 calculator 工具给出可复制的工具定义 JSON、settings 配置片段并用 TaoToken 统一 Key 接入把请求真正发出去。你跟着做能亲眼看到stop_reason从end_turn变成tool_use再拿到正确答案18538003464660。工具使用的完整流程最多四步第一步你在 API 请求里带上工具定义和用户提示第二步Claude 返回tool_use告诉你它想调用哪个工具、传什么参数第三步你在本地执行工具代码把结果作为tool_result塞回对话第四步Claude 用这个结果生成最终回答。本文的第一个示例只走到第三步因为问题简单拿到计算结果就够了。理解这四步后面做研究助手、查数据库、调内部 API 都是同一套骨架。2. TaoToken 统一 Key 前置准备Base URL、Key 与模型 ID 三件套在写工具之前先把“通道”铺好。Claude code 工具使用示例要跑起来你需要三样东西一个能访问 Anthropic 兼容接口的 Base URL、一个可用的 API Key、一个明确的模型 ID。TaoToken 的作用就是把这三件事统一起来你不需要分别去记不同厂商的地址和鉴权方式。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录然后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 进去之后找到 API Keys 页面新建一个 Key 并复制保存。这个 Key 只会完整显示一次丢了就得重建所以建议直接写进环境变量别硬编码在脚本里。Base URL 用 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数保持干净。模型 ID 方面本文示例沿用课程里的claude-3-haiku-20240307你也可以在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 里看看当前可用的模型列表挑一个支持工具调用的即可。环境变量这样设置Linux/macOS 用 exportWindows PowerShell 用$env:export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Claude Code CLI 这类工具它读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量写法略有差异export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥Python SDK 这边anthropic包会自动读取ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL所以只要环境变量设对了Anthropic()不传参也能连上。如果你更习惯显式传参也可以这样写from anthropic import Anthropic client Anthropic( base_urlhttps://taotoken.net/api, api_keysk-你的TaoToken密钥, )这里有个容易踩的坑Base URL 结尾不要多加/v1。SDK 内部会自己拼接路径你手动加/v1反而会变成/v1/v1/messages直接 404。另外 Key 一定要用sk-开头的那串完整字符串复制时别把前后空格带进去否则会报 401。把这三件套准备好后面的工具定义和请求代码才有意义。很多人卡在第一步不是代码写错而是 Key 或 Base URL 配错所以这一步值得多花两分钟确认。3. 可复制配置calculator 工具定义 JSON 与 settings 片段现在进入正题写你的第一个工具。工具定义是一个 JSON 对象包含三个字段name、description、input_schema。name必须匹配^[a-zA-Z0-9_-]{1,64}$也就是只能用字母、数字、下划线和短横线长度 1 到 64。description是给模型看的纯文本说明写清楚工具干什么、什么时候用。input_schema是标准 JSON Schema描述参数类型和必填项。先写本地函数确保它脱离 Claude 也能跑def calculator(operation, operand1, operand2): if operation add: return operand1 operand2 elif operation subtract: return operand1 - operand2 elif operation multiply: return operand1 * operand2 elif operation divide: if operand2 0: raise ValueError(Cannot divide by zero.) return operand1 / operand2 else: raise ValueError(fUnsupported operation: {operation})测试一下calculator(add, 10, 3)返回13calculator(divide, 200, 25)返回8.0。函数没问题了再把它包装成工具定义{ name: calculator, description: A simple calculator that performs basic arithmetic operations., input_schema: { type: object, properties: { operation: { type: string, enum: [add, subtract, multiply, divide], description: The arithmetic operation to perform. }, operand1: { type: number, description: The first operand. }, operand2: { type: number, description: The second operand. } }, required: [operation, operand1, operand2] } }注意enum的用法它把operation限定在四个值里模型就不会瞎传plus或times。required里三个参数全列上因为计算器缺一个操作数就没法算。如果你用 Claude Code CLI可以在项目根目录建一个.claude/settings.json把环境变量固化进去省得每次开终端都 export{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 } }这个 settings 片段和前面的环境变量是等价的选一种就行。用 CLI 的话推荐 settings.json团队协作时把 Key 换成占位符别提交到仓库。工具定义写好后请求时通过tools参数传进去response client.messages.create( modelclaude-3-haiku-20240307, max_tokens300, messages[{role: user, content: 计算1984135乘以9343116。只返回结果}], tools[calculator_tool], )这里calculator_tool就是上面那个 JSON 对象Python 里是 dict。请求发出去Claude 就知道它有个计算器可以用了。4. 验证请求从 stop_reason 到 tool_result 的完整链路请求发出去之后看响应。正常对话时stop_reason是end_turn但这次你会看到tool_useprint(response.stop_reason) # 输出: tool_useresponse.content里不再是纯文本而是一个ToolUseBlockprint(response.content) # [ToolUseBlock(idtoolu_..., input{operand1: 1984135, operand2: 9343116, operation: multiply}, namecalculator, typetool_use)]把工具名和参数提取出来tool_name response.content[0].name tool_inputs response.content[0].input print(工具名称, tool_name) print(参数, tool_inputs) # 工具名称 calculator # 参数 {operand1: 1984135, operand2: 9343116, operation: multiply}然后调用本地函数operation tool_inputs[operation] operand1 tool_inputs[operand1] operand2 tool_inputs[operand2] result calculator(operation, operand1, operand2) print(结果是, result) # 结果是 18538003464660正确答案就是18538003464660和模型自己硬算的18593367726060差了 553 亿。这就是工具使用的价值模型不擅长精确计算但它擅长“决定调用什么工具、传什么参数”。这里有个细节值得注意。课程示例里只走到“本地执行并打印结果”就停了没有把tool_result塞回对话。如果你想让 Claude 用这个结果生成一句自然语言回答需要再发一次请求把工具结果作为新的 user 消息传回去response2 client.messages.create( modelclaude-3-haiku-20240307, max_tokens300, messages[ {role: user, content: 计算1984135乘以9343116。只返回结果}, {role: assistant, content: response.content}, { role: user, content: [ { type: tool_result, tool_use_id: response.content[0].id, content: str(result), } ], }, ], tools[calculator_tool], ) print(response2.content[0].text)这一步就是四步流程里的第三步和第四步。tool_use_id必须和之前ToolUseBlock的id对上否则会报参数错误。还有一个常见现象你问“祖母绿是什么颜色的”Claude 有时也会想调计算器传operand10, operand20, operationadd。这是模型“过度使用工具”。解决办法是加一句 system promptsystem你可以使用工具但只在必要时使用。如果不需要工具就正常回应加上之后同样的问题会返回stop_reasonend_turn和文本祖母绿是绿色的。不再强行调工具。5. 本篇常见错排查401、local proxy failed、reading choices 与 OAuth跑第一个工具示例时报错基本集中在几个地方。下面按真实报错对照排查。401 Unauthorized / authentication_error。最常见的原因是 Key 没设对。检查ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN是否完整有没有多余空格是不是用了控制台里新建的那个 Key。如果你在 settings.json 里写死了 Key确认 JSON 没有语法错误导致变量没被读取。还有一种情况是 Base URL 写成了https://taotoken.net/api/v1SDK 再拼一次/v1就变成/v1/v1/messages服务端可能返回 401 或 404。把 Base URL 改回https://taotoken.net/api即可。local proxy failed / connection error。这类报错通常是网络层没通。先确认ANTHROPIC_BASE_URL拼写正确没有多余斜杠。然后在终端里用 curl 直接测一下curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-3-haiku-20240307,max_tokens:50,messages:[{role:user,content:hi}]}如果 curl 能通而 Python 不通多半是 SDK 版本太旧升级pip install -U anthropic。如果 curl 也不通检查本机网络和防火墙设置。reading choices / KeyError: choices。这个报错说明你拿到的响应结构不是 Anthropic 格式可能是把 OpenAI 风格的调用混进来了。Anthropic 的响应字段是content、stop_reason、usage没有choices。确认你用的是client.messages.create而不是client.chat.completions.create并且anthropic包版本正确。OAuth / invalid_grant。如果你用 Claude Code CLI 登录过官方账号它可能缓存了 OAuth token和 API Key 冲突。检查~/.claude目录下的凭据文件或者干脆用ANTHROPIC_AUTH_TOKEN覆盖。CLI 场景下settings.json 里的env优先级高于全局配置把 Base URL 和 Key 写进去能避免走错通道。工具调用参数对不上。如果tool_inputs里缺字段或者operation传了plus检查input_schema的enum和required是否写全。模型偶尔会不按 schema 来加一句 system prompt 强调“严格按工具定义的参数格式传参”能减少这类问题。stop_reason 一直是 end_turn。说明模型没打算用工具。检查tools参数有没有真的传进去工具description是否写得太模糊。描述里明确写“performs basic arithmetic operations”比只写“calculator”更容易触发调用。6. 语义一致 CTA把第一个工具扩展成研究助手跑通 calculator 之后你可以照着同一套骨架做更实用的东西。课程里的练习是做一个研究助手用户输入主题Claude 生成一批可能的维基百科文章标题你用一个工具去真实搜索并拿到 URL最后写进 markdown 文件。工具定义长这样{ name: generate_wikipedia_reading_list, description: Search Wikipedia for a list of article titles and save real article URLs to a markdown reading list., input_schema: { type: object, properties: { research_topic: { type: string, description: The overall research topic, e.g. History of Hawaii. }, article_titles: { type: array, items: {type: string}, description: A list of possible Wikipedia article titles to search for. } }, required: [research_topic, article_titles] } }注意这里article_titles是数组类型模型会一次传多个标题进来。你的本地函数遍历这些标题用wikipedia.search找到真实页面再把标题和 URL 写进output/research_reading.md。这样即使模型虚构了标题最终列表里也只会留下真实存在的文章。如果你想把这条链路接到更长期的编码或 Agent 任务上可以看看 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它适合需要持续调用模型、反复跑工具的场景。只是想验证模型和工具调用是否正常用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 快速试一把就行。接入过程中遇到鉴权或参数问题接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有完整的字段说明API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 可以随时新建或轮换 Key。我自己的习惯是每写一个新工具先用一个“必然触发”的问题验证链路比如计算器就用大数乘法研究助手就用一个明确需要外部数据的主题。链路通了再换更模糊的提示去测模型的判断力。这样排障时能快速区分是“工具没接上”还是“模型没想用”。第一个工具跑通之后后面加工具就是复制 schema、换函数体的事真正花时间的是把description写到模型能准确理解的程度。
阅读完成 · 觉得有帮助？
