Linux Mint Cinnamon 面板显示 Codex 额度：CodexBar 配置记录

在 Linux Mint Cinnamon 面板中接入 CodexBar CLI，通过已登录的 Codex CLI 显示 ChatGPT Plus/Pro 的 Codex 周额度、重置时间和账户状态。

July 29, 2026

10 mins

1984 words

Loading views

Linux Mint Cinnamon Codex CodexBar 桌面环境自动化

一、目标h2

这次要实现的效果很简单：在 Linux Mint Cinnamon 面板上直接显示 Codex 使用额度，不需要每次进入 Codex CLI 再手动查看。

最终调用链如下：

Cinnamon 面板插件
└─ ~/.local/bin/codexbar-cinnamon
   └─ ~/.local/bin/codexbar
      └─ --source cli
         └─ 调用已登录的 Codex CLI
            └─ 读取 ChatGPT Plus / Pro 的 Codex 额度

最终配置：

CodexBar command path
└─ /home/your-user/.local/bin/codexbar-cinnamon

Provider
└─ codex

Refresh interval
└─ 120 秒

这里的 your-user 需要替换为自己的 Linux 用户名。

二、前置条件h2

需要已经安装并登录 Codex CLI。

检查 Codex CLI：

command -v codex
codex --version

启动 Codex：

codex

进入后可以执行：

/status

检查认证文件是否存在：

test -f ~/.codex/auth.json \
  && echo "Codex 已登录" \
  || echo "未找到 Codex 登录信息"

注意：

~/.codex/auth.json

这个文件包含登录认证信息，不要发给别人，也不建议执行：

cat ~/.codex/auth.json

三、安装 CodexBar CLIh2

本文将 CLI 安装到：

~/.local/bin/codexbar

3.1 安装基础工具h3

sudo apt update
sudo apt install -y curl jq tar git

mkdir -p ~/.local/bin

3.2 获取最新版h3

cd /tmp

TAG=$(
  curl -fsSL \
    https://api.github.com/repos/steipete/CodexBar/releases/latest |
  jq -r '.tag_name'
)

case "$(uname -m)" in
  x86_64)
    ARCH="x86_64"
    ;;
  aarch64|arm64)
    ARCH="aarch64"
    ;;
  *)
    echo "不支持的架构：$(uname -m)"
    exit 1
    ;;
esac

FILE="CodexBarCLI-${TAG}-linux-${ARCH}.tar.gz"

echo "版本：$TAG"
echo "文件：$FILE"

3.3 下载并解压h3

curl -fLO \
  "https://github.com/steipete/CodexBar/releases/download/${TAG}/${FILE}"

rm -rf /tmp/codexbar-install
mkdir -p /tmp/codexbar-install

tar -xzf "$FILE" -C /tmp/codexbar-install

查找可执行文件：

CODEXBAR_BIN=$(
  find /tmp/codexbar-install \
    -type f \
    -name CodexBarCLI \
    -print \
    -quit
)

test -n "$CODEXBAR_BIN" || {
  echo "没有找到 CodexBarCLI"
  exit 1
}

安装：

install -m 0755 \
  "$CODEXBAR_BIN" \
  ~/.local/bin/codexbar

验证：

~/.local/bin/codexbar --version

四、验证 CodexBar 读取额度h2

普通文本输出：

~/.local/bin/codexbar usage \
  --provider codex \
  --source cli

示例输出：

== Codex 0.x.x (codex-cli) ==
Weekly: 44% left [=====-------]
Pace: 9% in deficit | Expected 47% used | Runs out in 2d 13h
Resets in 3d 17h
Credits: 0 left
Account: user@example.com
Plan: Plus

JSON 输出：

~/.local/bin/codexbar usage \
  --provider codex \
  --source cli \
  --format json \
  --pretty

关键字段示例：

{
  "provider": "codex",
  "source": "codex-cli",
  "usage": {
    "accountEmail": "user@example.com",
    "loginMethod": "plus",
    "primary": null,
    "secondary": {
      "resetDescription": "Jul 25 at 3:37 PM",
      "usedPercent": 57,
      "windowMinutes": 10080
    }
  }
}

字段含义：

provider
└─ codex

source
└─ codex-cli
   └─ 数据来自已登录的 Codex CLI

loginMethod
└─ plus
   └─ 使用 ChatGPT Plus / Pro 账户

primary
└─ null
   └─ 当前没有返回短时 Session 窗口

secondary
├─ usedPercent：57
│  └─ 每周额度已使用 57%
├─ 剩余额度
│  └─ 约 43%
└─ windowMinutes：10080
   └─ 10080 分钟，即 7 天

文本输出中的 44% left 与 JSON 的 57% used 可能存在 1% 左右差异，通常来自刷新时间和取整。

五、Pace 信息说明h2

示例：

10% in deficit
Expected 47% used
Runs out in 2d 11h

含义：

Expected 47% used
└─ 按当前一周已经过去的时间，均匀使用时预计应消耗约 47%

实际使用 57%
└─ 比均匀进度多用了约 10 个百分点

Runs out in 2d 11h
└─ 如果保持当前速度，预计约 2 天 11 小时后用完

这是 CodexBar 根据当前速度计算出的估算值，不是 OpenAI 官方承诺的准确耗尽时间。

六、创建 Cinnamon 专用包装脚本h2

Cinnamon 面板运行命令时，环境变量可能与 zsh、bash 终端不同。为了避免找不到 codex、codexbar 或认证目录，建议创建一个固定入口：

~/.local/bin/codexbar-cinnamon

创建脚本：

cat > ~/.local/bin/codexbar-cinnamon <<'EOF'
#!/bin/sh

export HOME="$HOME"
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"

exec "$HOME/.local/bin/codexbar" "$@" --source cli
EOF

chmod +x ~/.local/bin/codexbar-cinnamon

如果 Cinnamon 中 $HOME 没有按预期展开，也可以改成绝对路径版本：

cat > ~/.local/bin/codexbar-cinnamon <<'EOF'
#!/bin/sh

export HOME="/home/your-user"
export PATH="/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin"

exec /home/your-user/.local/bin/codexbar "$@" --source cli
EOF

chmod +x ~/.local/bin/codexbar-cinnamon

作用：

HOME
└─ 指向当前用户家目录，便于 Codex CLI 找到 ~/.codex/auth.json

PATH
└─ 确保 Cinnamon 能找到 codex 和 codexbar

--source cli
└─ 强制通过 Codex CLI 读取额度

验证包装脚本：

~/.local/bin/codexbar-cinnamon \
  usage \
  --format json \
  --provider codex \
  --pretty

只要能正常返回 JSON，说明 Codex CLI、CodexBar CLI 和包装脚本都正常。

七、安装 Cinnamon 面板插件h2

目标结构：

源码目录
└─ ~/.local/src/codexbar-cinnamon-applet

Cinnamon 小程序目录
└─ ~/.local/share/cinnamon/applets/codexbar@local

创建目录：

mkdir -p ~/.local/src
mkdir -p ~/.local/share/cinnamon/applets

下载插件：

git clone \
  https://github.com/jacobcalvert/codexbar-cinnamon-applet.git \
  ~/.local/src/codexbar-cinnamon-applet

如果目录已经存在：

git -C ~/.local/src/codexbar-cinnamon-applet pull --ff-only

建立软链接：

ln -sfn \
  ~/.local/src/codexbar-cinnamon-applet \
  ~/.local/share/cinnamon/applets/codexbar@local

检查：

ls -ld ~/.local/share/cinnamon/applets/codexbar@local

正常应指向：

~/.local/src/codexbar-cinnamon-applet

八、重新加载 Cinnamonh2

Alt + F2
└─ 输入 r
   └─ 回车

如果当前会话或远程桌面不支持该操作，注销后重新登录。

添加小程序：

系统设置
└─ 小程序
   └─ 管理
      └─ 搜索 CodexBar
         └─ 添加到面板

九、配置 Cinnamon 插件h2

打开：

系统设置
└─ 小程序
   └─ CodexBar
      └─ 设置

填写：

CodexBar command path
└─ /home/your-user/.local/bin/codexbar-cinnamon

Provider
└─ codex

Refresh interval
└─ 120

路径必须填写完整路径：

/home/your-user/.local/bin/codexbar-cinnamon

不要填写：

~/.local/bin/codexbar-cinnamon

Provider 选择：

codex

不要选 OpenAI。两者区别：

Codex
└─ ChatGPT Plus / Pro 的 Codex 使用额度

OpenAI
└─ OpenAI API Platform 的 API 组织用量

十、实际遇到的问题h2

第一次添加插件后面板可能显示：

Waiting for data
No usage data returned yet.

悬停后可能看到类似错误：

CodexBar: Could not run CodexBar:
执行子进程“/opt/apps/codexbar/codexbar”失败
（没有那个文件或目录）

原因是插件默认执行路径不是当前安装路径：

插件默认执行路径
└─ /opt/apps/codexbar/codexbar

实际安装路径
└─ ~/.local/bin/codexbar

插件最终应调用
└─ ~/.local/bin/codexbar-cinnamon

解决方法：

系统设置
└─ 小程序
   └─ CodexBar
      └─ 设置
         └─ CodexBar command path
            └─ /home/your-user/.local/bin/codexbar-cinnamon

修改后点击：

CodexBar
└─ Refresh now

面板即可恢复正常。最终不需要创建 /opt/apps/codexbar/codexbar 软链接。

十一、为什么只显示 Weeklyh2

返回的 JSON 可能是：

"primary": null,
"secondary": {
  "usedPercent": 57,
  "windowMinutes": 10080
}

因此：

primary
└─ 没有短时 Session 窗口数据

secondary
└─ 有 Weekly 周额度数据

插件会在 primary 为空时使用 secondary。

最终面板显示：

Weekly
├─ 已使用：57%
├─ 剩余：约 43%
└─ 重置时间：Jul 25 at 3:37 PM

注意：面板百分比表示已使用，而不是剩余。

十二、Credits: 0 的含义h2

Credits: 0 left

这不代表 ChatGPT Plus / Pro 的 Codex 周额度已经耗尽。

它表示：

额外购买或附加 Credits
└─ 当前余额为 0

Plus / Pro 套餐额度仍由 Weekly 窗口表示。

十三、可选：代理环境处理h2

如果终端执行正常，但 Cinnamon 面板执行失败，并且错误表现为网络连接失败、超时或无法访问服务，可以在包装脚本中加入代理变量。

示例：

cat > ~/.local/bin/codexbar-cinnamon <<'EOF'
#!/bin/sh

export HOME="/home/your-user"
export USER="your-user"
export LOGNAME="your-user"

export PATH="/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin"

export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"

export NO_PROXY="localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12"
export no_proxy="$NO_PROXY"

exec /home/your-user/.local/bin/codexbar "$@" --source cli
EOF

chmod +x ~/.local/bin/codexbar-cinnamon

如果本机代理监听 127.0.0.1:7890，Cinnamon 用户会话通常可以直接访问，不需要改成 0.0.0.0:7890。

没有网络问题时，不建议提前加入代理配置，保持脚本简单更容易排查。

十四、常用命令h2

查看当前额度：

~/.local/bin/codexbar usage \
  --provider codex \
  --source cli

查看 JSON：

~/.local/bin/codexbar usage \
  --provider codex \
  --source cli \
  --format json \
  --pretty

测试包装脚本：

~/.local/bin/codexbar-cinnamon \
  usage \
  --provider codex \
  --format json \
  --pretty

检查插件源码：

ls -ld ~/.local/src/codexbar-cinnamon-applet

检查 Cinnamon 软链接：

ls -ld ~/.local/share/cinnamon/applets/codexbar@local

查看 Cinnamon 错误日志：

grep -iE 'codexbar|codex|error' \
  ~/.xsession-errors |
  tail -n 50

实时查看：

tail -f ~/.xsession-errors

十五、更新与卸载h2

更新 Cinnamon 插件：

git -C ~/.local/src/codexbar-cinnamon-applet pull --ff-only

更新后重新加载 Cinnamon：

Alt + F2
└─ 输入 r
   └─ 回车

更新 CodexBar CLI 时，重新执行最新版下载和安装流程，覆盖：

~/.local/bin/codexbar

如果 Codex CLI 使用 npm 全局安装，可以更新：

npm install -g @openai/codex@latest

卸载时，先从 Cinnamon 面板移除 CodexBar 小程序，然后执行：

rm -f ~/.local/share/cinnamon/applets/codexbar@local
rm -rf ~/.local/src/codexbar-cinnamon-applet

rm -f ~/.local/bin/codexbar-cinnamon
rm -f ~/.local/bin/codexbar

十六、最终状态h2

最终状态如下：

Codex CLI
├─ 已登录 ChatGPT Plus / Pro
└─ 能正常返回账户信息

CodexBar CLI
├─ 路径：~/.local/bin/codexbar
├─ Provider：codex
├─ Source：codex-cli
└─ 能输出文本和 JSON

包装脚本
├─ 路径：~/.local/bin/codexbar-cinnamon
├─ 固定 HOME 和 PATH
└─ 强制使用 --source cli

Cinnamon 插件
├─ 命令路径：/home/your-user/.local/bin/codexbar-cinnamon
├─ Provider：codex
├─ 刷新间隔：120 秒
└─ 面板正常显示 Weekly 额度

本次问题的核心其实不是 CodexBar CLI，而是 Cinnamon 插件默认路径与实际安装路径不一致：

CodexBar CLI 本身正常
└─ Cinnamon 插件默认路径错误
   └─ 默认调用 /opt/apps/codexbar/codexbar
      └─ 文件不存在

修改插件命令路径
└─ /home/your-user/.local/bin/codexbar-cinnamon
   └─ 问题解决