1. 先搞清楚Claude Code Mods 到底是什么1.1 Claude Code 的根基终端优先与可扩展性如果过去几个月你关注过 AI 编程工具大概率见过 Claude Code 这个名字。它是跑在终端里的命令行智能体直接在终端里聊需求、读写文件、执行命令、跑测试。和普通聊天界面最大的区别在于它生来就是一副“干活的工具”的样子而不是一个对话框。Claude Code 默认提供了一批核心能力文件读写、搜索、命令行执行、任务拆解但默认能力永远是“通用”的。你想让它懂你团队的发布流程、让它画一个内部监控面板、让它调用公司内部 API就必须给它扩展能力。Mods就是 Claude Code 在扩展性上给出的答案。先别被“Mods”这个词吓到。Mod 就是 Module 的缩写你可以把它理解成“给 Claude 装的外挂模块”。一个 Mod 可以是一段指令、一个脚本、一组工具描述甚至是一整套终端 UI 渲染逻辑。它做的事情很纯粹让 Claude Code 从一个“通用编程助手”变成一个“懂你场景的专用助手”。我的理解是官方用 Mods 这个概念把过去散落在各个角落的自定义技能、快捷指令、工具接入方式收拢成一个统一的能力包。你不需要记住一堆互相打架的术语只需要知道以后给 Claude 加东西大概率都会落到 Mods 上。1.2 Mods 解决的三个核心痛点先说痛点一默认工具不够定制。Claude Code 虽然能执行 bash但直接让它在终端里跑一段脚本时你不一定能控制脚本的行为边界。你可能希望它执行一条固定的命令不希望它自由发挥参数更不希望它把整段 shell 塞进来随机试探。Mods 可以挂载预定义的脚本作为工具把脚本名、参数、输出格式都提前定义好Claude 调用起来是可控的。它能看到的信息只有你写好的工具说明它是在你的边界内干活而不是在无限可能的 shell 里探索。痛点二是经验没法沉淀。团队里每个人都在让 Claude 重复处理同一件事比如把日报转成固定格式、查看服务器状态、生成 Release Notes。这些东西单独聊不是不行但每次都重复写一大段描述太浪费。Mods 把“固定套路”封装成可复用的模块别人可以拷贝、可以分享、可以放进版本管理。我实际用下来这个“沉淀”的价值比预想中还要大因为新同学拿到项目后不用问“我们平时是怎么让 AI 干这活的”看一眼 mods 目录就懂了。痛点三是终端输出反人类。Claude Code 默认是纯文本输出信息长了就是一大片流水账看几屏就眼花。Mods 能驱动的另一个方向就是让 Claude 在终端里输出结构化界面色块、边框、进度条、实时刷新的仪表盘。这是“在终端画界面”这句话的由来也是我觉得 Mods 最性感的一部分。相比在浏览器里打开一个 DashBoard直接在终端里按需渲染一个临时面板成本低得多也更符合命令行工作的直觉。1.3 Mods 和插件、Skills、Slash Command 的区别很多刚接触生态的人会问Claude Code 不是已经有插件、Skills、斜杠命令了吗再搞个 Mods 是不是重复我自己的理解是这些概念背后的核心思路是一致的只是覆盖的层次不太一样。拿我熟悉的领域打个比方MCP 更像是给所有 AI 客户端共享的“USB 协议”它负责定义外部工具怎么连进来Slash Command 是快捷指令入口Skills 更偏知识注入给 Claude 喂一段背景知识让它学会某个场景的做事方式。而 Mods 在我的使用中会更像一个把上面这些能力打包好的“能力包”——一个 Mod 可以同时包含指令模板、外部脚本、UI 渲染逻辑。不过这里我不做太严格的学术定义因为不同版本里官方对这些概念的边界也在微调文档用词有时候会混着来。我的建议是先用起来再看它属于哪一类。你想给 Claude 加一个工具那就按 Mods 的方式创建一个描述文件加一个脚本你想让它在终端里画界面那就写一个会输出 ANSI 转义序列的工具脚本。用熟了之后这些概念之间到底剩多少差别其实不太影响你干活。2. 给 Claude 加工具Mods 的核心玩法2.1 Claude Code 本来就能执行终端命令为什么还要加工具Claude Code 自带 Bash 工具你直接跟它说“帮我看看内存占用”它就能执行相关命令。那加工具的意义在哪核心是三个词封装、约束、复用。直接让 Claude 随意跑命令虽然方便但你对它的控制力是弱的。你希望它执行一条固定的命令不希望在参数上自由发挥更不希望它在出错后自己试出一堆乱七八糟的 shell 片段。挂载一个 Mod 工具后Claude 能看到的只有你定义好的函数名、参数说明、返回格式它是在你有边界的沙箱里调用脚本而不是在一个无限可能的 shell 里探索。从实际体验来说把高频脚本封装成 Mod 还有一个隐藏好处你不需要在每轮对话中重新描述背景。直接说“用我的 sysinfo 工具看下这台机器的状态”Claude 就知道该调哪个脚本输出什么格式。时间久了你会发现这套东西用起来很像给命令行工具写 man pageAI 拿着说明文档调用你拿着结果看板。而且工具返回值如果是结构化 JSONClaude 还能自己决定要不要二次处理比如把数字转成“已用 12.4G / 总共 32G”这样的自然语言读起来舒服很多。2.2 写第一个 Mod一个系统信息查询工具先聊文件组织方式。项目级的 Mod 通常放在.claude/mods/目录下用户级的放在~/.claude/mods/下每个 Mod 是一个目录里面至少有一个描述文件加一个可选的可执行脚本。描述文件用 Markdown 写头部用 YAML frontmatter 声明元信息。下面这个例子是一个系统信息查询工具目录结构大致是这样.claude/mods/sysinfo/ ├── mod.md └── scripts/ └── sysinfo.py描述文件mod.md的内容可以长这样--- name: sysinfo description: 查询当前系统的CPU、内存、磁盘、网络状态返回结构化JSON tool: command: python3 scripts/sysinfo.py args: mode: desc: all/cpu/mem/disk/net 四选一 default: all --- 当用户想了解服务器或本机资源使用情况时使用 sysinfo 工具。 输出必须是 JSON字段固定为 cpu_usage, mem_total, mem_used, disk_total, disk_used。配套的sysinfo.py可以写成一段非常精简的 psutil 调用把结果print(json.dumps(data))打出来。这里的关键在于描述文件里的description和name是 Claude 决定“什么时候调用”的主要依据。写得太笼统Claude 不知道什么时候用它写得太复杂又容易喧宾夺主。我的写法是“什么时候用 输出什么格式 边界是什么”三行说清楚剩下的让脚本自己处理。2.3 加载与管理的几个高频操作查看当前已加载的 Mods在 Claude Code 里输入对应的列表命令把当前会话可用的 Mod 名称和描述列出来。启用或停用某个 Mod停用最粗暴的做法是把目录名加个后缀或者删掉描述文件重新进入会话后就不加载了。项目级与用户级的取舍项目级适合“这个仓库独有的脚本”用户级适合“我无论在哪都要用的工具”。我的建议是新写的 Mod 先放项目级。放项目级不影响全局环境出错了直接删目录就行等你在几个项目里都用顺手了再提升到用户级。这里还有个细节改完文件后Claude Code 不会热加载一般需要退出当前会话重新进入。你要是发现 Mod 一直没生效先别急着改脚本退出重开一次再说。2.4 实操心得工具粒度别太大这是我踩过最大的坑。初学者很容易做一个“万能工具 Mod”一个脚本里又是发请求、又是写文件、又是调接口最后发现问题反而更复杂因为 Claude 不太会主动用这种大而全的工具。我的经验是拆小每个 Mod 干一件事输入输出都是简单 JSON。宁可让 Claude 连续调用三次小工具也别让它在一个黑盒脚本里折腾半天。小工具有一个额外优势就是你调试的时候也轻松脚本出问题一眼就能看出是哪一步。3. 在终端画界面Mods 的终端 UI 路径3.1 终端里的界面其实是字符流一说“在终端里画界面”很多人第一反应是图片。不是的。终端 UI 的本质是字符流加控制字符。比如\033[2J是清屏\033[1;31m是把后面文字变成红色\033[H是把光标移到左上角。这些 ANSI 转义序列组合起来就能在终端里画边框、画表格、画色块、画进度条。命令行工具里那些花花绿绿的日志、表格、进度动画底层全是这套东西。那 Claude Code 怎么利用这套东西直接让 Claude 输出 ANSI 码有用但不够因为实时刷新的界面需要持续输出和清屏纯靠模型逐字输出太慢。更合理的方案是让 Mod 生成一个渲染脚本由脚本负责真正的界面刷新。这就是“Mod 画界面”和“人肉敲 ANSI”之间的分界线。Claude 只负责在最合适的时机启动脚本脚本一旦跑起来就和模型无关了用户看到的是一个活的终端面板。3.2 用 Mod 画仪表盘的原理一个能画界面的 Mod通常包含三段逻辑采集数据、组装画面、刷新输出。采集数据由脚本完成组装画面就是把数据拼成一行行带 ANSI 颜色的文本刷新输出用循环加time.sleep来实现。Mod 描述文件告诉 Claude 什么时候该跑这个脚本以及脚本运行期间用户应该看到什么。举个例子一个展示本机 CPU 和内存的仪表盘 Mod。描述文件里可以写“当用户要求查看资源面板或实时状态时运行 dashboard.py脚本会持续运行直到被 CtrlC 打断”。脚本内部每秒采集一次数据用 ANSI 转义序列把画面重绘一遍。Claude 看到用户说“来个实时面板”就自动调用这个 Mod。如果你平时只是想要一次性结果不想让它持续跑Mod 描述里也要写清楚“用户要求持续显示时运行”否则 Claude 一看到资源查询就给你弹个无限刷新的面板反而烦。3.3 终端复用与界面刷新tmux 是神器这里就要聊到终端复用了。我在 macOS 和 Linux 上用得最多的组合是 tmux Claude Code。为什么需要终端复用因为 Claude Code 占用一个终端会话实时仪表盘要占用另一个输出窗口普通终端窗口做不到“同一个屏幕里既有 AI 对话又有动态面板”。tmux 可以把你的一块屏幕切成多个 pane一个 pane 跑 Claude Code另一个 pane 跑仪表盘脚本互不干扰。具体操作是这样先用tmux new -s work开一个会话然后tmux split-window -h左右分屏左边跑 Claude Code右边跑 dashboard 脚本。切换焦点用CtrlB加方向键。如果你更喜欢图形化终端Tabby 这类现代终端工具对 tmux 的集成体验也不错字体渲染和配色都更舒服当作日常终端用没有任何问题。我自己在 Windows 上测试时Tabby 的 ANSI 支持比系统自带的好不少至少渲染状态面板不会乱。3.4 实操演示一个实时状态面板的最小实现下面是一个极简但能跑的仪表盘脚本它只做一件事每隔一秒重绘一次显示当前时间、CPU 占用、内存占用。代码里的核心就是 ANSI 转义#!/usr/bin/env python3 import sys import time import psutil def clear(): sys.stdout.write(\033[2J\033[H) def bar(pct, width20): filled int(pct * width) return [ # * filled - * (width - filled) ] while True: clear() cpu psutil.cpu_percent(interval0.5) / 100 mem psutil.virtual_memory().percent / 100 now time.strftime(%Y-%m-%d %H:%M:%S) print(f\033[1;36m 实时状态面板 {now}\033[0m) print(fCPU {bar(cpu)} {cpu * 100:.1f}%) print(fMEM {bar(mem)} {mem * 100:.1f}%) time.sleep(1)跑起来后终端会不断刷新同一个画面。把它嵌进 Mod 描述文件后Claude 就知道“用户要看状态”时执行它。需要注意两点脚本里要处理KeyboardInterrupt保证 CtrlC 能干净退出不然终端会残留一大堆控制字符如果终端宽度小于 40 字符界面就会错乱建议至少开 60 字符宽度。这里我习惯把“最小终端宽度要求”写进 Mod 描述里Claude 启动前会提醒用户把终端拉宽。4. 实操过程从安装到第一个 Mod 全流程4.1 Claude Code 的安装与配置Claude Code 最常见的是通过 npm 全局安装。前提是机器上有 Node.js版本不要太老我建议至少 18 以上。安装命令很简单npm install -g anthropic-ai/claude-code claude --versionmacOS 和 Linux 直接装就行装完先跑claude --version确认版本号能正常输出别急着直接开聊。Windows 的话我建议在 Git Bash 或 WSL 里跑原生 CMD 偶尔会遇到 ANSI 支持不完整的问题并不是不能用但像 Mods 这种依赖终端渲染的功能体验会差不少。Ubuntu 这类 Linux 发行版也是一样的思路先确认 node 和 npm 的版本都正常再一步步来别一上来就全局安装装完发现平台不兼容又得回头折腾。装完之后首次启动会要求登录走官方登录流程并配置 API Key。这一步属于环境前置条件跟着官方文档的引导操作就行。如果登录环节卡住先确认网络和 API Key 状态是否正常通常都是这两个环境变量的问题。登录成功后claude命令就能直接进入交互式会话。4.2 在 VS Code 里配置 Claude Code很多人其实不愿意完全脱离 IDE 干活。Claude Code 有官方 VS Code 扩展也可以在 VS Code 的集成终端里直接跑claude。我的习惯是日常开发用 VS Code 集成终端切一个面板跑 Claude Code看代码用编辑器对话在终端里这样两边切换顺畅。集成终端的好处是上下文切换快Claude 改完文件后编辑器会实时刷新不用来回切窗口。这里有一个配置细节容易被忽略VS Code 集成终端默认的 shell 在 Windows 上往往是 PowerShell如果不改部分命令的交互体验会不一致。我建议在设置里搜terminal.integrated.defaultProfile.windows把默认终端切换成 Git Bash 或 WSL这样 Claude Code 的行为表现得更接近 Linux 环境。macOS 用户一般不用管默认 zsh 就行。4.3 创建第一个 Mod 的完整步骤我以“给 Claude 加一个媒体文件信息查询工具”为例把完整步骤走一遍。第一步在项目根目录建目录mkdir -p .claude/mods/media-info/scripts第二步在media-info目录里创建描述文件mod.md写上元信息和工具说明。第三步写脚本scripts/media_info.py接收文件路径参数返回 JSON。第四步启动 Claude Code让 Claude 调用一次这个工具。如果描述文件写得没问题它会正确调用并返回结果。验证阶段我会故意问一句“这个 mp4 文件的编码是什么”如果 Claude 调用的是 media-info 工具说明 Mod 挂载成功。如果它还在尝试猜文件名或者自己拼命令多半是 description 没写清楚。这时候回去读一下描述文件里的触发条件把“媒体文件”“编码信息”“音频流”这类关键词补进去再重新加载一次。整个流程跑通之后你会明显感觉到Claude 不是“万金油”而是真正认识你环境里的工具。4.4 关于接入第三方模型服务的思路Claude Code 默认是配合 Anthropic 官方模型使用。但很多开发者在实操中发现自己手头有 DeepSeek 等模型的 API Key或者希望把调用成本降下来所以想让 Claude Code 指向兼容模型的接口。这套操作的本质是改模型接口地址。Claude Code 支持通过环境变量覆盖 API 服务地址你可以把 Base URL 指向兼容服务再把 API Key 换成对应服务的 Key。需要注意不同模型对工具调用的支持程度不一样如果 Mods 里大量依赖工具调用和结构化输出换成第三方模型后可能表现不稳定。我的建议是先跑通一个最基础的对话再逐步测试工具类 Mod最后才上复杂 UI 类 Mod。另外一个重要提醒不管接哪家模型API Key 都要小心保管不要写进仓库里。.claude/目录如果在 Git 仓库内建议把含密钥的配置文件路径加到.gitignore该忽略的别漏。5. 常见问题与排查技巧实录5.1 安装不上、命令找不到这类问题八成出在 Node 环境和 PATH 上。先node -v看版本低于 18 建议先升级。npm 全局安装后如果claude命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Windows 上尤其常见npm 的全局目录在%APPDATA%\npm确认这个目录在环境变量 PATH 中。如果在 Git Bash 里跑 npm 全局安装但 Git Bash 没继承 Windows 的 PATH一样会找不到命令这时候手动把 npm 全局目录加到 Git Bash 的.bashrc里就行。5.2 Mod 加载不生效最常见原因有三个目录位置不对、描述文件格式不对、Claude Code 没重启。项目级 Mod 必须放在.claude/mods/下用户级放在~/.claude/mods/下路径错了自然加载不了。frontmatter 解析失败一般是因为 YAML 里用了 tab 而不是空格或者description字段里有特殊字符没转义。改完之后一定要退出当前 Claude Code 会话再重新进入因为它不会热加载。这一点我吃过好几次亏——改完描述文件立刻问 Claude它还是旧行为但实际上文件已经写对了重开就能用。5.3 终端界面渲染错乱画面乱跳、边框断裂、闪烁不停通常是这几个问题终端宽度不够、换行符不一致、终端不支持某些 ANSI。最简单的排查办法是把TERM环境变量设置成xterm-256color把脚本里的换行统一成\n然后用 Tabby 这类支持完整 ANSI 的终端跑一次。如果还乱优先怀疑是不是脚本里同时用了clear命令和 ANSI 清屏序列重复清屏会导致闪烁。另外中文在终端里的宽度是按双字节计算的如果面板里有中文字符边框对齐会受影响我一般直接用wcwidth处理或者干脆先上英文标签。5.4 权限与安全问题Mods 能执行外部脚本安全问题就变得非常重要。给 Mod 脚本传参数时Claude 会根据用户描述填充参数这意味着“文件路径”“URL”这类参数存在注入风险。我的防御习惯是脚本里只接受白名单参数路径必须经过realpath校验不直接拼接 shell 命令。讲个具体例子我之前写过一个读取文件片段的小工具一开始用os.system(head -n 1 path)结果路径里带空格就崩后来改成subprocess.run加列表传参再对路径做存在性检查问题一次解决。另一个细节是密钥管理除非是本地开发工具否则不要让 Mod 脚本读取环境变量里的密钥再输出给模型。你希望模型调用工具但不希望它把密钥内容带走。这里我还想强调一句Mods 是给 Claude 增加能力的但能力越强越要注意边界。给每个 Mod 最小化权限比事后补救安全得多。我用一张速查表总结一下高频问题现象常见原因解决办法claude命令不存在Node 版本低或 PATH 不对升级 Node检查 npm bin 目录Mod 描述文件不生效路径错或 YAML 语法错对照示例检查 frontmatterClaude 不调用 Moddescription 写得太模糊写清触发场景和输出格式终端画面闪烁重复清屏或 sleep 太短单次清屏sleep 调大到 1sUI 出现乱码终端不支持中文宽度加宽终端改用英文标签脚本被注入参数直接拼接 shell 命令用 subprocess 列表传参并做路径校验6. 我这段时间的实战体会踩过不少坑之后我最大的体会是Mods 的粒度要小、描述要准、边界要清。别想着一个 Mod 干十件事也别把一个工具的 description 写得像一篇论文。你把触发场景写得越具体Claude 就越知道什么时候该用它。另一个心得是“工具和界面分开做”数据采集和 UI 渲染尽量拆成两个脚本因为 UI 脚本会持续运行一旦卡住你还能用另一个脚本单独排查。后面我打算把自己常用的发版检查、日志捞取、工作归档都做成一个个独立 Mod 沉淀下来。等到你手边的 Mods 多了你会发现与其说是给 Claude 装外挂不如说是在给团队积累一本“可执行的私有手册”。希望这篇分享能帮你绕过我踩过的坑。
Claude Code Mods全攻略：从工具封装到终端UI实战
1. 先搞清楚Claude Code Mods 到底是什么1.1 Claude Code 的根基终端优先与可扩展性如果过去几个月你关注过 AI 编程工具大概率见过 Claude Code 这个名字。它是跑在终端里的命令行智能体直接在终端里聊需求、读写文件、执行命令、跑测试。和普通聊天界面最大的区别在于它生来就是一副“干活的工具”的样子而不是一个对话框。Claude Code 默认提供了一批核心能力文件读写、搜索、命令行执行、任务拆解但默认能力永远是“通用”的。你想让它懂你团队的发布流程、让它画一个内部监控面板、让它调用公司内部 API就必须给它扩展能力。Mods就是 Claude Code 在扩展性上给出的答案。先别被“Mods”这个词吓到。Mod 就是 Module 的缩写你可以把它理解成“给 Claude 装的外挂模块”。一个 Mod 可以是一段指令、一个脚本、一组工具描述甚至是一整套终端 UI 渲染逻辑。它做的事情很纯粹让 Claude Code 从一个“通用编程助手”变成一个“懂你场景的专用助手”。我的理解是官方用 Mods 这个概念把过去散落在各个角落的自定义技能、快捷指令、工具接入方式收拢成一个统一的能力包。你不需要记住一堆互相打架的术语只需要知道以后给 Claude 加东西大概率都会落到 Mods 上。1.2 Mods 解决的三个核心痛点先说痛点一默认工具不够定制。Claude Code 虽然能执行 bash但直接让它在终端里跑一段脚本时你不一定能控制脚本的行为边界。你可能希望它执行一条固定的命令不希望它自由发挥参数更不希望它把整段 shell 塞进来随机试探。Mods 可以挂载预定义的脚本作为工具把脚本名、参数、输出格式都提前定义好Claude 调用起来是可控的。它能看到的信息只有你写好的工具说明它是在你的边界内干活而不是在无限可能的 shell 里探索。痛点二是经验没法沉淀。团队里每个人都在让 Claude 重复处理同一件事比如把日报转成固定格式、查看服务器状态、生成 Release Notes。这些东西单独聊不是不行但每次都重复写一大段描述太浪费。Mods 把“固定套路”封装成可复用的模块别人可以拷贝、可以分享、可以放进版本管理。我实际用下来这个“沉淀”的价值比预想中还要大因为新同学拿到项目后不用问“我们平时是怎么让 AI 干这活的”看一眼 mods 目录就懂了。痛点三是终端输出反人类。Claude Code 默认是纯文本输出信息长了就是一大片流水账看几屏就眼花。Mods 能驱动的另一个方向就是让 Claude 在终端里输出结构化界面色块、边框、进度条、实时刷新的仪表盘。这是“在终端画界面”这句话的由来也是我觉得 Mods 最性感的一部分。相比在浏览器里打开一个 DashBoard直接在终端里按需渲染一个临时面板成本低得多也更符合命令行工作的直觉。1.3 Mods 和插件、Skills、Slash Command 的区别很多刚接触生态的人会问Claude Code 不是已经有插件、Skills、斜杠命令了吗再搞个 Mods 是不是重复我自己的理解是这些概念背后的核心思路是一致的只是覆盖的层次不太一样。拿我熟悉的领域打个比方MCP 更像是给所有 AI 客户端共享的“USB 协议”它负责定义外部工具怎么连进来Slash Command 是快捷指令入口Skills 更偏知识注入给 Claude 喂一段背景知识让它学会某个场景的做事方式。而 Mods 在我的使用中会更像一个把上面这些能力打包好的“能力包”——一个 Mod 可以同时包含指令模板、外部脚本、UI 渲染逻辑。不过这里我不做太严格的学术定义因为不同版本里官方对这些概念的边界也在微调文档用词有时候会混着来。我的建议是先用起来再看它属于哪一类。你想给 Claude 加一个工具那就按 Mods 的方式创建一个描述文件加一个脚本你想让它在终端里画界面那就写一个会输出 ANSI 转义序列的工具脚本。用熟了之后这些概念之间到底剩多少差别其实不太影响你干活。2. 给 Claude 加工具Mods 的核心玩法2.1 Claude Code 本来就能执行终端命令为什么还要加工具Claude Code 自带 Bash 工具你直接跟它说“帮我看看内存占用”它就能执行相关命令。那加工具的意义在哪核心是三个词封装、约束、复用。直接让 Claude 随意跑命令虽然方便但你对它的控制力是弱的。你希望它执行一条固定的命令不希望在参数上自由发挥更不希望它在出错后自己试出一堆乱七八糟的 shell 片段。挂载一个 Mod 工具后Claude 能看到的只有你定义好的函数名、参数说明、返回格式它是在你有边界的沙箱里调用脚本而不是在一个无限可能的 shell 里探索。从实际体验来说把高频脚本封装成 Mod 还有一个隐藏好处你不需要在每轮对话中重新描述背景。直接说“用我的 sysinfo 工具看下这台机器的状态”Claude 就知道该调哪个脚本输出什么格式。时间久了你会发现这套东西用起来很像给命令行工具写 man pageAI 拿着说明文档调用你拿着结果看板。而且工具返回值如果是结构化 JSONClaude 还能自己决定要不要二次处理比如把数字转成“已用 12.4G / 总共 32G”这样的自然语言读起来舒服很多。2.2 写第一个 Mod一个系统信息查询工具先聊文件组织方式。项目级的 Mod 通常放在.claude/mods/目录下用户级的放在~/.claude/mods/下每个 Mod 是一个目录里面至少有一个描述文件加一个可选的可执行脚本。描述文件用 Markdown 写头部用 YAML frontmatter 声明元信息。下面这个例子是一个系统信息查询工具目录结构大致是这样.claude/mods/sysinfo/ ├── mod.md └── scripts/ └── sysinfo.py描述文件mod.md的内容可以长这样--- name: sysinfo description: 查询当前系统的CPU、内存、磁盘、网络状态返回结构化JSON tool: command: python3 scripts/sysinfo.py args: mode: desc: all/cpu/mem/disk/net 四选一 default: all --- 当用户想了解服务器或本机资源使用情况时使用 sysinfo 工具。 输出必须是 JSON字段固定为 cpu_usage, mem_total, mem_used, disk_total, disk_used。配套的sysinfo.py可以写成一段非常精简的 psutil 调用把结果print(json.dumps(data))打出来。这里的关键在于描述文件里的description和name是 Claude 决定“什么时候调用”的主要依据。写得太笼统Claude 不知道什么时候用它写得太复杂又容易喧宾夺主。我的写法是“什么时候用 输出什么格式 边界是什么”三行说清楚剩下的让脚本自己处理。2.3 加载与管理的几个高频操作查看当前已加载的 Mods在 Claude Code 里输入对应的列表命令把当前会话可用的 Mod 名称和描述列出来。启用或停用某个 Mod停用最粗暴的做法是把目录名加个后缀或者删掉描述文件重新进入会话后就不加载了。项目级与用户级的取舍项目级适合“这个仓库独有的脚本”用户级适合“我无论在哪都要用的工具”。我的建议是新写的 Mod 先放项目级。放项目级不影响全局环境出错了直接删目录就行等你在几个项目里都用顺手了再提升到用户级。这里还有个细节改完文件后Claude Code 不会热加载一般需要退出当前会话重新进入。你要是发现 Mod 一直没生效先别急着改脚本退出重开一次再说。2.4 实操心得工具粒度别太大这是我踩过最大的坑。初学者很容易做一个“万能工具 Mod”一个脚本里又是发请求、又是写文件、又是调接口最后发现问题反而更复杂因为 Claude 不太会主动用这种大而全的工具。我的经验是拆小每个 Mod 干一件事输入输出都是简单 JSON。宁可让 Claude 连续调用三次小工具也别让它在一个黑盒脚本里折腾半天。小工具有一个额外优势就是你调试的时候也轻松脚本出问题一眼就能看出是哪一步。3. 在终端画界面Mods 的终端 UI 路径3.1 终端里的界面其实是字符流一说“在终端里画界面”很多人第一反应是图片。不是的。终端 UI 的本质是字符流加控制字符。比如\033[2J是清屏\033[1;31m是把后面文字变成红色\033[H是把光标移到左上角。这些 ANSI 转义序列组合起来就能在终端里画边框、画表格、画色块、画进度条。命令行工具里那些花花绿绿的日志、表格、进度动画底层全是这套东西。那 Claude Code 怎么利用这套东西直接让 Claude 输出 ANSI 码有用但不够因为实时刷新的界面需要持续输出和清屏纯靠模型逐字输出太慢。更合理的方案是让 Mod 生成一个渲染脚本由脚本负责真正的界面刷新。这就是“Mod 画界面”和“人肉敲 ANSI”之间的分界线。Claude 只负责在最合适的时机启动脚本脚本一旦跑起来就和模型无关了用户看到的是一个活的终端面板。3.2 用 Mod 画仪表盘的原理一个能画界面的 Mod通常包含三段逻辑采集数据、组装画面、刷新输出。采集数据由脚本完成组装画面就是把数据拼成一行行带 ANSI 颜色的文本刷新输出用循环加time.sleep来实现。Mod 描述文件告诉 Claude 什么时候该跑这个脚本以及脚本运行期间用户应该看到什么。举个例子一个展示本机 CPU 和内存的仪表盘 Mod。描述文件里可以写“当用户要求查看资源面板或实时状态时运行 dashboard.py脚本会持续运行直到被 CtrlC 打断”。脚本内部每秒采集一次数据用 ANSI 转义序列把画面重绘一遍。Claude 看到用户说“来个实时面板”就自动调用这个 Mod。如果你平时只是想要一次性结果不想让它持续跑Mod 描述里也要写清楚“用户要求持续显示时运行”否则 Claude 一看到资源查询就给你弹个无限刷新的面板反而烦。3.3 终端复用与界面刷新tmux 是神器这里就要聊到终端复用了。我在 macOS 和 Linux 上用得最多的组合是 tmux Claude Code。为什么需要终端复用因为 Claude Code 占用一个终端会话实时仪表盘要占用另一个输出窗口普通终端窗口做不到“同一个屏幕里既有 AI 对话又有动态面板”。tmux 可以把你的一块屏幕切成多个 pane一个 pane 跑 Claude Code另一个 pane 跑仪表盘脚本互不干扰。具体操作是这样先用tmux new -s work开一个会话然后tmux split-window -h左右分屏左边跑 Claude Code右边跑 dashboard 脚本。切换焦点用CtrlB加方向键。如果你更喜欢图形化终端Tabby 这类现代终端工具对 tmux 的集成体验也不错字体渲染和配色都更舒服当作日常终端用没有任何问题。我自己在 Windows 上测试时Tabby 的 ANSI 支持比系统自带的好不少至少渲染状态面板不会乱。3.4 实操演示一个实时状态面板的最小实现下面是一个极简但能跑的仪表盘脚本它只做一件事每隔一秒重绘一次显示当前时间、CPU 占用、内存占用。代码里的核心就是 ANSI 转义#!/usr/bin/env python3 import sys import time import psutil def clear(): sys.stdout.write(\033[2J\033[H) def bar(pct, width20): filled int(pct * width) return [ # * filled - * (width - filled) ] while True: clear() cpu psutil.cpu_percent(interval0.5) / 100 mem psutil.virtual_memory().percent / 100 now time.strftime(%Y-%m-%d %H:%M:%S) print(f\033[1;36m 实时状态面板 {now}\033[0m) print(fCPU {bar(cpu)} {cpu * 100:.1f}%) print(fMEM {bar(mem)} {mem * 100:.1f}%) time.sleep(1)跑起来后终端会不断刷新同一个画面。把它嵌进 Mod 描述文件后Claude 就知道“用户要看状态”时执行它。需要注意两点脚本里要处理KeyboardInterrupt保证 CtrlC 能干净退出不然终端会残留一大堆控制字符如果终端宽度小于 40 字符界面就会错乱建议至少开 60 字符宽度。这里我习惯把“最小终端宽度要求”写进 Mod 描述里Claude 启动前会提醒用户把终端拉宽。4. 实操过程从安装到第一个 Mod 全流程4.1 Claude Code 的安装与配置Claude Code 最常见的是通过 npm 全局安装。前提是机器上有 Node.js版本不要太老我建议至少 18 以上。安装命令很简单npm install -g anthropic-ai/claude-code claude --versionmacOS 和 Linux 直接装就行装完先跑claude --version确认版本号能正常输出别急着直接开聊。Windows 的话我建议在 Git Bash 或 WSL 里跑原生 CMD 偶尔会遇到 ANSI 支持不完整的问题并不是不能用但像 Mods 这种依赖终端渲染的功能体验会差不少。Ubuntu 这类 Linux 发行版也是一样的思路先确认 node 和 npm 的版本都正常再一步步来别一上来就全局安装装完发现平台不兼容又得回头折腾。装完之后首次启动会要求登录走官方登录流程并配置 API Key。这一步属于环境前置条件跟着官方文档的引导操作就行。如果登录环节卡住先确认网络和 API Key 状态是否正常通常都是这两个环境变量的问题。登录成功后claude命令就能直接进入交互式会话。4.2 在 VS Code 里配置 Claude Code很多人其实不愿意完全脱离 IDE 干活。Claude Code 有官方 VS Code 扩展也可以在 VS Code 的集成终端里直接跑claude。我的习惯是日常开发用 VS Code 集成终端切一个面板跑 Claude Code看代码用编辑器对话在终端里这样两边切换顺畅。集成终端的好处是上下文切换快Claude 改完文件后编辑器会实时刷新不用来回切窗口。这里有一个配置细节容易被忽略VS Code 集成终端默认的 shell 在 Windows 上往往是 PowerShell如果不改部分命令的交互体验会不一致。我建议在设置里搜terminal.integrated.defaultProfile.windows把默认终端切换成 Git Bash 或 WSL这样 Claude Code 的行为表现得更接近 Linux 环境。macOS 用户一般不用管默认 zsh 就行。4.3 创建第一个 Mod 的完整步骤我以“给 Claude 加一个媒体文件信息查询工具”为例把完整步骤走一遍。第一步在项目根目录建目录mkdir -p .claude/mods/media-info/scripts第二步在media-info目录里创建描述文件mod.md写上元信息和工具说明。第三步写脚本scripts/media_info.py接收文件路径参数返回 JSON。第四步启动 Claude Code让 Claude 调用一次这个工具。如果描述文件写得没问题它会正确调用并返回结果。验证阶段我会故意问一句“这个 mp4 文件的编码是什么”如果 Claude 调用的是 media-info 工具说明 Mod 挂载成功。如果它还在尝试猜文件名或者自己拼命令多半是 description 没写清楚。这时候回去读一下描述文件里的触发条件把“媒体文件”“编码信息”“音频流”这类关键词补进去再重新加载一次。整个流程跑通之后你会明显感觉到Claude 不是“万金油”而是真正认识你环境里的工具。4.4 关于接入第三方模型服务的思路Claude Code 默认是配合 Anthropic 官方模型使用。但很多开发者在实操中发现自己手头有 DeepSeek 等模型的 API Key或者希望把调用成本降下来所以想让 Claude Code 指向兼容模型的接口。这套操作的本质是改模型接口地址。Claude Code 支持通过环境变量覆盖 API 服务地址你可以把 Base URL 指向兼容服务再把 API Key 换成对应服务的 Key。需要注意不同模型对工具调用的支持程度不一样如果 Mods 里大量依赖工具调用和结构化输出换成第三方模型后可能表现不稳定。我的建议是先跑通一个最基础的对话再逐步测试工具类 Mod最后才上复杂 UI 类 Mod。另外一个重要提醒不管接哪家模型API Key 都要小心保管不要写进仓库里。.claude/目录如果在 Git 仓库内建议把含密钥的配置文件路径加到.gitignore该忽略的别漏。5. 常见问题与排查技巧实录5.1 安装不上、命令找不到这类问题八成出在 Node 环境和 PATH 上。先node -v看版本低于 18 建议先升级。npm 全局安装后如果claude命令找不到检查 npm 全局 bin 目录是否在 PATH 里。Windows 上尤其常见npm 的全局目录在%APPDATA%\npm确认这个目录在环境变量 PATH 中。如果在 Git Bash 里跑 npm 全局安装但 Git Bash 没继承 Windows 的 PATH一样会找不到命令这时候手动把 npm 全局目录加到 Git Bash 的.bashrc里就行。5.2 Mod 加载不生效最常见原因有三个目录位置不对、描述文件格式不对、Claude Code 没重启。项目级 Mod 必须放在.claude/mods/下用户级放在~/.claude/mods/下路径错了自然加载不了。frontmatter 解析失败一般是因为 YAML 里用了 tab 而不是空格或者description字段里有特殊字符没转义。改完之后一定要退出当前 Claude Code 会话再重新进入因为它不会热加载。这一点我吃过好几次亏——改完描述文件立刻问 Claude它还是旧行为但实际上文件已经写对了重开就能用。5.3 终端界面渲染错乱画面乱跳、边框断裂、闪烁不停通常是这几个问题终端宽度不够、换行符不一致、终端不支持某些 ANSI。最简单的排查办法是把TERM环境变量设置成xterm-256color把脚本里的换行统一成\n然后用 Tabby 这类支持完整 ANSI 的终端跑一次。如果还乱优先怀疑是不是脚本里同时用了clear命令和 ANSI 清屏序列重复清屏会导致闪烁。另外中文在终端里的宽度是按双字节计算的如果面板里有中文字符边框对齐会受影响我一般直接用wcwidth处理或者干脆先上英文标签。5.4 权限与安全问题Mods 能执行外部脚本安全问题就变得非常重要。给 Mod 脚本传参数时Claude 会根据用户描述填充参数这意味着“文件路径”“URL”这类参数存在注入风险。我的防御习惯是脚本里只接受白名单参数路径必须经过realpath校验不直接拼接 shell 命令。讲个具体例子我之前写过一个读取文件片段的小工具一开始用os.system(head -n 1 path)结果路径里带空格就崩后来改成subprocess.run加列表传参再对路径做存在性检查问题一次解决。另一个细节是密钥管理除非是本地开发工具否则不要让 Mod 脚本读取环境变量里的密钥再输出给模型。你希望模型调用工具但不希望它把密钥内容带走。这里我还想强调一句Mods 是给 Claude 增加能力的但能力越强越要注意边界。给每个 Mod 最小化权限比事后补救安全得多。我用一张速查表总结一下高频问题现象常见原因解决办法claude命令不存在Node 版本低或 PATH 不对升级 Node检查 npm bin 目录Mod 描述文件不生效路径错或 YAML 语法错对照示例检查 frontmatterClaude 不调用 Moddescription 写得太模糊写清触发场景和输出格式终端画面闪烁重复清屏或 sleep 太短单次清屏sleep 调大到 1sUI 出现乱码终端不支持中文宽度加宽终端改用英文标签脚本被注入参数直接拼接 shell 命令用 subprocess 列表传参并做路径校验6. 我这段时间的实战体会踩过不少坑之后我最大的体会是Mods 的粒度要小、描述要准、边界要清。别想着一个 Mod 干十件事也别把一个工具的 description 写得像一篇论文。你把触发场景写得越具体Claude 就越知道什么时候该用它。另一个心得是“工具和界面分开做”数据采集和 UI 渲染尽量拆成两个脚本因为 UI 脚本会持续运行一旦卡住你还能用另一个脚本单独排查。后面我打算把自己常用的发版检查、日志捞取、工作归档都做成一个个独立 Mod 沉淀下来。等到你手边的 Mods 多了你会发现与其说是给 Claude 装外挂不如说是在给团队积累一本“可执行的私有手册”。希望这篇分享能帮你绕过我踩过的坑。