1. 从一次 Agent 空转说起为什么你的 Claude 只会“想”不会“做”很多人第一次把 Claude 接进终端或编辑器时都会遇到同一个尴尬模型推理写得头头是道但让它去读一个文件、跑一条命令、查一次接口它就停在原地反复输出“我建议你执行……”——这就是典型的 Agent 空转。问题不在模型智商而在于你只给了它“大脑”没给它“感官和四肢”。Claude 在 Agent 场景下的综合配置核心就三件事Agent Skill 负责定义“这类任务该怎么做”MCP 负责把外部工具接进来ReAct 负责把“思考—行动—观察”串成闭环。三者缺一Agent 就退化成聊天机器人。这篇教程会给出可复制的settings.json与 MCP 配置骨架并附上验证调用链是否真正生效的检查动作让你搭出一个能跑起来的 Claude Agent 工作流。适合谁看已经能用 Claude 做基础对话但想让它在本地项目里自主读写文件、调用外部服务的开发者以及被 ReAct 概念绕晕、想要一份能直接抄的配置骨架的人。下面所有配置都以“可跟做”为标准命令和参数我会写全踩过的坑也会标出来。2. 前置准备TaoToken 接入与 Claude Agent 运行环境2.1 为什么用 TaoToken 做接入层Claude 的 Agent 能力要落地第一步是拿到稳定的模型调用入口。TaoToken 提供统一的 API 接入兼容 Anthropic 风格的请求格式适合用来跑 Claude 系列的 Agent 工作流。你可以在官网了解整体能力实际接入时用 API 地址即可。需要提前准备的东西不多一个可用的 API Key、一个本地项目目录、以及 Node.js 18 或 Python 3.10 的运行环境取决于你选的 MCP Server 实现。Agent Skill 本身是文件系统层面的约定不依赖特定语言但 MCP Server 通常需要运行时。2.2 拿到 API Key 并确认模型可用先到控制台创建 API Key建议单独建一个用于 Agent 的 Key方便后续按调用量排查问题。创建后不要直接写进代码先放进环境变量export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类客户端它读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量对应改成export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key注意Base URL 不要带多余路径很多 404 都是因为手抖加了/v1或结尾斜杠导致的。接入细节以接入文档为准。2.3 验证模型通道是否通在写任何 Agent 配置之前先用一条最小请求确认通道没问题。用 curl 直接打curl -s $TAOTOKEN_BASE_URL/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 只回复两个字通了}] }返回里能看到content字段且有文本说明模型通道正常。这一步不通后面所有 Agent 配置都是白搭。如果报 401检查 Key报 404检查 Base URL报模型不存在换一个当前可用的模型名。3. 可复制配置settings.json 与 MCP 骨架3.1 settings.json 的完整结构Claude 的 Agent 行为大量依赖配置文件。下面这份settings.json放在项目根目录的.claude/下用户级则放~/.claude/是我实测能跑通 ReAct 循环的最小骨架{ model: claude-sonnet-4-20250514, permissions: { allow: [ Read, Glob, Grep, Bash(npm run *), Bash(git status), mcp__filesystem__read_file, mcp__filesystem__list_directory ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/demo ] }, fetch: { command: npx, args: [-y, modelcontextprotocol/server-fetch] } }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }几个关键点解释一下。permissions.allow是白名单Agent 只能调用这里列出的工具这是防止它乱跑的第一道闸。mcpServers里每个条目就是一个 MCP Servercommand加args决定怎么启动它。filesystem 那个参数是允许访问的目录务必换成你自己的绝对路径写错会导致 Agent 读不到文件却报“权限拒绝”很难查。3.2 MCP 配置骨架与工具命名规则MCP 工具在 Claude 里的命名规则是mcp__server名__工具名。比如上面 filesystem 服务暴露的read_file在权限里就要写成mcp__filesystem__read_file。这个命名规则是排查“工具明明配了却调不到”的第一检查项。如果你想接更多服务往mcpServers里加就行。下面是一个接数据库查询服务的骨架仅示意结构生产库不要直连{ mcpServers: { sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, ./data/dev.db] } } }注意MCP Server 启动失败时Claude 通常只会提示“工具不可用”不会告诉你具体错在哪。排查方法是把command和args单独在终端跑一遍看它自己报什么错。3.3 Agent Skill 的文件结构Agent Skill 解决的是“重复性任务不用反复写提示词”。它在文件系统里就是一个文件夹核心是SKILL.md.claude/skills/ └── daily-report/ ├── SKILL.md ├── reference/ │ └── format-guide.md └── scripts/ └── collect.pySKILL.md里写名称、描述和格式要求描述要写得能被语义匹配到否则自动调用不会触发。一个最小示例--- name: daily-report description: 根据当天 git 提交记录生成固定格式的日报 --- ## 执行步骤 1. 调用 Bash(git log --sincemidnight) 获取当天提交 2. 按 reference/format-guide.md 的模板整理 3. 输出到 reports/YYYY-MM-DD.md这里体现了渐进式披露的思路SKILL.md只放流程详细格式丢到reference/里按需读取脚本丢到scripts/里本地执行。这样常驻上下文的部分极小几百个 Skill 也不会把窗口撑爆。4. 验证 ReAct 调用链是否生效4.1 用一条任务观察 Thought-Action-Observation配置写完重启 Claude 客户端然后给它一个必须调用工具才能完成的任务比如“读取当前目录下的 package.json告诉我项目名和依赖数量。” 如果 ReAct 循环生效你会看到它先输出一段思考判断需要读文件然后发起工具调用拿到结果后再输出最终答案。判断是否真的走了 MCP而不是模型凭记忆瞎编看两点一是界面上有没有工具调用的确认或日志二是答案里的依赖数量是否和文件实际一致。改一下package.json里的依赖数再问一次如果数字跟着变说明它真的读了文件。4.2 检查 Skill 是否被命中手动触发 Skill 最稳输入/daily-report加需求。如果自动调用不触发八成是description写得太泛和用户请求的语义匹配不上。把描述改得更贴近真实说法比如加上“日报”“工作总结”这类词命中率会明显上升。4.3 确认调用链的日志位置MCP Server 的日志默认走 stderrClaude 客户端一般会把它收进自己的日志里。想单独看可以在配置里给 Server 加环境变量把日志落盘{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/dir], env: { LOG_FILE: ./logs/mcp-filesystem.log } } } }日志里能看到每次tools/call的入参和返回这是验证调用链最硬的证据。如果日志里只有initialize没有tools/call说明模型压根没发起工具调用问题在提示词或权限不在 MCP。5. 本篇常见错排查5.1 工具调不到先查命名和权限最常见的三类报错tool not found、permission denied、server not running。tool not found基本是命名写错回去核对mcp__server__tool三段式。permission denied是白名单没放行把对应工具加进permissions.allow。server not running是 MCP Server 启动失败单独跑一遍启动命令看报错。5.2 上下文被撑爆Skill 写太胖如果 Agent 跑几轮就开始丢上下文、回答变糊检查SKILL.md是不是写了几百行。核心文件控制在 500 行以内把参考资料挪到reference/脚本挪到scripts/。渐进式披露的意义就是让不用的东西别进窗口你把它全塞进主文件等于白设计。5.3 ReAct 循环卡死权限太松或太紧权限给太松Agent 可能反复尝试危险操作然后被拒陷入重试给太紧它发现没有可用工具直接放弃行动只输出建议。平衡点是把完成任务必需的工具精确放行危险操作明确 deny。deny 列表比 allow 列表更重要它是最后一道保险。5.4 模型名或 Base URL 写错导致静默失败有些客户端在模型名错误时不会报错而是回退到默认模型导致你以为 Agent 配置生效了其实跑的是另一个模型。验证方法就是前面那条 curl确认模型名和通道都正确再回到客户端配置里逐字核对。6. 把工作流跑顺之后Agent Skill 和 MCP 的关系用一句话说清Skill 定义“做什么”MCP 解决“怎么接”ReAct 负责“怎么串”。三者配齐Claude 才从“会回答”变成“会执行”。配置这件事没有一步到位先跑通最小闭环再按需加 Skill、加 MCP Server比一上来堆一堆配置然后不知道哪出错要高效得多。如果你还在调模型通道先去模型对话把请求跑通如果准备长期在项目里跑编码类 AgentCoding Plan 更适合按量使用接入过程中遇到权限或工具命名问题直接翻接入文档对照排查。配置骨架已经给你了剩下的就是把它改成你自己的路径和 Key然后让 Agent 真正动起来。
1. 从一次 Agent 空转说起为什么你的 Claude 只会“想”不会“做”很多人第一次把 Claude 接进终端或编辑器时都会遇到同一个尴尬模型推理写得头头是道但让它去读一个文件、跑一条命令、查一次接口它就停在原地反复输出“我建议你执行……”——这就是典型的 Agent 空转。问题不在模型智商而在于你只给了它“大脑”没给它“感官和四肢”。Claude 在 Agent 场景下的综合配置核心就三件事Agent Skill 负责定义“这类任务该怎么做”MCP 负责把外部工具接进来ReAct 负责把“思考—行动—观察”串成闭环。三者缺一Agent 就退化成聊天机器人。这篇教程会给出可复制的settings.json与 MCP 配置骨架并附上验证调用链是否真正生效的检查动作让你搭出一个能跑起来的 Claude Agent 工作流。适合谁看已经能用 Claude 做基础对话但想让它在本地项目里自主读写文件、调用外部服务的开发者以及被 ReAct 概念绕晕、想要一份能直接抄的配置骨架的人。下面所有配置都以“可跟做”为标准命令和参数我会写全踩过的坑也会标出来。2. 前置准备TaoToken 接入与 Claude Agent 运行环境2.1 为什么用 TaoToken 做接入层Claude 的 Agent 能力要落地第一步是拿到稳定的模型调用入口。TaoToken 提供统一的 API 接入兼容 Anthropic 风格的请求格式适合用来跑 Claude 系列的 Agent 工作流。你可以在官网了解整体能力实际接入时用 API 地址即可。需要提前准备的东西不多一个可用的 API Key、一个本地项目目录、以及 Node.js 18 或 Python 3.10 的运行环境取决于你选的 MCP Server 实现。Agent Skill 本身是文件系统层面的约定不依赖特定语言但 MCP Server 通常需要运行时。2.2 拿到 API Key 并确认模型可用先到控制台创建 API Key建议单独建一个用于 Agent 的 Key方便后续按调用量排查问题。创建后不要直接写进代码先放进环境变量export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类客户端它读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量对应改成export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key注意Base URL 不要带多余路径很多 404 都是因为手抖加了/v1或结尾斜杠导致的。接入细节以接入文档为准。2.3 验证模型通道是否通在写任何 Agent 配置之前先用一条最小请求确认通道没问题。用 curl 直接打curl -s $TAOTOKEN_BASE_URL/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 只回复两个字通了}] }返回里能看到content字段且有文本说明模型通道正常。这一步不通后面所有 Agent 配置都是白搭。如果报 401检查 Key报 404检查 Base URL报模型不存在换一个当前可用的模型名。3. 可复制配置settings.json 与 MCP 骨架3.1 settings.json 的完整结构Claude 的 Agent 行为大量依赖配置文件。下面这份settings.json放在项目根目录的.claude/下用户级则放~/.claude/是我实测能跑通 ReAct 循环的最小骨架{ model: claude-sonnet-4-20250514, permissions: { allow: [ Read, Glob, Grep, Bash(npm run *), Bash(git status), mcp__filesystem__read_file, mcp__filesystem__list_directory ], deny: [ Bash(rm -rf *), Bash(curl *) ] }, mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/demo ] }, fetch: { command: npx, args: [-y, modelcontextprotocol/server-fetch] } }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key } }几个关键点解释一下。permissions.allow是白名单Agent 只能调用这里列出的工具这是防止它乱跑的第一道闸。mcpServers里每个条目就是一个 MCP Servercommand加args决定怎么启动它。filesystem 那个参数是允许访问的目录务必换成你自己的绝对路径写错会导致 Agent 读不到文件却报“权限拒绝”很难查。3.2 MCP 配置骨架与工具命名规则MCP 工具在 Claude 里的命名规则是mcp__server名__工具名。比如上面 filesystem 服务暴露的read_file在权限里就要写成mcp__filesystem__read_file。这个命名规则是排查“工具明明配了却调不到”的第一检查项。如果你想接更多服务往mcpServers里加就行。下面是一个接数据库查询服务的骨架仅示意结构生产库不要直连{ mcpServers: { sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, ./data/dev.db] } } }注意MCP Server 启动失败时Claude 通常只会提示“工具不可用”不会告诉你具体错在哪。排查方法是把command和args单独在终端跑一遍看它自己报什么错。3.3 Agent Skill 的文件结构Agent Skill 解决的是“重复性任务不用反复写提示词”。它在文件系统里就是一个文件夹核心是SKILL.md.claude/skills/ └── daily-report/ ├── SKILL.md ├── reference/ │ └── format-guide.md └── scripts/ └── collect.pySKILL.md里写名称、描述和格式要求描述要写得能被语义匹配到否则自动调用不会触发。一个最小示例--- name: daily-report description: 根据当天 git 提交记录生成固定格式的日报 --- ## 执行步骤 1. 调用 Bash(git log --sincemidnight) 获取当天提交 2. 按 reference/format-guide.md 的模板整理 3. 输出到 reports/YYYY-MM-DD.md这里体现了渐进式披露的思路SKILL.md只放流程详细格式丢到reference/里按需读取脚本丢到scripts/里本地执行。这样常驻上下文的部分极小几百个 Skill 也不会把窗口撑爆。4. 验证 ReAct 调用链是否生效4.1 用一条任务观察 Thought-Action-Observation配置写完重启 Claude 客户端然后给它一个必须调用工具才能完成的任务比如“读取当前目录下的 package.json告诉我项目名和依赖数量。” 如果 ReAct 循环生效你会看到它先输出一段思考判断需要读文件然后发起工具调用拿到结果后再输出最终答案。判断是否真的走了 MCP而不是模型凭记忆瞎编看两点一是界面上有没有工具调用的确认或日志二是答案里的依赖数量是否和文件实际一致。改一下package.json里的依赖数再问一次如果数字跟着变说明它真的读了文件。4.2 检查 Skill 是否被命中手动触发 Skill 最稳输入/daily-report加需求。如果自动调用不触发八成是description写得太泛和用户请求的语义匹配不上。把描述改得更贴近真实说法比如加上“日报”“工作总结”这类词命中率会明显上升。4.3 确认调用链的日志位置MCP Server 的日志默认走 stderrClaude 客户端一般会把它收进自己的日志里。想单独看可以在配置里给 Server 加环境变量把日志落盘{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path/to/dir], env: { LOG_FILE: ./logs/mcp-filesystem.log } } } }日志里能看到每次tools/call的入参和返回这是验证调用链最硬的证据。如果日志里只有initialize没有tools/call说明模型压根没发起工具调用问题在提示词或权限不在 MCP。5. 本篇常见错排查5.1 工具调不到先查命名和权限最常见的三类报错tool not found、permission denied、server not running。tool not found基本是命名写错回去核对mcp__server__tool三段式。permission denied是白名单没放行把对应工具加进permissions.allow。server not running是 MCP Server 启动失败单独跑一遍启动命令看报错。5.2 上下文被撑爆Skill 写太胖如果 Agent 跑几轮就开始丢上下文、回答变糊检查SKILL.md是不是写了几百行。核心文件控制在 500 行以内把参考资料挪到reference/脚本挪到scripts/。渐进式披露的意义就是让不用的东西别进窗口你把它全塞进主文件等于白设计。5.3 ReAct 循环卡死权限太松或太紧权限给太松Agent 可能反复尝试危险操作然后被拒陷入重试给太紧它发现没有可用工具直接放弃行动只输出建议。平衡点是把完成任务必需的工具精确放行危险操作明确 deny。deny 列表比 allow 列表更重要它是最后一道保险。5.4 模型名或 Base URL 写错导致静默失败有些客户端在模型名错误时不会报错而是回退到默认模型导致你以为 Agent 配置生效了其实跑的是另一个模型。验证方法就是前面那条 curl确认模型名和通道都正确再回到客户端配置里逐字核对。6. 把工作流跑顺之后Agent Skill 和 MCP 的关系用一句话说清Skill 定义“做什么”MCP 解决“怎么接”ReAct 负责“怎么串”。三者配齐Claude 才从“会回答”变成“会执行”。配置这件事没有一步到位先跑通最小闭环再按需加 Skill、加 MCP Server比一上来堆一堆配置然后不知道哪出错要高效得多。如果你还在调模型通道先去模型对话把请求跑通如果准备长期在项目里跑编码类 AgentCoding Plan 更适合按量使用接入过程中遇到权限或工具命名问题直接翻接入文档对照排查。配置骨架已经给你了剩下的就是把它改成你自己的路径和 Key然后让 Agent 真正动起来。
