Files
wehub-resource-sync 0f3d4f9f7e
CI / lint (push) Waiting to run
CI / changes (push) Waiting to run
CI / swift-test-macos (2, 0) (push) Blocked by required conditions
CI / swift-test-macos (2, 1) (push) Blocked by required conditions
CI / lint-build-test (push) Blocked by required conditions
CI / build-linux-cli (linux-arm64, ubuntu-24.04-arm) (push) Waiting to run
CI / build-linux-cli (linux-x64, ubuntu-24.04) (push) Waiting to run
docs: make Chinese README the default
2026-07-13 10:12:34 +00:00

260 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理,属于社区翻译,非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/steipete/CodexBar) · [上游 README](https://github.com/steipete/CodexBar/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# CodexBar 🎚️ — 愿你的 token 永不枯竭。
> 所有 AI 编程额度限制,尽在你的菜单栏。
[![Latest release](https://img.shields.io/github/v/release/steipete/CodexBar?style=flat-square&color=0a0a0c)](https://github.com/steipete/CodexBar/releases/latest)
[![macOS 14+](https://img.shields.io/badge/macOS-14%2B-0a0a0c?style=flat-square)](https://github.com/steipete/CodexBar/releases/latest)
[![Homebrew](https://img.shields.io/badge/brew-steipete%2Ftap%2Fcodexbar-orange?style=flat-square)](https://github.com/steipete/homebrew-tap)
[![AUR](https://img.shields.io/aur/version/codexbar-cli?style=flat-square&color=1793d1)](https://aur.archlinux.org/packages/codexbar-cli)
[![License: MIT](https://img.shields.io/badge/license-MIT-6e5aff?style=flat-square)](LICENSE)
[![Site](https://img.shields.io/badge/site-codexbar.app-16d3b4?style=flat-square)](https://codexbar.app)
<a href="https://codexbar.app"><img src="docs/social.png" alt="CodexBar — 所有 AI 编程额度限制尽在菜单栏。59 个提供商。" width="100%" /></a>
一款轻量的 macOS 14+ 菜单栏应用,可让 **AI 编程提供商的额度限制** 始终可见,并显示各窗口何时重置。支持 Codex、OpenAI、Claude、Cursor、Gemini、Copilot、Grok、GroqCloud、ElevenLabs、Deepgram、z.ai、MiniMax、Kiro、Zed、Vertex AI、Augment、OpenRouter、LiteLLM、LLM Proxy、Codebuff、Command Code、AWS Bedrock 以及许多较新的编程提供商。每个提供商一个状态项,或使用带提供商切换器的 Merge Icons 模式。无 Dock 图标,极简 UI,动态菜单栏图标。
<img src="docs/codexbar.png" alt="CodexBar 菜单弹出面板,含提供商磁贴、用量进度条与重置倒计时" width="520" />
## 为何使用
- **围绕重置周期做计划。** 按提供商显示会话、每周与每月窗口,并倒计时至下次重置——不再猜测是否该启动那项耗时任务。
- **积分、支出与成本扫描。** 积分余额、Admin API 支出仪表盘、提供商账单摘要,以及在数据源暴露足够细节时的本地成本扫描。
- **实时状态。** 提供商状态轮询在菜单中显示事故徽章,并在菜单栏图标上叠加指示器。
- **隐私优先。** 复用现有提供商会话——OAuth、设备流、API 密钥、浏览器 Cookie、本地文件——因此不存储密码。
## 安装
### 系统要求
- macOS 14+ (Sonoma)
### GitHub Releases
下载:<https://github.com/steipete/CodexBar/releases>
### Homebrew
```bash
brew install --cask codexbar
```
### CLI 压缩包(macOS/Linux
Homebrew formula(目前支持 Linux):
```bash
brew install steipete/tap/codexbar
```
Arch Linux AUR 软件包:
```bash
yay -S codexbar-cli
```
或从 GitHub Releases 下载发布版压缩包:
- macOS: `CodexBarCLI-v<tag>-macos-arm64.tar.gz`, `CodexBarCLI-v<tag>-macos-x86_64.tar.gz`
- Linux (glibc): `CodexBarCLI-v<tag>-linux-aarch64.tar.gz`, `CodexBarCLI-v<tag>-linux-x86_64.tar.gz`
- Linux (static musl): `CodexBarCLI-v<tag>-linux-musl-aarch64.tar.gz`, `CodexBarCLI-v<tag>-linux-musl-x86_64.tar.gz`
### 首次运行
- 打开「设置 → 提供商」,启用你使用的提供商。
- 安装/登录你所依赖的提供商数据源:CLI、浏览器会话、OAuth/设备流、API 密钥、本地应用文件或提供商应用,具体取决于提供商。
- 可选:设置 → 提供商 → Codex → OpenAI cookies(自动或手动),以添加仪表盘增强功能。
### 从 CLI 设置 API 密钥
提供商开关与 API 密钥保存在已解析的 CodexBar 配置文件中。新安装使用
`~/.config/codexbar/config.json`;已有的 `~/.codexbar/config.json` 安装仍从旧路径加载。你可以
编写脚本,使用与「设置 → 提供商」相同的提供商列表:
```bash
codexbar config providers
codexbar config enable --provider grok
codexbar config disable --provider cursor
```
对于 API 密钥类提供商,无需打开设置即可存储密钥:
```bash
printf '%s' "$ELEVENLABS_API_KEY" | codexbar config set-api-key --provider elevenlabs --stdin
```
`set-api-key` 会修剪管道传入的值,以受限的配置文件权限存储,并默认启用该提供商。使用 `--no-enable` 仅保存密钥,或使用 `--api-key <key>` 用于一次性本地脚本(无需担心 shell 历史记录)。
完整流程请参阅 [CLI 配置](docs/cli-configuration.md)。
## 提供商
- [Codex](docs/codex.md) — OAuth API 或本地 Codex CLI,另可选 OpenAI 网页仪表盘增强功能。
- [OpenAI](docs/openai.md) — 使用 Admin API 密钥的用量/成本图表,并回退到旧版积分余额。
- [Azure OpenAI](docs/azure-openai.md) — API 密钥、端点与部署校验探测。
- [Claude](docs/claude.md) — OAuth API、浏览器 Cookie 或 CLI PTY 回退;在可用时显示会话与周用量。
- [Cursor](docs/cursor.md) — 浏览器会话 Cookie,用于套餐、用量与账单重置。
- [OpenCode](docs/opencode.md) — 浏览器 Cookie,用于工作区订阅用量。
- [OpenCode Go](docs/opencode.md) — 浏览器或本地 SQLite 数据,用于 Go 用量窗口。
- [Alibaba Coding Plan](docs/alibaba-coding-plan.md) — 网页 Cookie 或 API 密钥,用于编码计划配额。
- [Alibaba Token Plan](docs/alibaba-token-plan.md) — 百炼浏览器/手动 Cookie,用于 token 计划积分。
- [Gemini](docs/gemini.md) — 基于 OAuth 的配额 API,使用 Gemini CLI 凭据(无需浏览器 Cookie)。
- [Antigravity](docs/antigravity.md) — 本地 language server 探测(实验性);无需外部认证。
- [Droid](docs/factory.md) — 浏览器 Cookie + WorkOS token 流程,用于 Factory 用量与账单。
- [Copilot](docs/copilot.md) — GitHub 设备流 + Copilot 内部用量 API。
- [Devin](docs/devin.md) — Chrome localStorage 会话或手动 Bearer token,用于每日与每周配额。
- [z.ai](docs/zai.md) — API token,用于个人/团队配额、MCP、5 小时与按小时用量窗口。
- [Manus](docs/manus.md) — 浏览器 `session_id` 认证,用于积分余额、月度积分与每日刷新跟踪。
- [MiniMax](docs/minimax.md) — API token、Cookie 标头或浏览器 Cookie,用于编码计划用量。
- [T3 Chat](docs/t3chat.md) — 捕获浏览器 Cookie,用于 Base 与 Overage 用量桶。
- [Kimi](docs/kimi.md) — 认证 token(来自 `kimi-auth` Cookie 的 JWT),用于每周配额 + 5‑小时速率限制。
- [Kimi K2(非官方)](docs/kimi-k2.md) — 旧版 API 密钥流程,用于基于积分的用量总计。
- [Kilo](docs/kilo.md) — API tokenCLI 认证回退,用于 Kilo Pass 用量。
- [Kiro](docs/kiro.md) — 基于 CLI 的用量;月度积分 + 奖励积分。
- [Vertex AI](docs/vertexai.md) — Google Cloud gcloud OAuth,从本地 Claude 日志跟踪 token 成本。
- [Augment](docs/augment.md) — Augment CLI 或浏览器 Cookie,用于积分跟踪与用量监控。
- [Amp](docs/amp.md) — 基于浏览器 Cookie 的认证,跟踪 Amp Free 用量。
- [Ollama](docs/ollama.md) — API 密钥访问,外加浏览器 Cookie,用于 Ollama Cloud 用量窗口。
- [Synthetic](docs/synthetic.md) — API 密钥配额端点,用于滚动 5 小时、每周 token 与搜索按小时用量。
- [JetBrains AI](docs/jetbrains.md) — 来自 JetBrains IDE 配置的本地 XML 配额;月度积分跟踪。
- [Warp](docs/warp.md) — API token,用于 GraphQL 请求限制与月度积分。
- [ElevenLabs](docs/elevenlabs.md) — API 密钥,用于字符积分与语音位用量。
- [OpenRouter](docs/openrouter.md) — API token,用于跨多个 AI 提供商的基于积分的用量跟踪。
- [CrossModel](docs/crossmodel.md) — API 密钥钱包余额,含每日、每周与每月支出。
- [Windsurf](docs/windsurf.md) — 导入浏览器 localStorage 会话或本地 SQLite 缓存,用于套餐用量。
- [Zed](docs/zed.md) — Zed 编辑器 Keychain 会话,用于套餐、编辑预测配额、账单周期与逾期发票。
- [Perplexity](docs/perplexity.md) — 来自 Perplexity 用量数据的账户用量积分。
- [Xiaomi MiMo](docs/mimo.md) — 浏览器 Cookie,用于余额与 token 计划用量。
- [Doubao](docs/doubao.md) — API 密钥,用于火山引擎 Ark 请求限制探测。
- [Sakana AI](docs/sakana.md) — 手动 Cookie 标头,用于 5 小时与每周配额窗口。
- [Abacus AI](docs/abacus.md) — 浏览器 Cookie 认证,用于 ChatLLM/RouteLLM 计算积分跟踪。
- [Mistral](docs/mistral.md) — 浏览器 Cookie,用于 API 支出、积分余额与月度套餐用量。
- [DeepSeek](docs/deepseek.md) — API 密钥,用于积分余额跟踪(付费 vs. 赠送明细)。
- [Moonshot / Kimi API](docs/moonshot.md) — API 密钥,用于 Moonshot/Kimi API 账户余额跟踪。
- [Venice](docs/venice.md) — API 密钥,用于 DIEM 或 USD 余额跟踪。
- [Codebuff](docs/codebuff.md) — API token(或 `~/.config/manicode/credentials.json`),用于积分余额 + 每周速率限制。
- [Crof](docs/crof.md) — API 密钥,用于美元积分余额与请求配额跟踪。
- [Command Code](docs/command-code.md) — 浏览器或手动 Cookie,用于 Command Code 账单的月度 USD 积分。
- [Qoder](docs/qoder.md) — 浏览器或手动 Cookie,用于 Qoder 大模型积分用量。
- [StepFun](docs/stepfun.md) — 用户名 + 密码登录,用于 Step Plan 速率限制(5 小时 + 每周窗口)与订阅套餐名称。
- [AWS Bedrock](docs/bedrock.md) — AWS 访问密钥或命名 AWS profile(通过 AWS CLI 的 SSO/assume-role),用于 Cost Explorer 支出、月度预算与可选 CloudWatch Claude 活动。
- [Grok](docs/grok.md) — Grok CLI 账单 RPC,外加 grok.com 浏览器会话回退。
- [GroqCloud](docs/groqcloud.md) — API 密钥,用于 Enterprise Prometheus 请求/token/缓存命中指标。
- [LLM Proxy](docs/llm-proxy.md) — API 密钥 + base URL,用于聚合代理配额统计与提供商明细。
- [ClawRouter](docs/clawrouter.md) — API 密钥,用于月度预算、支出、请求、token 与路由提供商用量。
- [sub2api](docs/sub2api.md) — 自托管网关密钥配额、订阅限制、钱包余额与按密钥用量。
- [Wayfinder](docs/wayfinder.md) — 本地路由器网关轮询,用于健康状态、按路由明细、节省与决策延迟。
- [LiteLLM](docs/litellm.md) — 虚拟密钥 + 代理 URL,用于个人与团队预算/支出跟踪。
- [Deepgram](docs/deepgram.md) — API 密钥用量摘要,涵盖语音、agent、token 与 TTS 指标。
- [Poe](docs/poe.md) — API 密钥,用于当前积分余额与近期积分历史。
- [Chutes](docs/chutes.md) — API 密钥,用于订阅用量、滚动与月度配额窗口,以及按量付费配额。
- 欢迎新增提供商:[提供商编写指南](docs/provider.md)。
## Icon & Screenshot
菜单栏图标是一个小巧的用量指示器。条形图的含义因提供商(provider)而异;错误或过期数据会使图标变暗或显示事件指示器。
## Features
- 多提供商菜单栏,支持按提供商单独开关(Settings → Providers)。
- 各提供商专用用量指示器,带重置倒计时。
- 可选 Codex 网页仪表板增强(代码审查剩余次数、用量明细、额度历史)。
- 针对 OpenAI、Claude Admin API、OpenRouter、LiteLLM、z.ai、MiniMax、Mistral 和 AWS Bedrock 等 API 提供商的内联支出与用量图表。
- 可配置的 Codex + Claude 成本用量扫描,并为支持的提供商历史复用图表 UI。
- 提供商状态轮询,在菜单和图标叠层中显示事件徽章。
- Merge Icons 模式,将多个提供商合并为一个状态项 + 切换器。
- 显示控制:提供商图标、标签、条形图、重置时间样式,以及最高用量自动选择。
- 刷新频率预设(手动、1m、2m、5m、15m)。
- 内置 CLI`codexbar`),用于脚本和 CI(本地成本用量可使用 `codexbar cost --provider codex``claude``both`);提供 macOS 和 Linux CLI 构建。
- 为支持的提供商提供 WidgetKit 小组件。
- 应用和网站本地化,共享 21 种语言目录,支持自动网站检测、持久化选择器和 RTL。
- 可选会话配额通知和每周重置 confetti 庆祝效果。
- 隐私优先:默认在设备端解析;浏览器 cookie 需主动启用并复用(不存储密码)。
## Privacy note
担心 CodexBar 会扫描你的磁盘吗?它不会遍历文件系统;在相关功能启用时,只会读取少量已知位置(浏览器 cookie/本地存储、提供商配置文件、本地 JSONL 日志)。提供商令牌和令牌账户设置保存在 CodexBar 配置文件中,并采用严格的文件权限。讨论与审计说明见 [issue #12](https://github.com/steipete/CodexBar/issues/12).
## macOS permissions (why they're needed)
- **Full Disk Access(可选)**:仅在为基于网页的提供商读取 Safari cookie/本地存储时需要。若不授予,可改用其他受支持浏览器、手动 cookie/API 密钥、OAuth,或该提供商支持的 CLI/本地数据源。
- **Keychain 访问(由 macOS 提示)**
- Chromium cookie 导入需要浏览器的 “Safe Storage” 密钥来解密 cookie。
- 当 CodexBar 没有可用缓存凭据时,Claude OAuth 引导可能会读取 Claude CLI 的 Keychain 条目。
- CodexBar 可能将 Keychain 用于浏览器 cookie 解密、缓存的 cookie 标头,以及 OAuth/设备流凭据(当这些数据源需要时)。
- **如何阻止这些 Keychain 弹窗?**
- 打开 **Keychain Access.app** → 登录钥匙串 → 搜索被提示的条目(Claude OAuth 通常为 “Claude Code-credentials”)。
- 打开该条目 → **Access Control** → 在 “Always allow access by these applications” 下添加 `CodexBar.app`
- 建议仅添加 CodexBar(除非你希望完全放开,否则避免 “Allow all applications”)。
- 保存后重新启动 CodexBar。
- 参考截图:![Keychain access control](docs/keychain-allow.png)
- **如何对浏览器做同样设置?**
- 找到浏览器的 “Safe Storage” 密钥(例如 “Chrome Safe Storage”、“Brave Safe Storage”、“Microsoft Edge Safe Storage”)。
- 打开该条目 → **Access Control** → 在 “Always allow access by these applications” 下添加 `CodexBar.app`
- 这样 CodexBar 解密该浏览器 cookie 时就不会再弹窗。
- **最后手段——彻底停止所有 Keychain 读取**:若 “Always Allow” 无法持久(例如 Chromium 更新或 `partition_id` 重置后 macOS 会重置 ACL),打开 **CodexBar → Settings → Advanced → Keychain access** 并启用 **Disable Keychain access**。CodexBar 将不再访问 Keychain。基于浏览器 cookie 的提供商会被跳过,但通过 CLI 的 Claude/Codex OAuth 仍可用(它读取 `~/.codex` / `~/.claude` 配置文件,而非 Keychain)。
- **卸载后仍弹窗?** 删除应用会阻止从该 bundle 再次启动,但已在运行的 CodexBar 进程可能继续请求 Keychain 访问,直到退出。请检查该进程、登录项、另一份已安装副本,或弹窗中是否指向不同的请求二进制/路径。安全排查及支持报告中应包含哪些信息(无需泄露密钥),见 [Keychain prompt troubleshooting](docs/keychain-prompts.md)。
- **Files & Folders 提示(文件夹/卷访问)**:CodexBar 会为部分提供商启动提供商 CLI 和本地探测。若这些辅助程序读取项目目录或外置磁盘,macOS 可能要求 CodexBar 访问该文件夹/卷(例如 Desktop 或外置卷)。这由辅助程序的工作目录驱动,而非后台磁盘扫描。
- **我们不会在后台请求的内容**:不请求屏幕录制或辅助功能权限;用户触发的辅助操作可能要求 macOS 授予自动化权限以打开 Terminal。不存储密码(在你主动启用时会复用浏览器 cookie)。
## Docs
- 提供商概览:[docs/providers.md](docs/providers.md)
- 提供商编写指南:[docs/provider.md](docs/provider.md)
- Issue 标签指南:[docs/ISSUE_LABELING.md](docs/ISSUE_LABELING.md)
- UI 与图标说明:[docs/ui.md](docs/ui.md)
- CLI 参考:[docs/cli.md](docs/cli.md)
- 配置:[docs/configuration.md](docs/configuration.md)
- Keychain 弹窗:[docs/keychain-prompts.md](docs/keychain-prompts.md)
- CLI 配置:[docs/cli-configuration.md](docs/cli-configuration.md)
- 小组件:[docs/widgets.md](docs/widgets.md)
- 架构:[docs/architecture.md](docs/architecture.md)
- 刷新循环:[docs/refresh-loop.md](docs/refresh-loop.md)
- 状态轮询:[docs/status.md](docs/status.md)
- Sparkle 更新:[docs/sparkle.md](docs/sparkle.md)
- 打包:[docs/packaging.md](docs/packaging.md)
- 开发:[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
- 发布清单:[docs/RELEASING.md](docs/RELEASING.md)
- 更新日志:[CHANGELOG.md](CHANGELOG.md)
## Getting started (dev)
- 克隆仓库并在 Xcode 中打开,或直接运行脚本。
- 启动一次后,在 Settings → Providers 中切换提供商。
- 安装/登录你依赖的提供商数据源(CLI、浏览器 cookie、OAuth/设备流、API 密钥,或本地应用/配置文件)。
- 可选:为 Codex 仪表板增强功能设置 OpenAI cookieAutomatic 或 Manual)。
## Build from source
需要 macOS 14+ 和 Swift 6.2+。
```bash
./Scripts/package_app.sh # builds CodexBar.app in-place with ad-hoc signing
open CodexBar.app
```
Dev loop:
```bash
./Scripts/compile_and_run.sh
./Scripts/compile_and_run.sh --test # also run the sharded test suite before packaging/relaunching
make check # SwiftFormat + SwiftLint
make docs-list # list docs with frontmatter summaries
```
CLI install:
```bash
# after installing CodexBar.app in /Applications
./bin/install-codexbar-cli.sh
```
## Related
- ✂️ [Trimmy](https://github.com/steipete/Trimmy) — “Paste once, run once.” 将多行 shell 片段压平,便于粘贴并运行。
- 🧳 [MCPorter](https://mcporter.dev) — 面向 Model Context Protocol 服务器的 TypeScript 工具包 + CLI。
- 🧿 [oracle](https://askoracle.dev) — 卡住时问问 oracle。使用自定义上下文和文件调用 GPT-5 Pro。
## Looking for a Windows version?
- [Win-CodexBar](https://github.com/Finesssee/Win-CodexBar)
## Linux desktop integration?
- [codexbar-waybar](https://github.com/Marouan-chak/codexbar-waybar) — Waybar 自定义模块 + GTK4 弹出层,适用于 Hyprland / Sway / 其他 Wayland 合成器,基于内置 Linux CLI 构建。
- [Codexbar GNOME](https://extensions.gnome.org/extension/9841/codexbar/) — GNOME Shell 扩展,将 CodexBar 用量显示到桌面面板。
- [codexbar-cinnamon-applet](https://github.com/jacobcalvert/codexbar-cinnamon-applet) — Linux Mint Cinnamon 面板小程序,由 CodexBar 的 JSON 输出驱动。
- [noctalia-codex-usage](https://github.com/rayoplateado/noctalia-codex-usage) — Noctalia/Quickshell 插件,显示 Codex 5 小时与每周用量上限,基于内置 Linux CLI 构建。
- [KodexBar](https://github.com/tylxr59/KodexBar) — KDE Plasma 小组件,在 Plasma 面板中显示 CodexBar 用量,基于内置 Linux CLI 构建。
- [codexbar-plasmoid](https://github.com/psimaker/codexbar-plasmoid) — KDE Plasma 6 小组件,展示 CodexBar 的计量图标、提供商切换器、配额窗口、节奏、额度、本地成本与状态,由内置 Linux CLI 驱动。
## 状态栏与终端集成
- [showy-quota](https://github.com/enieuwy/showy-quota) — 为 SketchyBar、tmux 和 Zellij 提供常驻 AI 套餐配额条(独立 WASM 插件),基于 `codexbar serve` / 捆绑 CLI 构建。
## 致谢
受 [ccusage](https://github.com/ryoppippi/ccusage) (MIT) 启发,尤其是其成本用量追踪功能。
## 许可证
MIT • Peter Steinberger ([steipete](https://twitter.com/steipete))