1. Claude Code 系统提示词到底在驱动什么从 MCP 到 Agent 的调用链Claude Code 的系统提示词不是一个躺在某处的system.md文件而是一套分布式结构每个 Agent 有自己的.md提示词每个 Command 有自己的 frontmatter每个 Skill 有自己的指导文档工具权限则通过tools/allowed-tools字段传递。理解这一点是理解 Claude Code 为什么能稳定调用工具、为什么能编排多步任务的前提。它适合谁适合已经在用 Claude Code 写代码、但发现 Agent 行为不稳定、工具乱调、权限失控的开发者也适合想把 Claude Code 的提示词设计思路迁移到自己 MCP Server 上的工程师。核心检索词就是 Claude Code 系统提示词、MCP、Agent 协作机制。我实测下来Claude Code 的提示词设计遵循五条底层原则权限边界清晰Read 只读、Write 只写、Edit 只编辑、工具选择有优先级专用工具 通用工具Read/Grep/Glob Bash、权限过滤Bash(git:*)优于Bash(*)、语义清晰工具名直接映射能力、分布式提示词每个 Agent/Command 独立控制权限。这五条原则落到配置上就是三样东西Agent 的 frontmatter、MCP Server 的 tools 声明、以及 settings 里的权限白名单。下面我会从零把这套配置跑通并给出验证 Agent 调用链是否真正生效的具体动作。2. TaoToken 前置把 Claude Code 的模型出口接上Claude Code 本身是客户端它需要一个能响应 Anthropic 协议或兼容协议的模型出口。TaoToken 提供的就是这个出口同时支持模型对话、Coding Plan 和 API Key 三种接入方式。对于本地 AI 编程助手场景我建议用 API Key 方式接入因为 Claude Code 的 Agent 调用链需要稳定的 Base URL 和 Key。先到官网注册并进入控制台https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在控制台里创建一个 API Key。创建时注意两点一是 Key 只在创建时完整显示一次复制后立刻存到本地环境变量二是如果打算长期跑 Agent 任务建议直接开 Coding Plan避免按量计费在长上下文里烧得太快。拿到 Key 之后Claude Code 的接入点有两个一个是环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY另一个是~/.claude/settings.json里的env字段。我推荐后者因为 settings.json 可以跟项目一起版本化团队协作时不用每个人手动 export。这里有个容易踩的坑Claude Code 默认会去请求 Anthropic 官方域名如果你只改了 Key 没改 Base URL请求会直接失败。所以 Base URL 必须显式指向https://taotoken.net/api注意这个地址不带任何 UTM 参数UTM 只用于官网跳转归因。另外如果你用的是 Claude Code 的 OAuth 登录流程切到 API Key 模式后需要先退出登录否则客户端会优先走 OAuth 通道。这一步在后面的排障章节会详细讲。3. 可复制配置settings.json MCP Agent 三件套这一节是全文的核心所有片段都可以直接复制。先给 Claude Code 的~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Grep, Glob, Edit, Bash(git:*), Bash(npm:test), Bash(npm:run lint) ], deny: [ Bash(rm:*), Bash(curl:*) ] } }注意ANTHROPIC_MODEL这一项它对应的是 Model ID必须和 TaoToken 控制台里可用的模型名一致。Base URL、Key、Model ID 这三件套缺一不可少任何一个都会在请求阶段报错。接下来是 MCP Server 的配置。Claude Code 的 MCP 配置放在~/.claude.json或项目级.mcp.json里我用项目级配置方便跟代码一起提交{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects/demo ] } } }这个 filesystem MCP Server 会暴露read_file、write_file、list_directory、search_files等工具。Claude Code 启动时会读取这个配置把 MCP 工具注册进当前会话的工具列表。最后是 Agent 的 frontmatter。在.claude/agents/code-reviewer.md里写--- name: code-reviewer description: Use this agent for thorough code reviews. Examples: exampleReview my latest changes/example model: inherit tools: [Read, Grep, Glob] --- You are an expert code reviewer specializing in identifying bugs and security issues. **Your Core Responsibilities:** 1. Analyze code changes for potential issues 2. Check security vulnerabilities 3. Provide specific, actionable feedback **Code Review Process:** 1. Use Glob to find recently modified files 2. Use Read to examine each changed file 3. Use Grep to scan for SQL injection, XSS, hardcoded credentials 4. Generate report with file:line references **Quality Standards:** - Every issue must include severity level - Provide code snippets for context这个 Agent 的tools字段只给了三个只读工具意味着它无法写文件、无法执行命令。这就是权限边界清晰的体现审查类 Agent 天然不该有写权限。三件套配好之后Claude Code 的调用链就是settings.json 决定模型出口和全局权限.mcp.json 决定外部工具供给Agent frontmatter 决定单个 Agent 的工具子集。三者叠加才是完整的系统提示词驱动机制。4. 验证请求确认 Agent 调用链真的生效配置写完不代表生效必须验证。我一般分三步验证。第一步验证模型出口通不通。在终端里直接跑curl -s 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-20250514, max_tokens: 64, messages: [{role: user, content: reply with ok}] }如果返回 JSON 里content[0].text是ok说明 Base URL 和 Key 都对。如果返回 401说明 Key 有问题如果返回local proxy failed说明 Base URL 写错了或者网络出口被拦。第二步验证 MCP 工具注册。在 Claude Code 里输入/mcp它会列出当前会话加载的所有 MCP Server 和工具。你应该能看到filesystem下面挂着read_file、write_file等条目。如果列表为空说明.mcp.json路径不对或者npx拉包失败。第三步验证 Agent 调用链。在 Claude Code 里输入code-reviewer 帮我审查 src/auth.ts 的安全问题观察它的行为它应该先调用 Glob 找文件再调用 Read 读内容再调用 Grep 搜敏感模式最后输出带 file:line 的报告。如果它直接开始写代码说明 Agent frontmatter 没被加载Claude Code 退化成了默认 Agent。我试过在同一个项目里放两个 Agent一个只读一个可写然后用分别调用观察工具调用日志。只读 Agent 尝试写文件时会被权限层拦下报tool not allowed。这个拦截动作就是权限边界生效的直接证据。验证通过后你可以在~/.claude/logs里看到每次工具调用的记录包括工具名、参数、耗时。这份日志是排查 Agent 行为异常的第一手材料。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth排障部分我按真实报错来写每条都给触发条件和修复动作。401 Unauthorized最常见。触发条件是 Key 无效、Key 过期、或者 Key 前面多了空格。修复动作是重新在控制台生成 Key然后echo $ANTHROPIC_API_KEY | tr -d 确认没有空白字符。如果用的是 settings.json注意 JSON 里字符串不能有换行。local proxy failed这个报错通常出现在 Base URL 配置错误时。Claude Code 会尝试把请求发到一个本地代理地址如果ANTHROPIC_BASE_URL没设或者设成了http://localhost:xxxx就会报这个。修复动作是确认 Base URL 是https://taotoken.net/api注意结尾不要带/v1Claude Code 会自己拼路径。reading choices 相关报错这类报错一般出现在响应体解析阶段说明返回的 JSON 结构不符合 Anthropic 协议。触发条件通常是 Model ID 写错服务端返回了错误结构。修复动作是核对ANTHROPIC_MODEL和控制台里的模型名是否完全一致大小写和日期后缀都要对上。OAuth 冲突如果你之前用 OAuth 登录过 Claude Code切到 API Key 模式后可能仍然走 OAuth 通道表现为请求发到了官方域名。修复动作是删除~/.claude/credentials.json或对应平台的凭据文件然后重启 Claude Code。重启后它会优先读 settings.json 里的 env。MCP 工具不出现.mcp.json里command写的是npx但系统 PATH 里没有 npx或者 Node 版本太低。修复动作是which npx确认路径必要时在配置里写绝对路径比如/usr/local/bin/npx。Agent 不响应 调用Agent 文件名和name字段不一致或者文件不在.claude/agents/目录下。修复动作是确认文件名是code-reviewer.mdfrontmatter 里name: code-reviewer两者必须一致。排障时有个通用技巧把 Claude Code 的日志级别调到 debug在 settings.json 里加logLevel: debug然后看日志里实际发出的请求 URL 和 headers。90% 的接入问题都能从这一行日志里看出来。6. 把提示词设计迁移到自己的 MCP ServerClaude Code 的这套设计思路完全可以迁移到你自己的 MCP Server 上。核心是三条工具粒度要细、权限要能过滤、提示词要分布式。工具粒度细的意思是不要把「读文件」和「写文件」塞进一个工具而是拆成fs_read和fs_write。这样 Agent 在只读场景下可以只挂fs_read从工具层面杜绝误写。我在自己的 filesystem MCP 里就是这么做的12 个工具按读、写、改、执行四类分开每类有独立的权限声明。权限过滤的意思是执行类工具必须支持参数级白名单。比如exec工具不要只接受一个command字符串而是接受runtime和command两个参数然后在服务端校验command是否匹配白名单。这样即使 Agent 被提示词注入攻击也无法执行白名单外的命令。分布式提示词的意思是每个 Agent 的.md文件里都要写清楚「用哪个工具、按什么顺序、输出什么格式」。不要指望一个全局提示词能覆盖所有场景。Claude Code 的做法是每个 Agent 独立一份提示词通过tools字段控制权限这个模式可以直接抄。如果你想把模型出口也统一管理可以在 TaoToken 控制台里给不同项目建不同的 Key然后在各自的 settings.json 里引用。这样既能隔离权限又能按项目统计用量。模型对话入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Key 管理在 https://taotoken.net/api 接入文档在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个我实际在用的技巧把 Agent 的提示词当成代码来维护每次改完都跑一遍验证请求确认工具调用链没断。提示词不是写完就完事的配置它跟代码一样会腐化需要持续验证。