当前位置： 首页 > news >正文

Claude Code和Codex调试完全指南：日志解读、MCP排查、repomix上下文、断点技巧

news 2026/5/22 19:50:09

强烈推荐收藏！Claude Code & Codex 调试完全指南：日志解读、MCP排查、repomix上下文、断点技巧——AI编程工具问题排查手册

Claude Code 突然找不到你的文件了？Codex 卡在"正在思考"？MCP Server 莫名连接不上？这些问题网上几乎搜不到答案。本文整理了 Claude Code 和 Codex 最常见的 12 个调试场景，从日志文件位置到 MCP 协议排错，从 repomix 上下文诊断到 Token 消耗追踪，一篇文章让你从抓瞎到从容。

一、日志文件在哪里——所有问题排查的第一步

1.1 Claude Code 日志位置

# macOS~/Library/Logs/Claude/# Windows%APPDATA%\Claude\logs\# Linux~/.config/Claude/logs/
# 实时查看日志tail-f~/Library/Logs/Claude/mcp*.log# 搜索错误grep-i"error\|fail\|timeout"~/Library/Logs/Claude/*.log

关键日志文件：

文件记录什么
mcp.logMCP Server 启动/连接/调用日志
claude.logClaude Code 主进程日志
agent-*.logAgent 会话日志（每次对话一个文件）

1.2 Codex 日志位置

# macOS / Linux~/.codex/logs/# Windows%USERPROFILE%\.codex\logs\# Codex Desktop 日志# macOS: ~/Library/Logs/Codex/# Windows: %APPDATA%\Codex\logs\
# 查看最近的会话日志ls-lt~/.codex/logs/|head-5cat~/.codex/logs/session-*.log

1.3 日志级别设置

# Claude Code - 开启详细日志exportCLAUDE_LOG_LEVEL=debug claude# Codex CLI - 开启详细日志codex --log-level debug# Codex Desktop - 设置 → 开发者选项 → 日志级别 → Debug

二、MCP Server 排错——最容易出问题的地方

2.1 MCP Server 启动失败

// ~/Library/Application Support/Claude/claude_desktop_config.json{"mcpServers":{"weather":{"command":"python","args":["/Users/me/mcp/weather.py"]}}}

常见错误 1：路径不存在

# 验证ls-la/Users/me/mcp/weather.py python /Users/me/mcp/weather.py# 看能不能独立启动

常见错误 2：Python 环境问题

# Claude Desktop 用的是系统 Python，不是你虚拟环境里的# 修复：用绝对路径指定 Python{"command":"/Users/me/.pyenv/shims/python","args":["/Users/me/mcp/weather.py"]}# 或者用 uv 自动处理依赖{"command":"uv","args":["run","--with","mcp","/Users/me/mcp/weather.py"]}

常见错误 3：端口冲突

# 检查端口是否被占用lsof-i:8080# 换个端口mcp run weather.py--transportstreamable-http--port8081

2.2 调试 MCP 通信

# MCP Inspector - 官方的调试工具npx @modelcontextprotocol/inspector python weather.py# Inspector 能做：# 1. 列出所有 tools/resources/prompts# 2. 手动调用工具看返回# 3. 查看 JSON-RPC 原始消息

2.3 MCP 常见报错速查

报错原因修复
ECONNREFUSEDMCP Server 没启动或端口不对检查进程是否在运行ps aux | grep mcp
Method not foundJSON-RPC 方法名拼错检查 Server 注册的 tool name
Invalid arguments工具参数不符合 Schema检查 Function Calling 传入的参数类型
TimeoutServer 处理超时工具执行不要太久（<30s），异步处理
Not initialized没走 MCP 握手流程Server 启动后等 Client 发 initialize 请求

三、repomix / repomap 上下文诊断

3.1 Claude Code 的代码库理解机制

Claude Code 启动时会分析项目结构，生成一个repomap（代码库地图）：

# 查看 Claude Code 看到什么claude--debug# 启动时输出 repomap# 或者手动生成npx repomix# 生成 XML 上下文文件

3.2 问题：Claude Code 说"找不到文件"

症状：claude "帮我看看 src/auth/routes.py" → "I cannot find that file" 诊断： 1. 文件是不是在 .gitignore 里？repomap 默认忽略 gitignore 的文件 2. 文件是不是在 node_modules 等默认忽略目录？ 3. 是不是 Claude Code 的工作目录不对？
# 检查工作目录pwd# 确保在项目根目录# .gitignore 会影响 repomapcat.gitignore|grep"src/auth"# 如果匹配，文件被忽略了# 修复：在 CLAUDE.md 中明确告诉 Claude Code 这个文件# .claude/CLAUDE.md## 项目文件结构- src/auth/routes.py: 认证相关 API 路由

3.3 Token 上下文过大

# 查看当前 repomix 生成的上下文大小npx repomix--outputrepomix-output.xmlwc-crepomix-output.xml# 文件大小# > 如果超过 100KB，说明项目太大，需要裁剪# 裁剪策略npx repomix--include"src/**/*.py"--ignore"tests/**,docs/**"

四、Codex 专项调试

4.1 Codex CLI “一直显示正在思考”

# 原因 1：API 连接问题（国内最常见）# 诊断codex --log-level debug"hello"2>&1|grep-i"api\|timeout\|error"# 修复：配置 API 中转exportOPENAI_API_BASE="https://api.ofox.ai/v1"exportOPENAI_API_KEY="your-key"
# 原因 2：工作目录太大，上下文扫描耗时# 诊断：查看工作目录文件数find.-typef-not-path'./node_modules/*'-not-path'./.git/*'|wc-l# > 如果超过 1000 个文件，考虑用 .codexignore# 创建 .codexignore（类似 .gitignore）echo"node_modules/">>.codexignoreecho".git/">>.codexignoreecho"dist/">>.codexignore

4.2 Codex Desktop 常见问题

问题解决
打开后白屏清除缓存：rm -rf ~/Library/Caches/Codex
无法登录检查网络代理；尝试 CLI 模式
文件夹加载失败权限问题 — 检查文件夹是否可读
Thread 历史丢失检查~/.codex/threads/目录

4.3 Codex 的 Thread 管理调试

# 查看所有 Threadls-la~/.codex/threads/# 导出 Thread（备份）cp-r~/.codex/threads/ ~/Desktop/codex-backup/# 查看 Thread 的 token 用量cat~/.codex/usage.json|jq'.'# 清理旧 Thread（释放磁盘空间）find~/.codex/threads/-mtime+30-execrm-rf{}\;

五、CLAUDE.md / CODE.md 编写调试

5.1 指令太多了？测试加载效果

# 查看 Claude Code 实际加载了多少上下文claude--debug2>&1|grep"CLAUDE.md"# 如果输出太多，说明 CLAUDE.md 太长wc-c.claude/CLAUDE.md# > 建议控制在 2000 字以内

5.2 CLAUDE.md 常见反模式

# ❌ 写了 3000 字的项目文档 # ❌ 把 README 原样复制进去 # ✅ 只写 AI 需要知道的例外规则和习惯
# ✅ 精简版的 CLAUDE.md ## 这不是默认的 - 测试用 pytest，不是 unittest - API 返回格式是 {"code": 0, "data": ...}，不是直接返回 data - 数据库表名用蛇形命名，不是驼峰 ## 特别注意 - src/legacy/ 下的代码不要动 - .env 里的密钥不要在日志里打印

5.3 A/B 测试 CLAUDE.md 的效果

# 切换不同版本的 CLAUDE.mdclaude --project-dir ./# 用 .claude/CLAUDE.mdCLAUDE_CUSTOM_INSTRUCTIONS="..."claude# 临时覆盖# 对比：同一个任务，有 CLAUDE.md 和没有的结果# 1. 先不用 CLAUDE.md 执行任务# 2. 启用 CLAUDE.md 再执行同样任务# 3. 比较 Token 消耗和代码质量

六、性能与 Token 追踪

6.1 查看 Token 消耗

# Claude Code：每次对话结束后显示 Token 用量# 也可以查看日志grep"tokens"~/Library/Logs/Claude/agent-*.log# Codex：查看用量统计codex usagecat~/.codex/usage.json

6.2 请求重试与超时

# Claude Code 的超时配置（环境变量）exportCLAUDE_TIMEOUT=120000# 毫秒，默认 120 秒exportCLAUDE_MAX_RETRIES=3# 失败重试次数# Codex 的超时配置exportCODEX_TIMEOUT=60000

6.3 网络问题诊断（国内用户重点）

# 测试 API 连通性curl-Ihttps://api.anthropic.com# 如果超时 → 需要代理exportHTTPS_PROXY=http://127.0.0.1:7890 claude# 现在走代理# Claude Code 用 ofox.ai 中转（国内推荐）exportANTHROPIC_BASE_URL=https://api.ofox.ai/anthropicexportANTHROPIC_AUTH_TOKEN=your-ofox-key

七、工具/Plugin/Skill 问题排查

7.1 Skill 没加载

# 检查 Skill 目录ls-la.claude/skills/# 验证 SKILL.md 格式cat.claude/skills/my-skill/SKILL.md# 必须有 name 和 description 字段# 重新加载 Skillclaude --reload-skills

7.2 Codex Plugin 安装失败

# Plugin 安装日志cat~/.codex/logs/plugin-install.log# 手动安装codex pluginaddhttps://github.com/xxx/plugin# 如果失败，检查 GitHub 是否可访问# 查看已安装的 Plugincodex plugin list

八、调试工作流最佳实践

# 1. 复现问题 → 开最小化案例echo"用最简单的方式复现这个错误"|claude--print# 2. 查看日志 → 定位错误grep-A5"ERROR"~/Library/Logs/Claude/*.log# 3. 隔离变量 → 逐个排除# 先关掉所有 MCP Server# 再关掉所有 Skill# 再清空 CLAUDE.md# 逐步加回来，看哪个触发了问题# 4. 对比环境 → 别人的能跑我的不能？claude--versioncodex--versionnode--versionpython--version

九、总结

问题类别第一诊断步骤关键命令
启动失败看日志tail -f ~/Library/Logs/Claude/mcp*.log
MCP 连不上MCP Inspectornpx @modelcontextprotocol/inspector python server.py
找不到文件repomapclaude --debug
Token 超标裁剪上下文.codexignore/ CLAUDE.md 精简
网络超时API 连通性curl -I/ 配置中转
Skill 没加载目录+格式ls .claude/skills/+ SKILL.md 检查

AI 编程工具的调试和传统 IDE 完全不同——你看不到断点，看不到调用栈。但日志文件、MCP Inspector、repomap 是三个最重要的调试入口。遇到问题先看这三个，80% 的 bug 都能定位。

标签：#ClaudeCode #Codex #AI编程 #MCP #调试 #问题排查 #程序员必读

http://www.jsqmd.com/news/859156/

相关文章：

  • 中小团队如何通过TokenPlan套餐实现AI成本可控
  • 告别IDM试用弹窗：轻松实现永久畅用的秘密武器
  • PortSwigger SQL注入LAB7 LAB8 LAB9
  • 2026年新疆旅游深度指南：疆都国旅怎么选？零购物直营旅行社避坑与品质出行完全攻略 - 优质企业观察收录
  • 别再只当画图工具了！Flowable Modeler + Task App 实战：模拟一个请假审批流程
  • MySQL复制 slave_exec_mode 参数IDEMPOTENT 说明
  • 【文档编辑】打印小册子（一张A4纸4页内容）步骤
  • Omnizart部署终极方案：Docker、Colab、本地环境全攻略
  • 三星固件下载解密终极指南：Bifrost跨平台工具完全使用手册
  • 如何高效管理中文文献：Zotero茉莉花插件完整使用指南
  • Synopsys工具filter选项：后端设计效率倍增器实战指南
  • 告别花屏！手把手教你为STM32H743的RGB屏配置LVGL显示驱动（基于CubeIDE）
  • 通过curl命令快速测试与调试大模型API连接
  • 2026年大连全屋定制工厂怎么选？源头工厂直营vs传统品牌深度对比指南 - 企业名录优选推荐
  • 告别Keil和IAR？手把手教你用STM32CubeProgrammer + ST-Link烧录调试（附常见连接失败解决方案）
  • 保姆级教程：在K8s集群上部署Triton Inference Server服务（含TensorRT加速配置）
  • CANN/torchtitan-npu SFT指令微调指南
  • BCFtools基因组变异数据处理架构深度解析与技术实现
  • SpringbootWeb【入门】+Mysql【安装】
  • 亲测：2026年爱彼售后网络升级全流程解析——客观解析新服务网络与热线变化 - 亨得利官方服务中心
  • java springboot-vue 实验报告管理系统的设计与实现
  • 2026年新疆旅游深度指南：疆都国旅高品质直营游、研学游、党建红培全方位对标 - 优质企业观察收录
  • 博德之门3脚本扩展器：如何用代码重新定义你的冒险体验？
  • MySQL错误提示mysql Statement violates GTID consistency
  • 告别nRFgo Studio！Win10/Mac下用J-Flash给nRF52832烧写蓝牙协议栈S132的保姆级教程
  • Gmail 注册新门槛：当“验证”开始要求你主动发送短信与扫描 QR 码
  • ‌智慧校园选型避坑指南：三大关键点轻松搞定
  • Steam Economy Enhancer终极指南：快速提升Steam市场交易效率的完整教程
  • CANN/asc-devkit SIMT h2exp10函数
  • WebSocket配置IIS代理