Agent 技能安装

CodexZH 提供两个 Agent 技能包，装好后可以直接用对话完成操作，不用记命令。

技能	装好后可以说
额度与用量查询	「我今天用了多少额度」「这周哪个模型最费钱」「套餐什么时候到期」
图片生成与编辑	「帮我画一只戴帽子的水獭」「把这张图的背景换成雪山」

两个技能可以只装一个，也可以都装。它们共用同一个 API Key。

安装只有 4 步

下载压缩包 → 找到技能目录 → 解压放进去 → 配置 API Key

技能目录按客户端不同而不同，这是最容易搞错的一步，请看第 2 步。

最省事：让 AI 自己装

不想手动下载解压，可以把整件事甩给 Codex 或 Claude Code。启动后把下面这段提示词完整复制粘贴进去：

帮我安装 CodexZH 的 Agent 技能，教程在 https://docs.codexzh.com/codex/agent-skills

两个技能包的下载地址：
- https://codexzh.com/downloads/codexzh-usage.zip  （额度与用量查询）
- https://codexzh.com/downloads/codexzh-image.zip  （图片生成与编辑）

请你：
1. 先判断我现在用的是哪个客户端。如果是 Codex，技能目录是 ~/.agents/skills/；如果是 Claude Code，技能目录是 ~/.claude/skills/。目录不存在就创建。
2. 下载这两个压缩包并解压到技能目录。解压后确认结构是 <技能目录>/codexzh-usage/SKILL.md，不要多套一层文件夹。
3. 创建 ~/.codexzh/config.json，内容是 {"apiKey": "sk-在这里填你的密钥"}，权限设成 600。如果我已经在 ~/.codex/.env 里配过 base_url 指向 codexzh 的 api_key，就跳过这步并告诉我会自动复用。
4. 装完列出技能目录确认文件到位，然后告诉我去哪里替换真实密钥、以及需要重启客户端才生效。

注意：不要编造 API Key，一律用占位符。

AI 会依次完成：

判断当前客户端，确定技能目录
下载两个技能包并解压到位
写入配置文件，API Key 先用占位符填充
检查文件结构是否正确
告诉你到哪里替换真实密钥

只想装一个技能

把提示词里不需要的那一行下载地址删掉即可。

装完按 AI 的指引填入你自己的 API Key（在控制台复制），然后重启客户端。

想自己动手，或者 AI 没装成功，按下面的步骤手动安装。

第 1 步：下载技能包

第 2 步：找到技能目录

技能要放进客户端的「技能目录」，不同客户端位置不一样：

客户端	技能目录
Codex	`~/.agents/skills/`
Claude Code	`~/.claude/skills/`

这里的 ~ 是个简写，代表你电脑的「用户主目录」，后面那个以点开头的文件夹默认是隐藏的。按下面的方法打开它：

MacWindows

text

1. 打开「访达（Finder）」
2. 按下 Command + Shift + G，会弹出一个跳转输入框
3. 输入技能目录路径后回车，例如：~/.agents/skills
4. 如果提示文件夹不存在，就在用户主目录下手动新建
   （先建 .agents，再在里面建 skills）

小贴士：按 Command + Shift + . （点号）可以切换显示隐藏文件

text

1. 打开「文件资源管理器」
2. 点击顶部地址栏，输入后回车，例如：%USERPROFILE%\.agents\skills
   （%USERPROFILE% 就是你的用户文件夹，一般是 C:\Users\你的用户名）
3. 如果提示找不到，就在用户文件夹下手动新建
   （先建 .agents，再在里面建 skills）

小贴士：在「查看 → 显示 → 隐藏的项目」里可以显示隐藏文件夹

新建以点开头的文件夹

Windows 直接右键新建文件夹时，输入 .agents 可能会提示「必须键入文件名」。解决办法：输入 .agents.（末尾多加一个点），回车后系统会自动去掉末尾的点。

第 3 步：解压技能包

把下载好的压缩包解压，把解压出来的文件夹整个拖进技能目录。

Mac：双击压缩包，会自动解压出一个 codexzh-usage 文件夹，把它拖进技能目录。
Windows：右键压缩包 → 「全部解压缩」，解压后把 codexzh-usage 文件夹拖进技能目录。

完成后目录结构应该是这样，注意 SKILL.md 要在技能文件夹的第一层：

text

~/.agents/skills/
├── codexzh-usage/
│   ├── SKILL.md
│   └── scripts/
└── codexzh-image/
    ├── SKILL.md
    └── scripts/

最常见的错误：多套了一层文件夹

如果解压出来是 skills/codexzh-usage/codexzh-usage/SKILL.md，说明多套了一层，客户端会认不出这个技能。

把里层的 codexzh-usage 文件夹移到上一层，然后删掉空的外层文件夹即可。

两个客户端都在用的话，两边各放一份。

习惯用命令行？一条命令搞定（点击展开）

CodexClaude CodeWindows

bash

unzip ~/Downloads/codexzh-usage.zip -d ~/.agents/skills/
unzip ~/Downloads/codexzh-image.zip -d ~/.agents/skills/

bash

unzip ~/Downloads/codexzh-usage.zip -d ~/.claude/skills/
unzip ~/Downloads/codexzh-image.zip -d ~/.claude/skills/

powershell

Expand-Archive -Path "$HOME\Downloads\codexzh-usage.zip" -DestinationPath "$HOME\.agents\skills\" -Force
Expand-Archive -Path "$HOME\Downloads\codexzh-image.zip" -DestinationPath "$HOME\.agents\skills\" -Force

-d / -DestinationPath 指定的是技能目录，压缩包里已经带了技能文件夹这一层，不会多套。

第 4 步：配置 API Key

两个技能共用一个 Key，配一次就够。任选一种方式：

环境变量（推荐）配置文件Windows

bash

# 写进 ~/.zshrc 或 ~/.bashrc，重开终端生效
export CODEXZH_API_KEY="sk-你的密钥"

json

// ~/.codexzh/config.json
{
  "apiKey": "sk-你的密钥"
}

powershell

# 永久写入用户环境变量
[Environment]::SetEnvironmentVariable("CODEXZH_API_KEY", "sk-你的密钥", "User")

API Key 在 CodexZH 控制台复制，以 sk- 开头。

保管好 API Key

不要截图发给别人，也不要粘贴到公开群聊或论坛里。配置文件建议设成只有自己可读（chmod 600 ~/.codexzh/config.json）。

如果你已经在 ~/.codex/.env 里配过 CodexZH 的 api_key，技能会自动复用，这一步可以跳过。

第 5 步：重启客户端并试用

技能是客户端启动时加载的，放好文件后必须重启才能生效。

重启后直接用日常说话的方式提问就行，不用记命令，客户端会自己判断该用哪个技能：

text

我今天用了多少额度？

如果回答里出现了你的真实额度数字，说明装好了。

额度技能能回答什么

你可以问	会得到
我今天用了多少额度？	今日消费、调用次数、Token 数
这周还剩多少额度？	本周已用 / 周限额度、剩余可用
我的套餐什么时候到期？	订阅起止时间、剩余天数
这周哪个模型最费钱？	按模型聚合的消费排行
昨天调用了哪些模型？	指定日期的调用明细
帮我看看最近 7 天的用量趋势	近 7 天的请求数、Token 和消费

查询范围最多一次跨 31 天。接口限制每分钟 10 次，正常提问不会碰到。

生图技能能做什么

text

帮我画一只戴贝雷帽、坐在木桌上的小水獭，柔和光线

text

把这张图的背景换成下雪的雪山          （附上图片路径）

text

把图里这块区域换成一盆绿植             （附上图片和掩码）

支持文生图、图生图（改已有图片）和局部重绘。图片默认存到当前目录，也可以直接说「存到桌面」。

生图前请先放开权限

Codex 的沙盒默认是「只读」、不允许命令联网，直接生图大概率失败，提示「沙盒内无法解析 api.codexzh.com」或审核服务返回 503。

生图前先在聊天界面把权限切成完全访问权限，或在设置 →「配置」→「沙盒设置」里改成完全访问。详细图示见常见问题。

关于生图费用

生成图片按次计费，从周额度中扣除。具体金额以控制台用量明细为准，装了额度技能的话直接问「我今天生图花了多少」也能查。

可能出现多次扣费

Agent 生成完图片后会自己检查，如果它觉得不合适会重新再生成一次，所以一个需求可能对应好几条调用记录。

另外还可能出现图片已经生成成功、但 Codex 等待超时误判为失败的情况，这时后台正常扣费但图片没返回给你。

如果介意这两种情况，可以改用 AI HUB API 网页生图，一次请求对应一张图。

常见问题

客户端里看不到技能

确认解压位置对不对（Codex 是 ~/.agents/skills/，Claude Code 是 ~/.claude/skills/）。
确认没有多套一层文件夹，SKILL.md 应该直接在 codexzh-usage/ 下面。
重启客户端——技能是启动时加载的，解压后不重启看不到。

提示「未找到 CodexZH API Key」

环境变量没生效，或配置文件路径不对。检查：

echo $CODEXZH_API_KEY 能不能打印出密钥（Windows 用 echo %CODEXZH_API_KEY%）
设了环境变量后有没有重开终端、重启客户端
配置文件路径是 ~/.codexzh/config.json，不是 ~/.codex/

提示「无效的令牌」

Key 填错了，或者已经轮换过。到控制台重新复制一次，注意前后不要多带空格。

提示「请求过于频繁」

额度查询接口限制每分钟 10 次。稍等片刻再问即可，不用反复重试。

怎么更新技能

重新下载压缩包，解压覆盖原目录，然后重启客户端。

想手动创建文件而不是解压

生图技能的手动创建方式见用 Codex 生成图片，那里列出了每个文件的完整内容。

Agent 技能安装 ​

最省事：让 AI 自己装 ​

第 1 步：下载技能包 ​

第 2 步：找到技能目录 ​

第 3 步：解压技能包 ​

第 4 步：配置 API Key ​

第 5 步：重启客户端并试用 ​

额度技能能回答什么 ​

生图技能能做什么 ​

生图前请先放开权限 ​

关于生图费用 ​

常见问题 ​

客户端里看不到技能 ​

提示「未找到 CodexZH API Key」 ​

提示「无效的令牌」 ​

提示「请求过于频繁」 ​

怎么更新技能 ​

想手动创建文件而不是解压 ​

延伸阅读 ​

Agent 技能安装

最省事：让 AI 自己装

第 1 步：下载技能包

第 2 步：找到技能目录

第 3 步：解压技能包

第 4 步：配置 API Key

第 5 步：重启客户端并试用

额度技能能回答什么

生图技能能做什么

生图前请先放开权限

关于生图费用

常见问题

客户端里看不到技能

提示「未找到 CodexZH API Key」

提示「无效的令牌」

提示「请求过于频繁」

怎么更新技能

想手动创建文件而不是解压

延伸阅读