CPA + Codex 配置避坑指南 前言 本文记录了配置 CLI Proxy API (CPA) 与 Codex 集成时遇到的各种坑，希望能帮助后来者少走弯路。 环境信息 系统 : macOS (Apple Silicon) CPA 版本 : v6.9.29 Codex 版本 : 0.121.0 代理工具 : ClashX / Clash Verge 核心问题：502 Bad Gateway 症状 Codex 启动后尝试连接 API 时，反复出现： Unexpected status 502 Bad Gateway: Unknown error, url: http://localhost:8321/v1/responses 根本原因 系统代理拦截了 localhost 请求！ ClashX/Clash Verge 等代理工具默认会拦截所有 HTTP 请求，包括 localhost 和 127.0.0.1 。当 Codex 尝试访问本地 CPA 服务时，请求被代理转发，导致： 请求无法直接到达本地服务 代理返回 502 错误 日志中看不到任何请求记录（因为请求根本没到达目标服务） 解决方案 方法 1：设置 NO_PROXY 环境变量（推荐） # 添加到 ~/.zshrc 或 ~/.bashrc export NO_PROXY="localhost,127.0.0.1" # 应用配置 source ~/.zshrc 重要： 必须在新终端中启动 Codex，才能加载新的环境变量。 方法 2：配置代理绕过规则 在 ClashX/Clash Verge 中添加绕过规则，让 localhost 不走代理。 其他常见问题 1. API Key 不匹配 (401 Unauthorized) 症状： Unexpected status 401 Unauthorized: {"error":"Invalid API key"} 原因： Codex 使用了自己的 API key（格式如 sk-sub-Pack6n6X... ），而不是配置文件中的 api_key 。 解决方案： 将 Codex 使用的 key 添加到 CPA 配置中： # ~/cpa-config.yaml api-keys: - "your-custom-key" - "sk-sub-Pack6n6X_yKXdwEwPB2mT0iGkcQyE4IMMHe-kCN7TIy4L-gf" # Codex 的 key 重启 CPA： pkill -f "cpa.*config" ~/.local/bin/cpa -config ~/cpa-config.yaml > /tmp/cpa.log 2>&1 & 2. 端口被占用 症状： Error: listen EADDRINUSE: address already in use 127.0.0.1:8321 原因： 旧的 shim 进程还在运行 LaunchAgent 自动重启服务 解决方案： # 查找占用端口的进程 lsof -nP -iTCP:8321 -sTCP:LISTEN # 停止进程 kill -9 <PID> # 禁用自动启动 launchctl unload ~/Library/LaunchAgents/com.linkunkun.codex.cliproxy-shim.plist 3. 旧版本冲突 症状： Homebrew 安装的旧版本 cliproxyapi 自动重启。 解决方案： # 停止 Homebrew 服务 brew services stop cliproxyapi # 卸载旧版本 brew uninstall cliproxyapi # 清理配置 rm -rf /opt/homebrew/etc/cliproxyapi* rm -f ~/Library/LaunchAgents/homebrew.mxcl.cliproxyapi.plist 4. Shim 是否必需？ 答案：不需要！ 早期以为需要 shim 来转换请求格式，但实际上： CPA 原生支持 /v1/responses 端点 直接连接 CPA 更简洁高效 推荐配置： # ~/.codex/config.toml [model_providers.custom] name = "custom" wire_api = "responses" base_url = "http://localhost:8317/v1" # 直接连 CPA api_key = "your-api-key" 完整安装步骤 1. 安装 CPA # 下载最新版本 curl -L -o /tmp/cpa.tar.gz https://github.com/router-for-me/CLIProxyAPI/releases/download/v6.9.29/CLIProxyAPI_6.9.29_darwin_arm64.tar.gz # 解压并安装 cd /tmp tar -xzf cpa.tar.gz mkdir -p ~/.local/bin mv cli-proxy-api ~/.local/bin/cpa chmod +x ~/.local/bin/cpa # 添加到 PATH echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc 2. 配置 CPA # 复制示例配置 cp /tmp/config.example.yaml ~/cpa-config.yaml # 编辑配置 vim ~/cpa-config.yaml 关键配置项： port: 8317 # 管理密钥 remote-management: secret-key: "your-admin-password" # API keys api-keys: - "your-api-key" 3. 启动 CPA nohup ~/.local/bin/cpa -config ~/cpa-config.yaml > /tmp/cpa.log 2>&1 & 4. 配置 Codex # ~/.codex/config.toml model_provider = "custom" model = "gpt-5.4" [model_providers.custom] name = "custom" wire_api = "responses" base_url = "http://localhost:8317/v1" api_key = "your-api-key" 5. 配置代理绕过（关键！） # 添加到 ~/.zshrc echo 'export NO_PROXY="localhost,127.0.0.1"' >> ~/.zshrc source ~/.zshrc 6. 测试 # 测试 CPA curl http://localhost:8317/v1/models -H "Authorization: Bearer your-api-key" # 在新终端启动 Codex codex 调试技巧 1. 查看 CPA 日志 tail -f /tmp/cpa.log 2. 查看 Codex 日志 tail -f ~/.codex/log/codex-tui.log 3. 检查端口占用 lsof -nP -iTCP:8317 -sTCP:LISTEN 4. 测试 API 连接 curl -v http://localhost:8317/v1/responses \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5.4","input":[{"role":"user","content":[{"type":"input_text","text":"test"}]}]}' 5. 检查代理设置 # 查看环境变量 env | grep -i proxy # 查看活动连接 lsof -nP -iTCP | grep codex | grep ESTABLISHED 常见错误排查流程 502 Bad Gateway ↓ 检查是否有代理 (lsof -nP -iTCP | grep codex) ↓ 有代理 → 设置 NO_PROXY ↓ 无代理 → 检查服务是否运行 ↓ 401 Unauthorized ↓ 检查 Codex 使用的 API key (查看日志) ↓ 将 key 添加到 CPA 配置 ↓ 重启 CPA 总结 配置 CPA + Codex 的最大坑就是 系统代理 。记住： 设置 NO_PROXY 环境变量 在新终端启动 Codex 直接连接 CPA，不需要 shim 将 Codex 的 API key 添加到 CPA 配置 遵循这些原则，可以避免 90% 的问题。 参考资源 CPA GitHub CPA 文档 管理界面 最后更新 : 2026-04-18 作者 : 基于实际踩坑经历整理 5 个帖子 - 3 位参与者 阅读完整话题
请教各位佬友一个问题, codex聊天记录除了本地存储外, 云端会有存储吗, 如果别人拿到账号密码登录是否能看到codex的历史记录 2 个帖子 - 2 位参与者 阅读完整话题
目前规划是前期公益 后期盈利， 后期想把大部分模型都上上实现盈利， 本人做抖音直播短视频的 所以推广问题不大， 考虑是自身技术有限，所以想找一些大佬作为云股东一起建设，后期可以爽蹬。 目前注册机注册速度很慢，解决不掉，需要找个有开发和解决中转站的大佬一起研讨 服务器啥的需要买个啥样的比较好，比如日本的美国的，我有个美国表弟后期我懂点了可以在他家部署个正儿八经的家宽服务器，然后我用他的卡 买opus4.7的api接入站内就可以实现纯血了 然后我再混点反代 就可以实现盈利了！！！哈哈哈哈哈哈哈哈哈 不好意思跑题了，奸商的嘴脸又暴漏了，我只是想了解下逻辑 为啥可以掺着卖。。。 回归正题，云股东依旧可以长期享受爽蹬 但是前提是要有贡献共同维护好站点， 相比大家都在公益站上来回徘徊，是因为我觉得大部分公益站都没有赢利点必然不长远嘛， 如果有赢利点 战长可以有维护成本 这个事必然会长远一点， 小白也只是有点自己的见解而已，欢迎大家毛遂自荐，时间充足的，有能力解决问题的， 包括我也想把那个即梦注册机看看咋可以变成api直接导入到AI漫剧对接下 最好， 目前就买了一个域名，下一步买个服务器，求大家推荐下，一步步的来。 服务器我还自己做了一个网站和小程序我也需要放在上面，注册机我也放在上面， newapi也部署上面去，然后最好是可以养个小龙虾在上面 平时就可以遥控龙虾直接在服务器上修newapi了 是这个样的吗 球大佬指点一二。 28 个帖子 - 8 位参与者 阅读完整话题
前4个： 1.官网fiat24卡开，秒封 2.尼区5x，三天封 3.尼区Pro，隔天封 4.goole play买的5x，隔天封 一直封，一直爱试，手痒难耐。今天看见佬友帮忙用自写的反代代挂，就又心动开了一个5x试试水。 如果有希望使用claude反代的 可以找我 搞七捻三 自写的反代目前看来比较稳定 之前直接分享自己用的key被举报了 没心情分享免费opus4.7了 但是如果有佬自己的号希望反代用 可以找我免费托管，代理我来提供 因为代理是按流量计费的 5 /GB 所以提供不了太多号 建议最多2个人分享一个号，更多人没测过 有可视化面板可以查使用情况 不用担心有你本人以外的人使用你的账号 记录一下时间线： 2026-04-18 16点：Google Play 购买 5x 2026-04-18 17点：开始反代… 2026-04-18 20点：第一次2api对话…正常 6 个帖子 - 4 位参与者 阅读完整话题
如题，我3个账号用cpa（不然聊天记录不共享）的api接入codex，但是发现用api没法开始codex的/fast，这应该怎么办？难道用ccs再加一个解析本地会话记录的东西吗 2 个帖子 - 2 位参与者 阅读完整话题
写在开头：纯水，群友转发的聊天记录不可信，不要认真。 先来看瓜，为了方便佬们观看，手动横向排版了下： ==============分割线============== 吃饭的时候刷到的，突然就想起来前两天刷到L站有类似的帖子，那个佬也是对象出去团建了然后不回消息啥的。 那还说啥，赶紧往嘴里扒两口饭就直奔卧室打开L站，凭着关键词印象翻到了那帖子，还好最后发现不是同一个 11 个帖子 - 9 位参与者 阅读完整话题
之前的账号3h就没了，这次准备再新开一个，再次尝试一下！ 目前准备： 静态LSP（美国加州） 住宅IP代理的指纹 浏览器 Claude账号注册用的是Gmail（新号）已养号3天 支付使用Visa虚拟卡 使用准备： 养号阶段——Web端对话 测试阶段——开通后先使用2天Web 使用阶段——没问题后，迁移至ClaudeCode（Linux服务器部署），同时我会删除原有的.claude文件夹（之前的残留） 这个帖子用来记录使用日志记录，欢迎各位佬友讨论！ 1 个帖子 - 1 位参与者 阅读完整话题
最终搞定了，记录一下。 在 Home Assistant（简称HA）里安装 xiaomi-miot 插件后。 设置 → 设备与服务 → 搜索 Xiaomi Miot 在设备列表里找到你要控制的音箱，我有2个小爱音箱，其中 小米小爱音箱 Pro ，在 Miot 里叫做 Mi AI Speaker Pro，设备型号 xiaomi.wifispeaker.lx06 小米智能音箱 Pro ，在 Miot 里叫做 Xiaomi Smart Speaker Pro，设备型号 xiaomi.wifispeaker.oh2p 点击进入设备控制页面后，可以发现有很多控制功能，比如【播放文本】和【执行文本指令】。 点击“播放文本”功能前面的图标，再点击右上角的设置图标 即可看到这个功能的【实体标识符】，我理解就是一个 function id 有了这个，再配合 HA 生成的长期 token，就能写脚本控制小爱音箱说话了。 这是龙虾给我写的代码，测试通过。 1 个帖子 - 1 位参与者 阅读完整话题
1、2023年slack时期，使用google老号注册的claude，大概2023年4月份左右注册的。 2、上个月使用google play套U卡支付了一个月pro，稳定到今天最后一天，直接冲max20，google play + 国内招商visa卡，250刀。 aws服务器部署sub2api中转站反代claude code 4 个帖子 - 3 位参与者 阅读完整话题
在印尼实体服务器部署中转供内部5人使用，购买的是max20账号。 4月13号认证pro账号，不够用，4月14号中午升级为max20，分发了账号，大家在国内自己的电脑接入使用，晚上7点被退款； 4月15号开第二个账号购买max20，使用国内同一个服务器、同一个账号，用了不到30分钟封号了。 求大佬指点长久一点的使用方法。 3 个帖子 - 2 位参与者 阅读完整话题
让 opus 总结的，包含了踩坑记录和完整部署过程 可以直接丢给你们的agent看 Claude-Code-LSP-部署与踩坑记录.pdf (474.9 KB) 5 个帖子 - 4 位参与者 阅读完整话题
一个free扛住了69个请求，感觉比team号还耐造 1 个帖子 - 1 位参与者 阅读完整话题
前提条件 ：已知锁屏密码 现状： 屏幕全黑 触屏有反馈 开机有开机音乐 屏幕无显示，但可以触摸，开机进系统。 最终目的是打开手机的USB调试模式，从而使用工具访问手机，达成类“云手机”的效果。 tips：如果手机无法触摸，可以尝试使用TypeC-USBA的方式OTG连接鼠标模拟点击，具体实践会更复杂。当然如果屏幕可以显示的情况下，OTG连接鼠标已通关。 tips：很多手机不支持OTG。OTG还有扩展包括支持鼠标键盘；支持扩展坞连接显示屏（仅常见于三星、华为高端型号） tips：有动手能力可以网购屏幕总成解决问题。 尝试记录 测试截图 同时按下电量和音量下键，手机震动。三指下滑，手机震动。说明手机可以正常截图。 测试解锁屏幕 手从屏幕中线最下方开始逐步向上点击，第一个震动反馈，一般就是0键，根据按键相对位置，可以逐步标记789的位置，记号笔记录。再根据789轴线从上向下点击，确认123位置，456位置也可以确认。 接下来根据手机声音和震动，可以确认手机是否解锁。通常解锁失败，手机会较大震动。解锁成功则轻微震动或者声音反馈。 USB访问文件 通常解锁后，电脑USB连接上，会有会话框进行选择”仅充电、访问相册、访问文件“，根据各品牌和系统版本有所不同。搜索对应手机系统版本的视频，可以大致推测位置。根据大致位置，从左开始点击，无反应，推测为仅充电；从右开始点击，电脑一段时间后发现存储器，检查，激活相册。 截图 此时，启动手机截图，刷新相册文件夹，发现新截图。 根据截图信息和黑屏触屏点击，可以相对判断点击后的效果，依次进入设置-开启USB调试。 tips：如存在屏幕部分区域无法点击，参考OTG连接鼠标 tips：开发者模式存在一项绘制当前触控位置和小圆点的配置，可以观察点击的位置。（当然，你都进入这个界面了，USB调试就差点两下了，还需要这个吗？ USB调试验证 USB插入手机，可能需要手机点击一下允许连接USB调试，这将会保存一个验证密钥文件到PC端。到此正式启动USB调试。 ==== 后续，准备拆开后盖卸电池，改直连。 因为没有屏幕，观测电量很麻烦，长期充电有火灾风险。 室友相机放窗边太阳直射下充电，引起火灾，虽及时扑灭，但锂电池燃烧导致房屋大面具熏黑，照价赔偿4位数，引以为鉴。 不知道当前屏幕到底还是否在耗电？如果还耗电是不是可以拆机把屏幕排线拆下来？ ==== 幻想环节1 黑屏刷机–需要解锁BL（假想环节，非专业人士切勿模仿） 使用镜像修改工具，修改镜相包配置文件，重新打包，关闭USB调试验证，开启充电自启，大致需要6-8项配置。失败则变砖，仅能购买屏幕总成解决。 还可以跳过开机引导，可惜MIUI每个版本的跳过策略都不同，无法通用。 幻想环节2 远程屏幕模拟 经过搜索，主板连接屏幕应该是依靠MIPI-DSI接口协议，一般没有验证芯片，也就是说，只要自己实现一个开发板连接排线，模拟自己是一个屏幕，即可远程发送画面和触控交互。 这玩意似乎没办法用低成本的芯片进行开发，只看到了FPGA方案，500+成本起步。其他方案个人用户很难得到完整的开发文档。 并且根据不同屏幕之间存在通用性问题，推断手机排线定义可能是不通用的，没有手册烧毁概率极大。 没有市场前景，大规模厂商是直接购买成品主板的，自带所有权限的ROM，无需该方案。 5 个帖子 - 5 位参与者 阅读完整话题
在此记录一个在开发自测环节中遇到的问题: 先上代码(已脱敏) type TestData struct { Data []byte `json:"data"` } func TestTryEncryptoClient(t *testing.T) { jsonStr := "{\"Data\":\"4GFwsR9XFRkyb/9Hn14zNpQRFE4V/f1hLIDlnff6LLPR/EvRmSW6ma6PHZiamB4mDeynjRYfVsfipg==\"}" message := &TestData{} err := json.Unmarshal([]byte(jsonStr), message) if err != nil { panic(err) } result := message.Data t.Logf("%v", result) t.Log(string(result)) sprintf := fmt.Sprintf("%s", result) t.Log(sprintf) t.Logf("bad base64: %s", result) t.Log("test done") } 输出内容(goland)控制台 [224 97 112 177 31 87 21 25 50 111 255 71 159 94 51 54 148 17 20 78 21 253 253 97 44 128 229 157 247 250 44 179 209 252 75 209 153 37 186 153 174 143 29 152 154 152 30 38 13 236 167 141 22 31 86 199 226 166] 짍V��� 짍V��� 짍V��� xxx_test.go:193: test done 现象描述: 此段代码会造成如下代码片段未能输出 t.Logf("bad base64: %s", result) ，并且如果是多协程测试条件下，很可能会造成控制台卡住(无法输出后续内容) 原因分析: 在此过程中，我们错误使用了%s来匹配 []byte 类型的数据，虽然golang在编译或者goland在运行前检查中不会报错/warning，但是在最终输出的时候，由于 byte[] 中包含了不能被控制台解析的控制字符，所以会造成最终输出内容的错误(也可以叫做编码不匹配)，并且由于大部分编码都会兼容ASCII编码，在上述输出中会有byte为22的控制字符-> ASCII中描述为暂停等待同步字符，所以在多线程/协程测试中会导致控制台卡住等待同步完成 解决方案: 使用string现式包裹 []byte 即可 sprintf := fmt.Sprintf("%s", string(result)) 总结: 下次当遇到控制台卡住无输出的时候，记得检查是不是%s遇上了 []byte 类型的数据(常见某些加密流中的测试，用于观察加密后的字符输出) 1 个帖子 - 1 位参与者 阅读完整话题
佬们，codex不自己单做接口的情况下，不同的中转API有没有办法共享/继承聊天记录？ 更换之后上下文总是无非继承。 5 个帖子 - 5 位参与者 阅读完整话题
20260417 晚8点开的 记一下 tg渠道 后续稳定的话可能和佬友一起蹬，因为主用codex，网页的pro就体验体验 3 个帖子 - 2 位参与者 阅读完整话题
AnyRouter Claude Code 验证机制分析 本文档记录了通过逐步删减请求字段、实际发送请求测试，得出的 AnyRouter 对 Claude Code 请求的验证机制。 测试日期：2026-03-16 起，持续追加 测试方法：以完整的 Claude CLI 请求为基准，逐个移除字段并观察响应状态码（200 = 通过，500 = 拒绝） 重要提醒：验证机制具有时变性与灰度特征 AnyRouter 的验证逻辑经过多次反复调整， 任何结论都不应被视为长期稳定 ： 请求头校验可能被启用或取消（如 anthropic-beta 从"可选"变为"必需"） 白名单策略可能被启用或撤销（如 session_id 白名单上线又下线） user_id 格式曾整体变更（扁平字符串 → JSON 字符串） 同一时段内不同 Key 行为可能差异巨大（被封禁/限流的 Key 返回 520/503，正常 Key 返回 200） 不同模型的上游可用性独立变化（旧模型下线、新模型灰度上线） 部分校验存在 灰度/后端负载 相关的不稳定行为 使用建议 ： 代理实现应默认携带"完整最小必需集"（见后文），而非依赖某次测试得出的"可省略"结论 遇到非预期错误码时，优先换 Key / 换模型 / 换时间重试，再排查请求体 本文档中旧结论凡被推翻的，均以「已失效 / 已变更」标注并保留，用于回溯演变轨迹 一、验证结论总览 AnyRouter 的验证 只检查请求体 ，不检查请求头。核心验证点仅有两个： system 数组中必须包含精确的 Claude Code system prompt metadata.user_id 必须符合特定格式 2026-04 更新 ：以上结论为早期测试结果。当前 AnyRouter 同时校验请求头 ， 缺少必需的 anthropic-beta 头（尤其是 context-1m-2025-08-07 标志）会直接返回 400。 详见下方「请求头新增校验」章节。 最小可通过请求 = 标准 Anthropic 请求 + system[0].text = "You are Claude Code, Anthropic's official CLI for Claude." + metadata.user_id = "user_{64位hex}_account__session_{UUID格式}" 补充：请求头新增校验（2026-04-11 确认） 400 错误：“1m 上下文已经全量可用，请启用 1m 上下文后重试” 错误现象 ： {"error":"1m 上下文已经全量可用，请启用 1m 上下文后重试","type":"error"} 所有模型、所有 Key 均返回 HTTP 400，与请求体内容无关。 根本原因 ： anthropic-beta 请求头中缺少 context-1m-2025-08-07 标志。AnyRouter 现在会检查此 beta flag 来确认客户端已启用 1M 上下文窗口。 解决方案 ： 在请求头中添加 anthropic-beta ，至少包含 context-1m-2025-08-07 ： anthropic-beta: context-1m-2025-08-07 Claude Code CLI 2.1.92 实际发送的完整 anthropic-beta 值（共 9 个 flag）： claude-code-20250219,context-1m-2025-08-07,interleaved-thinking-2025-05-14,redact-thinking-2026-02-12,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,fast-mode-2026-02-01 各 flag 含义： Flag 用途 claude-code-20250219 Claude Code 专属标识 context-1m-2025-08-07 启用 1M 上下文窗口（ AnyRouter 必须校验项 ） interleaved-thinking-2025-05-14 交错思考模式 redact-thinking-2026-02-12 思考内容脱敏 context-management-2025-06-27 上下文管理 prompt-caching-scope-2026-01-05 提示缓存作用域 advanced-tool-use-2025-11-20 高级工具使用 effort-2025-11-24 输出努力程度控制 fast-mode-2026-02-01 快速模式 经逐项省略测试确认， anthropic-beta 是 唯一 必需的非标准头，其余头（ User-Agent 、 x-app 、 X-Stainless-* 、 anthropic-version 等）均可省略。完整测试结果见下方第二章。 测试对比 ： anthropic-beta 中包含 context-1m-2025-08-07 状态码 否 400（上述错误） 是 200 或 503（验证通过） 二、请求头测试详情 注意 ：以下为 2026-03-16 的旧测试结果，当时 AnyRouter 不校验请求头。 2026-04-11 重新测试发现 anthropic-beta 已变为 必需 头，详见下方更新。 旧测试结果（2026-03-16，已过时） （点击了解更多详细信息） 请求头结论（2026-04-11 更新） AnyRouter 现在校验 anthropic-beta 请求头。 缺少此头或其中不含 context-1m-2025-08-07 会返回 400。 逐项省略测试方法：以完整请求头为基准，每次仅移除一个字段，发送请求并记录响应状态码（自动重试 520）。每个字段测试 2 次有效结果。 移除的请求头 结果 结论 Accept 200, 200 可省略 User-Agent 200, 200 可省略 X-Claude-Code-Session-Id 520, 200 可省略 X-Stainless-Arch 200, 200 可省略 X-Stainless-Lang 200, 200 可省略 X-Stainless-OS 200, 200 可省略 X-Stainless-Package-Version 200, 200 可省略 X-Stainless-Retry-Count 200, 200 可省略 X-Stainless-Runtime 200, 200 可省略 X-Stainless-Runtime-Version 200, 200 可省略 X-Stainless-Timeout 200, 200 可省略 anthropic-beta 400, 400 必需 anthropic-dangerous-direct-browser-access 200, 200 可省略 anthropic-version 200, 200 可省略 x-app 200, 200 可省略 最小请求头： Content-Type: application/json Authorization: Bearer sk-xxx anthropic-beta: context-1m-2025-08-07 以下请求头全部为冗余，可安全移除： accept anthropic-version anthropic-beta anthropic-dangerous-direct-browser-access user-agent x-app x-stainless-arch x-stainless-helper-method x-stainless-lang x-stainless-os x-stainless-package-version x-stainless-retry-count x-stainless-runtime x-stainless-runtime-version x-stainless-timeout accept-encoding 三、URL 参数测试 # 变更 状态码 结论 9 移除 ?beta=true 200 可移除 URL 结论 直接使用 /v1/messages 即可，无需 ?beta=true 查询参数。 四、请求体 — system 字段测试 # 变更 状态码 结论 13 完全移除 system 500 必需 12 只保留一个 system 块（Claude Code prompt） 500 失败（因同时无 metadata） 15 一个 system 块 + 有 metadata 200 一个块就够 14 两个 system 块，无 cache_control 200 cache_control 不需要 18 第一个 system 文本改为 "You are a helpful assistant." 500 文本必须精确匹配 25 第一个 system 文本去掉末尾句号 500 句号不可省略 19 第二个 system 块文本改为 "anything" 500 若有第二块，必须为 "null" system 字段结论 必须 包含至少一个 system 块 第一个块的 text 必须 精确匹配 以下字符串（一字不差，含末尾句号）： You are Claude Code, Anthropic's official CLI for Claude. 第二个 "null" 块 可省略 （一个块即可通过） 如果保留第二个块，其 text 必须为 "null" ，不能是其他值 cache_control 字段完全不需要 最小 system： "system": [ {"type": "text", "text": "You are Claude Code, Anthropic's official CLI for Claude."} ] 五、请求体 — metadata 字段测试 # 变更 状态码 结论 10 完全移除 metadata 500 必需 26 metadata 为空对象 {} 500 必须包含 user_id 17 user_id = "test" 500 格式不对 20 user_id = "user_abc123" 500 长度不够 22 user_id = "user_{64位hex}" （无 session 后缀） 500 缺少 session 部分 21 user_id = 完整格式，不同哈希值 200 值任意，只校验格式 23 user_id = 全零占位值 200 全零也能通过 metadata 字段结论 metadata 对象 必须存在 metadata.user_id 必须存在 且符合以下格式： user_{64位十六进制字符}_account__session_{UUID格式} 不校验具体值 ，只校验格式（正则匹配） 全零占位值完全可用： "metadata": { "user_id": "user_0000000000000000000000000000000000000000000000000000000000000000_account__session_00000000-0000-0000-0000-000000000000" } user_id 格式拆解 user_ ← 固定前缀 "user_" 82a10c807646e5141d2ffcbf5c6d439ee4cfd99d1903617b7b69e3a5c03b1dbf ← 64 位 hex（SHA-256 哈希） _account__session_ ← 固定中缀 "_account__session_" 74673a26-ea49-47f4-a8ed-27f9248f231f ← UUID v4 格式 (8-4-4-4-12) 推测的验证正则： ^user_[0-9a-f]{64}_account__session_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ 六、请求体 — 其他字段测试 字段 测试结果 说明 messages 必需 Anthropic API 标准要求 max_tokens 必需 Anthropic API 标准要求 model 必需 Anthropic API 标准要求 messages 中的 "null" 文本块 可移除 简单字符串 content 即可 cache_control （system 和 messages 上的） 可移除 不参与验证 thinking 可选 只影响是否启用思考链 七、最终最小请求模板 curl https://anyrouter.top/v1/messages \ -H "Content-Type: application/json" \ -H "x-api-key: sk-xxx" \ -d '{ "model": "claude-opus-4-6", "messages": [ {"role": "user", "content": "Hello"} ], "system": [ {"type": "text", "text": "You are Claude Code, Anthropic'\''s official CLI for Claude."} ], "metadata": { "user_id": "user_0000000000000000000000000000000000000000000000000000000000000000_account__session_00000000-0000-0000-0000-000000000000" }, "max_tokens": 1024 }' 八、验证机制推测 根据测试结果，AnyRouter 的验证逻辑推测如下： 收到请求 │ ├─ 提取 x-api-key 或 Authorization → 标准认证 │ ├─ 解析 JSON body │ ├─ 检查 system[0].text │ ├─ == "You are Claude Code, Anthropic's official CLI for Claude." → 继续 │ └─ 不匹配或不存在 → 拒绝 (500) │ ├─ 检查 metadata.user_id 格式 │ ├─ 匹配 user_{64hex}_account__session_{UUID} → 继续 │ └─ 格式不对或不存在 → 拒绝 (500) │ ├─ (可选) 如有 system[1]，检查 text == "null" │ └─ 转发到上游 Anthropic API → 返回响应 2026-03-20 补充：固定 user_id 被封禁 使用写死的 user_82a10c... 值持续请求后，该 user_id 被 AnyRouter 封禁，所有携带该值的请求返回 403（空响应体）。换用全零 user_id 或随机生成的值即可恢复。 结论 ：AnyRouter 虽然不校验 user_id 的具体内容，但会 对高频使用的固定 user_id 做封禁处理 。代理应每次请求随机生成 user_id 。 2026-03-28 补充：metadata.user_id 格式变更 & session_id 校验 格式变更 metadata.user_id 的格式已从旧的扁平字符串格式变更为 JSON 字符串 格式： 旧格式（已失效，返回 503）： user_{64位hex}_account__session_{UUID} 新格式（当前生效）： "{\"device_id\":\"82a10c807646e5141d2ffcbf5c6d439ee4cfd99d1903617b7b69e3a5c03b1dbf\",\"account_uuid\":\"\",\"session_id\":\"f81a44fc-edfb-40f5-bdd4-f6fd4afbc27c\"}" 字段说明： device_id ：64 位十六进制字符串（SHA-256 哈希） account_uuid ：可为空字符串 session_id ：UUID v4 格式，与请求头 X-Claude-Code-Session-Id 的值一致 session_id 校验测试 # X-Claude-Code-Session-Id 请求头 user_id 中的 session_id 状态码 结论 1 随机 UUID 51ef0c33-... 同一随机值 503 拒绝 2 f81a44fc-edfb-40f5-bdd4-f6fd4afbc27c 同一值 200 通过 结论 AnyRouter 校验 session_id 的具体值 （已于 2026-03-30 变更，见下方补充） 请求头 X-Claude-Code-Session-Id 与 metadata.user_id 中的 session_id 应保持一致 device_id 与 session_id 独立校验测试（2026-03-28） # device_id session_id 状态码 结论 1 随机值 合法固定值 f81a44fc-... 200 device_id 不参与校验 2 合法固定值 82a10c... 随机 UUID 503 session_id 必须合法 3 随机值 随机 UUID 503 同上 2026-03-30 补充：session_id 白名单校验已取消 2026-03-28 确认的 f81a44fc-edfb-40f5-bdd4-f6fd4afbc27c 白名单值一度失效（503）， 但 2026-03-30 测试发现 AnyRouter 已取消 session_id 白名单校验 ，随机 UUID 全部通过： # session_id 状态码 1 28ea2f67-e043-4107-ae5f-cec919bfaa0c （随机） 200 2 67408c8f-96ee-4a6c-91a1-b21683aceb3f （随机） 200 3 0b9ce4f8-f337-4178-901f-fd9dd818acf8 （随机） 200 4 ee785666-9dda-47cb-b49b-445da13cf2a9 （随机） 200 5 9444af14-00d2-45a7-a806-dd4cff63f741 （随机） 200 6 f81a44fc-edfb-40f5-bdd4-f6fd4afbc27c （旧值） 200 结论 ： device_id 和 session_id 均可每次请求随机生成 metadata.user_id 仍须为 JSON 字符串格式（含 device_id 、 account_uuid 、 session_id 三个字段） AnyRouter 的验证现在回归到 仅校验格式，不校验具体值 设计意图推测 AnyRouter 通过检查 Claude Code 特有的 system prompt 和 metadata 格式来识别"Claude Code 请求"， 据此可能提供差异化的路由策略、计费方式或配额管理。验证策略经历了多次变化： 早期：旧格式 user_{64hex}_account__session_{UUID} ，仅校验格式 2026-03-28：新 JSON 格式 user_id ，一度校验 session_id 白名单 2026-03-30：取消白名单，回归仅校验格式 2026-04-09：部分端点/时段出现 session_id 校验回归——随机 session_id 返回 503，使用已验证的固定 session_id 可返回 200。此行为不稳定，可能取决于后端负载或灰度策略。建议代理服务默认使用固定 session_id 以提高成功率。 九、503 请求体验证 — thinking block signature 校验（2026-04-15 确认） 问题背景 一份包含 54 条消息的长对话请求体始终返回 503，而一份仅 2 条消息的新对话请求体正常返回 200。通过系统性排查定位到根因。 根因结论 assistant 消息中 thinking block 的 signature 字段为空时，触发 503。 503 请求体的 msg[46]（assistant 角色）包含一个 thinking block，其 signature 值为空字符串（长度=0）。这是导致 503 的 唯一根因 。 该请求体中所有 thinking block 的 signature 状态： 消息 signature 长度 状态 msg[2] 476 有效 msg[10] 484 有效 msg[16] 5,152 有效 msg[18] 8,872 有效 msg[32] 892 有效 msg[36] 2,792 有效 msg[38] 1,668 有效 msg[40] 596 有效 msg[46] 0 空/缺失 所有有效 signature 的 thinking block 均未触发 503；唯一空 signature 的 msg[46] 是故障点。 验证证据 关键对照表 测试场景 结果 thinking + 空 signature（ "" ） 503 thinking + 假 signature（非空但格式无效） 503 thinking 无 signature 字段 503 无 thinking block 200 完整 54 条消息 + 删除空 signature 的 thinking block 200 消息数量扫描 对原始请求体逐步截取前 N 条消息发送，确认 503 在 msg[46]（即 N=46）处首次以 user 结尾仍返回 503： N=28~45: user 结尾 → 200, assistant 结尾 → 503（API 标准规则） N=46: assistant 结尾 → 503 N=47: assistant 结尾 → 503（含空 signature thinking） N=48: user 结尾 → ❌ 503（首次出现 user 结尾也 503） N=48~54: 全部 503（无论末尾角色） N=48 以 user 结尾却 503，因为 msg[46] 的空 signature thinking block 已包含在内。 修复验证 删除 msg[46] 中的 thinking block（或删除所有空 signature 的 thinking block）后，完整 54 条消息恢复 200： ✅ msg[0:54] 删除空 signature 的 thinking → HTTP 200 回复: 让我先看看之前是否已经有部分输出了。 已排除因素 以下因素经过系统性测试， 确认与 503 无关 ： 可疑因素 测试方法 结果 call_ 前缀的 tool_use ID 替换为 toolu_ 前缀 仍 503 缺失 caller 字段 补全 caller: {"type": "direct"} 仍 503 call_ 前缀 + caller 同时修复 替换前缀 + 补全字段 仍 503 WebSearch 工具（503 有 10 个 tools vs 正常 9 个） 正常请求体 + WebSearch tools 200 请求体大小 缩短 system[2] / tool_result / thinking 内容 仍 503 billing header 差异（cc_version / cch 不同） 互换 system[0] 无影响 is_error: true 的 tool_result 包含/排除均测试 无影响 根因溯源 msg[46]-[50] 同时具备两个来自 OpenAI 兼容后端的特征： call_ 前缀的 tool_use ID（OpenAI 格式，非 Claude 原生 toolu_ 前缀） thinking block 的 signature 为空（OpenAI 兼容代理无法生成 Claude 原生签名） 这表明这些消息来自 OpenAI 兼容代理后端 ，在格式转换过程中 thinking block 的 signature 被丢弃，导致后续请求被拒绝。 次要发现：messages 以 assistant 结尾触发 503 测试过程中发现，messages 数组 以 assistant 角色消息结尾时 也会触发 503。这是 Claude API 的标准规则（messages 末尾必须是 user 角色），但经代理后错误码从 400 变为 503。 末尾角色 状态码 说明 user 200 正常 assistant 503 API 标准规则，代理包装为 503 此为独立问题，与 thinking signature 无关。 修复方案 发送请求前，删除所有 signature 为空的 thinking blocks： for msg in body["messages"]: if msg["role"] == "assistant": content = msg.get("content", []) msg["content"] = [ b for b in content if not (b.get("type") == "thinking" and not b.get("signature")) ] 如果代理服务需要保留 thinking 内容用于上下文，可改为在转发前将空 signature 替换为占位值，但经测试非空但无效的 signature 同样触发 503，因此 删除是最稳妥的方案 。 十、模型下线与切换：claude-opus-4-7 上线（2026-04-17 确认） 变更概述 模型 状态 claude-opus-4-6 已下线 claude-opus-4-7 已上线 （新默认 Opus） 验证方式变化 无变化。 现有验证机制（ anthropic-beta 头、 system[0].text 、 metadata.user_id JSON 格式、 X-Claude-Code-Session-Id 等） 完全复用 ，仅需把 model 字段改为 claude-opus-4-7 。 实测对照表 使用当前最小请求模板（零修改）分别测试： 模型 非流式 流式 响应示例 claude-opus-4-6 400 400 {"error":"claude-opus-4-6 已下线，请切换到 claude-opus-4-7 模型"} claude-opus-4-7 200 200 正常响应 claude-sonnet-4-5 429 — {"error":"Service Unavailable"} （限流，非验证问题） opus-4-6 返回的是 业务层提示 （验证已通过、模型路由拒绝），而非验证失败，可作为"验证机制未变"的旁证。 结论 model 字段值： claude-opus-4-6 → claude-opus-4-7 其余请求头、请求体字段、URL 全部保持不变 十一、Key 级别的可用性校验（2026-04-17 确认） 现象 即使请求体、请求头完全相同，不同 Key 的响应可能差异巨大： Key 状态 非流式响应 流式响应 说明 正常 Key 200 200 完整 SSE 流 / JSON 响应 被封禁/额度耗尽 Key 520 （空响应） 503 {"error":"Service Unavailable"} Cloudflare 层包装 实测同一请求模板： Key A（耗尽）→ 非流式 5/5 次 520 空响应，流式返回 503 Service Unavailable Key B（正常）→ 非流式 3/3 次 200，流式 3/3 次 200 SSE 结论 AnyRouter 对 Key 本身有独立的可用性校验 ，与模型版本、请求格式无关 520 空响应 / 503 Service Unavailable 很可能是 Key 级别问题，而非验证失败或模型下线 排查 520 / 503 时应 优先换用另一个 Key 复测，再排查请求体 状态码含义更新 结合历史结论，当前完整状态码含义： 状态码 含义 排查方向 200 验证通过且响应成功 — 400 验证失败（缺 anthropic-beta / system 错 / user_id 格式错） 或 模型已下线 读取 body 中的 error 提示 403 user_id 固定值被封禁 改为随机生成 user_id 429 限流 降低频率或换 Key 500 （历史）验证失败；现在很少出现 — 503 验证通过但后端不可用 或 Key 不可用（流式模式） 换 Key / 检查 thinking signature 是否为空 520 Cloudflare 上游异常，通常是 Key 不可用（非流式模式） 换 Key 复测 十二、最新最小可用请求模板（2026-04-17） curl https://anyrouter.top/v1/messages \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-xxx" \ -H "anthropic-beta: claude-code-20250219,context-1m-2025-08-07,interleaved-thinking-2025-05-14,redact-thinking-2026-02-12,context-management-2025-06-27,prompt-caching-scope-2026-01-05,advanced-tool-use-2025-11-20,effort-2025-11-24,fast-mode-2026-02-01" \ -H "anthropic-version: 2023-06-01" \ -H "User-Agent: claude-cli/2.1.92 (external, cli)" \ -H "X-Claude-Code-Session-Id: <UUID，与 user_id.session_id 一致>" \ -H "x-app: cli" \ -d '{ "model": "claude-opus-4-7", "max_tokens": 1024, "system": [ {"type": "text", "text": "You are Claude Code, Anthropic'\''s official CLI for Claude."} ], "messages": [ {"role": "user", "content": "Hello"} ], "metadata": { "user_id": "{\"device_id\":\"<64hex>\",\"account_uuid\":\"\",\"session_id\":\"<UUID>\"}" }, "thinking": {"type": "adaptive"}, "output_config": {"effort": "high"}, "speed": "fast" }' 相比文档第七章的"早期最小模板"（仅 Content-Type + x-api-key + 旧格式 user_id ），当前版本新增了多个必需项。早期模板 已失效 ，保留作为历史参考。 演变时间轴 日期 关键变化 2026-03-16 初版测试：仅校验请求体 system[0].text + metadata.user_id （旧扁平格式） 2026-03-20 固定 user_id 被封禁（403），需随机生成 2026-03-28 user_id 格式变更为 JSON 字符串；一度引入 session_id 白名单 2026-03-30 session_id 白名单取消，回归仅校验格式 2026-04-09 部分端点/时段 session_id 校验回归（灰度） 2026-04-11 anthropic-beta 头变为 必需 （必须含 context-1m-2025-08-07 ） 2026-04-15 thinking block 空 signature 触发 503 2026-04-17 claude-opus-4-6 下线， claude-opus-4-7 上线；Key 级可用性差异显著 2026-04-17 确认 thinking 字段是 opus-4-7 必需项 （new-api 后端空指针 panic）， output_config 、 speed 可省略 十三、opus-4-7 请求体字段必需性测试（2026-04-17 确认） 测试背景 代码中 thinking / output_config / speed 三个字段是否都必须携带？针对 claude-opus-4-7 模型，逐个移除测试。 测试方法 以完整请求体为基准，按 7 种组合移除字段，每种测 2 次，观察响应状态码。 测试结果 测试组合 2 次结果 结论 全部保留（基准） 200 / 520* 通过 仅移除 thinking 500 / 500 new-api panic 仅移除 output_config 200 / 520* 可省略 仅移除 speed 200 / 520* 可省略 移除 thinking + output_config 500 / 500 panic 移除 thinking + speed 500 / 500 panic 移除 output_config + speed 200 / 520* 可省略 三个全移除 500 / 500 panic *520 为 Cloudflare 上游偶发错误，与字段无关。 500 panic 错误响应 移除 thinking 后返回的错误： { "error": { "message": "Panic detected, error: runtime error: invalid memory address or nil pointer dereference. Please submit a issue here: https://github.com/Calcium-Ion/new-api", "type": "new_api_panic" } } 结论 字段 必需性 说明 thinking 必需 缺失触发 new-api 后端 panic（非验证失败，是后端代码 bug） output_config 可省略 AnyRouter 不校验 speed 可省略 AnyRouter 不校验 根因分析 ：AnyRouter 验证层本身 不校验 这三个字段，500 来自上游 new-api 的空指针 bug —— 后端代码假定 thinking 字段一定存在而未做 nil 判断。这是 AnyRouter 上游实现缺陷 而非协议要求。 thinking 字段取值语义 "thinking": {"type": "adaptive"} 类型 含义 {"type":"enabled","budget_tokens":N} 旧版：固定 token 预算 {"type":"adaptive"} 新版（推荐） ：模型自适应决定思考深度 {"type":"disabled"} 或缺失 不思考（但对 opus-4-7 会触发 panic） adaptive 让模型根据问题难度自动调节思考量——简单问题少想、复杂问题多想，配合 output_config.effort 的 high/medium/low 共同控制行为。 最小必需请求体（2026-04-17 更新） { "model": "claude-opus-4-7", "max_tokens": 1024, "system": [ {"type": "text", "text": "You are Claude Code, Anthropic's official CLI for Claude."} ], "messages": [{"role": "user", "content": "Hello"}], "metadata": { "user_id": "{\"device_id\":\"<64hex>\",\"account_uuid\":\"\",\"session_id\":\"<UUID>\"}" }, "thinking": {"type": "adaptive"} } 相比第十二章的模板，可安全移除 output_config 和 speed ；但 不可移除 thinking 。 14 个帖子 - 14 位参与者 阅读完整话题
请把我们这次对话整理成一份“学习过程记录”，不要写成只保留结论的总结。 要求： 按照对话推进的先后顺序记录，从我最开始的疑问写到最后问题解决。 保留我的问题演化过程，包括： 最初的问题 中途冒出的新问题 更基础的追问 卡住的地方 理解发生变化的地方 不要把我的问题重写成一篇平滑的教程，要保留“我是怎么一步步学到这里的”这条线。 尽量保留我原本提问的意思和顺序，可以整理语句，但不要改变原意。 每个阶段都写清楚： 我当时在问什么 我为什么会问到这里 关键解释或关键代码点是什么 这个阶段又引出了什么新问题 我在这一阶段学到了什么 如果对话里有代码，要结合代码上下文来写，不要脱离代码空讲概念。 最后单独补一个“最终结论 / 当前理解”，但这个部分只能放在最后，不能代替前面的过程记录。 请按下面格式输出： 学习主题 一句话说明这次主要在学什么 学习起点 我最开始的问题是什么 我当时为什么会问这个问题 学习过程记录 第1阶段 我的问题： 当时的困惑点： 关键解释 / 关键代码点： 引出的新问题： 这一阶段学到了什么： 第2阶段 我的问题： 当时的困惑点： 关键解释 / 关键代码点： 引出的新问题： 这一阶段学到了什么： （按实际对话继续） 关键误区与转折点 列出我中途哪些地方理解错了，后来是怎么被纠正的 最终结论 / 当前理解 用简洁的话总结我最后已经搞懂了什么 仍可继续追问的点 列出这次虽然解决了，但后续值得继续深入的问题 1 个帖子 - 1 位参与者 阅读完整话题
iPhone 13 因为储存空间满了，用了巨魔的清理软件，把所有软件的文稿和数据都清理掉了。 微信有亲人在世的消息内容，和 20 多年来的回忆 误删后，尝试了 i4 助手整机备份数据，但没有文稿数据都没有了。 佬们有什么办法可以恢复吗？ 4 个帖子 - 3 位参与者 阅读完整话题
一、/命令： 新手/powerup 新手教程 /model; /config; /effort; /permissions alt + t 开启当前session是否额外思考 alt+m 权限切换 Esc Esc 回滚状态 /tasks 查看后台任务，运行命令 +& 可以后台测试 /remote-control 远程操控 /teleport 将远程历史结果等拉到本地 /status 查看状态 /context 查看上下文使用情况 /compact 传递指令怎么进行上下文压缩，比如保留xx计划 /diff opens an interactive viewer for uncommitted changes — useful for reviewing what Claude has done before committing. /doctor checks installation health 二、Memory: /init 生成CLAUDE.md; /memory在线修改， CLAUDE.md三级 repo/home/ per-directory overrides 对于较大的项目，可以将指令拆分成 .claude/rules/ .md 文件。规则可以是全局的项目，也可以用 Frontmatter 范围到路径。一条带有路径的规则：src/api/**/ .ts 只有在 Claude 处理匹配文件时才会激活： paths: src/api/**/*.ts --- All API endpoints must validate input with Zod. Return 400 with field-level errors on validation failure. CLAUDE_CODE_NEW_INIT=1; CLAUDE_CODE_DISABLE_AUTO_MEMORY=1; 默认自动维护memory; 记住某件事，就自然地问，比如“记住API测试需要Redis。”如果你想把它写进 CLAUDE.md，可以明确要求Claude把它加进去。 三、Project Setup: 代码开始进行init; CLAUDE.md怎么写： A good `CLAUDE.md` is concise and specific. Aim for under 200 lines per file. Every line should be relevant to nearly every session — if something only matters for one feature, put it in a path-scoped rules file instead. The most valuable sections are: tech stack and versions, development commands (install, test, build, lint), naming conventions that aren’t obvious, and known gotchas that would trip up a new developer. eg: # Project: Payment Service ## Stack - Node.js 20, TypeScript 5, PostgreSQL 15 - Express for API, Prisma for ORM, Jest for tests ## Commands - `npm run dev` — start with hot reload - `npm test` — run test suite - `npm run migrate` — apply pending migrations - `npm run lint` — ESLint + Prettier check ## Conventions - All monetary values stored as integers (cents) - Use `Result<T, E>` pattern for error handling, never throw in service layer - Database columns: snake_case; TypeScript: camelCase 三层配置文件： .claude/settings.local.json, .claude/settings.json, ~/.claude/settings.json 四、Commands in Depth 进阶命令 当上下文不够时组合命令： /context /compact focus on the auth refactor /branch /rename auth-refactor-v2 /export auth-refactor-v2.md claude code 内置skills： /simplify：指的是对最近修改的文件进行代码质量审查，同时启动多个并行的审查代理，每个代理专注于不同的审查方面（如安全性、性能、可读性等）。 /batch <instruction>： 对大量文件进行大规模修改，会先规划工作流程，确保变更有序进行。使用隔离的 Git 工作树，以避免对主分支造成干扰，确保操作安全。能够协调验证过程，并支持以拉取请求（PR）为导向的后续跟进，提高协作效率。 /loop 5m check deploy status：以5分钟为间隔周期性执行“检查部署状态”的操作。 会按设定的时间间隔反复运行一个提示或检查任务。 这种重复检查机制特别适用于监控耗时较长的后台操作（如部署、构建等）的状态变化。 /debug：该命令用于启用详细日志记录，帮助诊断Claude行为或工具使用过程中出现的问题。 /claude-api：该命令用于加载项目所用语言的Anthropic SDK参考文档，当检测到项目中导入了@anthropic-ai/sdk或Python的anthropic包时会自动激活。 eg: /simplify /batch add JSDoc comments to all public functions in src/ /loop 2m check if the build finished /debug Fast Mode 使 Claude Opus 4.6 的速度约为 2.5 倍，但token更多；不会降低质量，有次数限制，但/effort会降低质量；{快速模式符号↯} eg: /fast # toggle on/off /fast on # explicitly enable /fast off # explicitly disable 五、快捷键： Ctrl+O ：实时查看工具调用和思考步骤 /btw：用于提出一个附加问题或补充信息，不会将其加入对话历史，适合用于核实事实或询问语法细节，避免干扰当前对话上下文。 Ctrl+B：将正在运行的bash命令或代理任务置于后台执行，使用户可以在不中断任务的情况下继续向Claude发出其他指令。 Ctrl+X Ctrl+K：官方快捷键，用于终止所有在后台运行的代理任务 /insights :生成会话分析报告，包含统计数据，说明已完成的任务。 六、Skills .claude/skills/code-review/ ├── SKILL.md # Instructions (required) ├── templates/ │ └── review-checklist.md └── scripts/ └── analyze-metrics.py 技能描述存储：上下文1%+8000字符；更多通过辅助文件引入：比如 For the full review checklist, see [templates/review-checklist.md](templates/review-checklist.md). SKILL.md 通过bash读入，不超过500行，超过的建议加到单个文件中引入； ！command 举例： name: pr-summary description: Summarize pull request changes. Use when asked to review or summarize a PR. context: fork agent: Explore --- ## PR context - Diff: !`gh pr diff` - Comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` Summarize the intent and key changes in this pull request. 技能调用： disable-model-invocation: true； 模型不能自动调用skill，deploys, pushes, sends等操作 user-invocable: false，用户不调用，让模型调用 paths: 接受一个 YAML 格式的通配符列表，用于限定技能适用的范围。工作目录匹配这些通配符时，技能才会被加载 eg： --- name: api-generator description: Generate REST API endpoints from schema definitions. paths: ["src/**/*.ts", "tests/**"] --- 七、Hooks 定义： 在 Claude Code 会话中特定事件触发时自动执行的脚本，用于响应系统事件并执行预设操作。 它们通过标准输入（stdin）接收 JSON 格式的输入数据，以便获取事件相关信息。 它们通过退出码和标准输出（stdout）返回 JSON 格式的执行结果，实现与系统通信。 钩子架构与配置 钩子在设置文件中通过一个名为 hooks 的键进行配置。 每个事件都包含一个匹配器数组，每个匹配器又包含一个钩子定义数组。 匹配器字段是一个正则表达式模式，用于匹配工具名称——‘Bash’ 仅精确匹配该工具名，‘Write|Edit’ 匹配其中任意一个，‘ ’ 匹配所有工具，'mcp__github__. ’ 匹配所有以 mcp__github__ 开头的 GitHub MCP 工具。 eg： { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"", "timeout": 10 } ] } ] } } Matchers也支持一个条件性的if字段（v2.1.85），该字段使用权限规则语法进一步过滤钩子触发的时机。 虽然matcher通过名称选择工具，但if可将范围缩小到该工具的特定调用。 当您只关注工具调用的子集时这很有用——例如，仅拦截git push命令而不对每次Bash调用都执行操作。 eg: { "hooks": { "PreToolUse": [ { "matcher": "Bash", "if": "Bash(git push*)", "hooks": [ { "type": "command", "command": "/path/to/check-push.sh" } ] } ] } } Claude Code 支持30多个钩子事件。日常工作中最有用的有： PreToolUse（在工具运行前进行验证，可阻止执行） PostToolUse（在工具执行后观察或响应，可添加上下文） UserPromptSubmit（在 Claude 处理用户输入前拦截输入） Stop（在 Claude 完成响应时执行检查） (PermissionRequest), 还有用于权限处理的事件 notifications, 通知事件 subagent lifecycle (SubagentStart, SubagentStop)子代理生命周期事件； failures (PostToolUseFailure, StopFailure)，故障事件 config changes, 配置变更事件； file watching (FileChanged) 文件监视事件； context compaction (PreCompact, PostCompact), 上下文压缩事件； worktree management 工作树管理事件。 多个新事件扩展了钩子可响应的范围。 CwdChanged（v2.1.83）在工作目录变更时触发，支持类似 direnv 的动态环境管理——例如，当 Claude 进入项目目录时自动加载环境变量。 TaskCreated（v2.1.84）在使用 TaskCreate 工具时触发，可用于记录或验证新任务的创建。 WorktreeCreate（v2.1.84）在创建工作树代理时触发，并支持 type: ‘http’ 类型的远程通知——适用于在并行工作开始时向外部服务发送警报。 Elicitation（v2.1.76）在 MCP 服务器通过交互式对话请求任务中的结构化用户输入时触发，可拦截并修改该请求内容，在展示给用户前进行调整。 ElicitationResult（v2.1.76）在用户对 MCP 的 elicitation 响应后触发，可拦截并覆盖响应内容，在发送回 MCP 服务器前进行修改。 “PreCompact” 是一个事件名称，指在 Claude Code 执行对话压缩以释放上下文空间之前触发的钩子事件。 它在压缩操作正式开始前运行，允许开发者或系统在关键时刻介入处理。 该事件可用于阻止压缩操作的进行，例如当需要保存当前状态、向用户发出警告或拒绝可能丢失关键信息的自动压缩时。 事件的 matcher 字段用于判断触发原因：当值为 ‘manual’ 时表示用户手动执行了 /compact 命令；当值为 ‘auto’ 时表示系统因上下文容量已满而自动触发了压缩。 若要阻止压缩发生，可通过返回退出码 2 或使用 JSON 决策负载（payload）来实现，例如： { "hooks": { "PreCompact": [ { "matcher": "auto", "hooks": [ { "type": "command", "command": "./scripts/snapshot-context.sh" } ] } ] } } 钩子返回： {"decision": "block", "reason": "active refactor in flight"} 钩子脚本通过 stdin 接收 JSON。Python 钩子的读法是这样的： import json, sys data = json.load(sys.stdin) tool_name = data.get("tool_name", "") tool_input = data.get("tool_input", {}) 退出码0表示成功，需从标准输出（stdout）中解析JSON格式的输出结果。 退出码2表示阻断性错误，Claude会停止运行，并显示你标准错误（stderr）中的信息。 其他任何退出码均表示非阻断性警告，仅在详细模式（verbose mode）下显示。 钩子（Hook）的常见分类和典型应用方式 在执行写入或编辑操作后触发的 工具使用后钩子 ，用于自动化后续处理。 系统会自动调用指定的格式化程序来整理内容。 确保 Claude 的输出始终整洁，表示无论用户输入如何，最终输出都会保持良好的排版和结构。 eg： #!/bin/bash INPUT=$(cat) FILE=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('file_path',''))") case "$FILE" in *.ts|*.tsx|*.js) prettier --write "$FILE" 2>/dev/null ;; *.py) black "$FILE" 2>/dev/null ;; *.go) gofmt -w "$FILE" 2>/dev/null ;; esac exit 0 安全扫描在写入时使用PostToolUse和additionalContext输出警告Claude关于它刚刚写入的可能机密信息, 例如 SECRET_PATTERNS = [ (r"api[_-]?key\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded API key"), (r"password\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded password"), ] # ... check content, then: output = {"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": f"Security warnings: {'; '.join(warnings)}"}} print(json.dumps(output)) 使用PreToolUse和正则表达式检查以及退出代码2来阻止危险命令： BLOCKED = [(r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf /")] for pattern, message in BLOCKED: if re.search(pattern, command): print(message, file=sys.stderr) sys.exit(2) Advanced: Prompt Hooks and Component Scope 提示钩子和作用域 prompt 钩子 对于 Stop 和 SubagentStop 停止事件， prompt 类型的钩子使用LLM来评估任务完成情况。LLM阅读对话并返回一个关于是否让Claude停止或继续工作的结构化决策。这对于具有明确完成标准的工作任务来说非常强大。 eg： { "hooks": { "Stop": [ { "hooks": [ { "type": "prompt", "prompt": "Check: 1) Were all files modified? 2) Do tests pass? 3) Is the PR description updated? If anything is missing, explain what.", "timeout": 30 } ] } ] } } agent 钩子 钩子类型 “agent” 会派生一个子代理进行评估——与提示钩子（单轮）不同，代理钩子可以使用工具并执行多步推理。当检查需要读取文件或运行命令时使用此功能。 钩子也可以通过hooks frontmatter字段针对单个技能和代理进行范围限定。一个技能的前置工具使用钩子仅在执行该技能时触发： eg: --- name: production-deploy hooks: PreToolUse: - matcher: "Bash" hooks: - type: command command: "./scripts/production-safety-check.sh" once: true --- once ： true : 只在会话中运行一次钩子，而不是在每次匹配工具使用时都运行。这对于只需要发生一次的设置检查很有用。 2 个帖子 - 1 位参与者 阅读完整话题