Skip to content
BranchesTags

Repository files navigation

AkironMux

统一 Claude Code 与 Codex 配置和会话的 Rust TUI、CLI 与桌面 GUI。

管理 Claude Code 与 Codex 的多个 API 供应商配置，支持一键切换、代理转发、会话历史浏览。Claude Code 支持本地/代理模式，Codex 直接维护自身配置文件。

功能

  • Claude 四模型配置：每个 Profile 独立配置 Opus、Sonnet、Haiku、Subagent
  • 双应用顶栏：顶栏显示 Claude | Codex，Space 切换当前应用上下文
  • Codex 第三方模型：Provider 可使用 Codex 内置目录，或维护多个 Responses API 模型并生成聚合 Catalog
  • 一键切换：本地模式直接写入 ~/.claude/settings.json，代理模式更新 SQLite
  • 会话历史：分别扫描 Claude Code 与 Codex 本地会话文件，支持搜索、过滤
  • 代理服务：本地 HTTP 代理（端口 15721），自动模型名转换，支持 systemd / launchd / 计划任务后台运行
  • Token 用量：按模型统计 Token 消耗，带缓存避免每帧查询
  • 多语言：内置中文 / English 切换，设置持久化
  • 桌面会话工作区：通过可选的本地后端，在一个 GUI 中运行和恢复 Claude Code / Codex 会话
  • 认证远程后端：独立 Remote 监听器、逐设备凭证、60 秒配对、单次 WebSocket 票据和终端控制租约

安装

NixOS

Nix 安装直接使用 GitHub Release 中经过固定 SHA-256 校验的预编译包，不会在本机编译 Rust 或 WebUI。目前该安装方式仅支持 x86_64-linux。

Home Manager（推荐，按用户配置）

在 home.nix 中：

{
  inputs.akironMux.url = "github:pomeluce/akiron-mux";

  homeConfigurations = {
    your-user = home-manager.lib.homeManagerConfiguration {
      modules = [
        akironMux.homeModules.default
        {
          programs.akmux = {
            enable = true;
            gui = true; # 默认 false，只安装 TUI/CLI
            # 由 sops-nix/agenix 等部署到 Nix store 外；内容如 OPENAI_API_KEY=sk-xxx
            envVars = "%h/.config/akmux/env";
            defaults = {
              version = 1;
              claude_providers = [
                {
                  id = "deepseek";
                  name = "DeepSeek";
                  api_url = "https://api.deepseek.com/anthropic";
                  api_key = "env:DEEPSEEK_API_KEY";
                  profiles = [
                    {
                      id = "v4"; name = "V4";
                      opus = "deepseek-v4-pro[1m]";
                      sonnet = "deepseek-v4-pro[1m]";
                      haiku = "deepseek-v4-flash";
                      subagent = "deepseek-v4-flash";
                      default = true;
                    }
                  ];
                }
              ];
              # 官方 Codex 套餐对应的 OpenAI Provider 已内建；这里的配置
              # 额外保留按 API Key 计费的 OpenAI API Provider。
              codex_providers = [
                {
                  id = "openai-api";
                  name = "OpenAI API";
                  api_url = "https://api.openai.com/v1";
                  api_key = "env:OPENAI_API_KEY";
                }
              ];
            };
          };
        }
      ];
    };
  };
}

Home Manager 会自动：

  • 将 defaults 写入 ~/.config/akmux/defaults.toml
  • gui = false 只安装 akmux TUI/CLI；gui = true 同时安装桌面 GUI
  • 安装并启用 akmux-proxy systemd user service（通过 envVars 传入 Nix store 外的环境文件路径）
  • 让 CLI/TUI 从同一个 envVars 文件解析 env:VAR_NAME，无需将密钥导入当前 shell

注意：defaults 会进入 Nix store，api_key 应只写 env:VAR_NAME 引用，不要写明文密钥。

NixOS 全局安装

在 configuration.nix 中：

{
  inputs.akironMux.url = "github:pomeluce/akiron-mux";

  outputs = { nixpkgs, akironMux, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      modules = [
        akironMux.nixosModules.default
        {
          services.akmux = {
            enable = true;
            gui = false;
            defaults = {
              version = 1;
              claude_providers = [ ... ];
              # 官方 Codex 套餐对应的 OpenAI Provider 已内建；这里的配置
              # 额外保留按 API Key 计费的 OpenAI API Provider。
              codex_providers = [
                {
                  id = "openai-api";
                  name = "OpenAI API";
                  api_url = "https://api.openai.com/v1";
                  api_key = "env:OPENAI_API_KEY";
                }
              ];
            };
          };
        }
      ];
    };
  };
}

NixOS 模块将配置写入 /etc/akmux/defaults.toml，并安装二进制包。

命令行直接使用

# 临时启动
nix run github:pomeluce/akiron-mux

# 安装到 profile
nix profile install github:pomeluce/akiron-mux

Homebrew（macOS）

brew tap pomeluce/ccswitch
brew install akiron-mux

Cargo（Linux / macOS / Windows WSL2）

cargo install --git https://github.com/pomeluce/akiron-mux

首次运行会自动创建 ~/.config/akmux/。如果存在旧的 ~/.config/akiron-mux/ 或 ~/.config/ccswitch/，缺失文件会被复制迁移，旧目录不会删除或覆盖新数据。

预编译包（Linux）

从 Releases 下载：

# Debian/Ubuntu
VERSION=1.15.4
curl -LO "https://github.com/pomeluce/akiron-mux/releases/download/v${VERSION}/AkironMux-${VERSION}-linux-x86_64-cli.deb"
sudo dpkg -i "AkironMux-${VERSION}-linux-x86_64-cli.deb"

# Fedora/RHEL
curl -LO "https://github.com/pomeluce/akiron-mux/releases/download/v${VERSION}/AkironMux-${VERSION}-linux-x86_64-cli.rpm"
sudo rpm -i "AkironMux-${VERSION}-linux-x86_64-cli.rpm"

# 通用 tar.gz
curl -LO "https://github.com/pomeluce/akiron-mux/releases/download/v${VERSION}/AkironMux-${VERSION}-linux-x86_64-cli.tar.gz"
tar -xzf "AkironMux-${VERSION}-linux-x86_64-cli.tar.gz"
sudo mv akmux akmux-sessiond /usr/local/bin/

预编译包（macOS 手动）

VERSION=1.15.4
curl -LO "https://github.com/pomeluce/akiron-mux/releases/download/v${VERSION}/AkironMux-${VERSION}-macos-arm64-cli.tar.gz"
tar -xzf "AkironMux-${VERSION}-macos-arm64-cli.tar.gz"
chmod +x akmux akmux-sessiond
sudo mv akmux akmux-sessiond /usr/local/bin/

预编译包（Windows）

从 Releases 下载 CLI zip 或 AkironMux GUI 安装包；CLI zip 中的 akmux.exe 与 akmux-sessiond.exe 可加入 %PATH%。

也可以通过 Scoop 安装：

scoop bucket add ccswitch https://github.com/pomeluce/scoop-ccswitch.git
scoop install ccswitch

安装后执行 akmux service install 注册 Windows 计划任务后台服务。

使用

TUI 模式

akmux    # 无参数启动 TUI

左侧栏 J/K 选择标签页，Tab / Shift+Tab 切换，Enter 确认。

CLI 模式

# 模型切换
akmux switch deepseek/v4           # 切换到指定的 provider/profile
akmux list                         # 列出所有 provider 和 profile

# 配置管理（仅对用户配置生效，系统默认不可删除/编辑）
akmux add provider                 # 交互式添加供应商
akmux add profile <provider-id>    # 添加模型配置
akmux edit <provider|profile>      # 查看配置
akmux remove <provider|profile>    # 删除用户配置

# 代理服务
akmux proxy start                  # 后台启动代理（自动检测 systemd）
akmux proxy stop                   # 停止代理
akmux proxy status                 # 查看代理状态
akmux proxy serve                  # 前台运行代理（调试用）
akmux service install              # 安装后台服务（开机自启）
akmux service uninstall            # 卸载后台服务

# 服务安装平台支持：
#   Linux   → systemd user service
#   macOS   → launchd agent
#   Windows → 计划任务 (Schtasks)

# 远程会话后端（17322 是明文 HTTP 监听器，只绑定 loopback、LAN 或 Tailnet 地址）
akmux backend remote configure --bind 127.0.0.1:17322 --public-url https://akmux.example.com
akmux backend device create --name "Bootstrap" --show-token
akmux backend remote enable
akmux backend remote status
akmux backend diagnostics
akmux backend audit --limit 50

# 60 秒桌面端/移动端配对；客户端提交后再确认 pending ID
akmux backend pair create
akmux backend pair pending
akmux backend pair confirm <pairing-id>
akmux backend pair cancel <pairing-id>

# 设备管理（输出不包含凭证明文）
akmux backend device list
akmux backend device revoke <token-id>

# 用量与历史
akmux usage                        # Token 用量统计（默认本周）
akmux usage --day|--week|--month   # 按日/周/月
akmux usage --profile <name>       # 按模型过滤
akmux history                      # 会话历史
akmux history --project <name>     # 按项目过滤
akmux history --search <keyword>   # 搜索会话

# Shell 补全 & Man 文档
akmux completions <zsh|bash|fish>  # 生成 Shell 补全脚本
akmux man                          # 输出 roff 格式 man page

配置

配置文件位置：

  • ~/.config/akmux/akmux.db — SQLite 数据库（模型配置、用量、会话和后端开关）
  • ~/.config/akmux/defaults.toml — 系统默认配置（Home Manager / NixOS 生成）
  • ~/.local/share/akmux/akmux.log — TUI 运行日志
  • ~/.codex/config.toml — Codex Provider 配置
  • ~/.codex/auth.json — 当前生效的 Codex 登录凭证或第三方 API Key
  • ~/.codex/auth_openai.json — 切换第三方 Provider 时备份的官方 Codex 登录凭证
  • ~/.codex/auth_akmux.json — 切回官方 Provider 时备份的第三方 API Key

首次启动

首次启动 akmux 时会先显示终端进度条导入 Claude Code 历史会话数据（从 ~/.claude/projects/ 扫描 JSONL 文件）。导入完成后自动进入 TUI。后续启动跳过导入直接进入。

用量数据在进入 TUI 后通过后台异步扫描。Claude 数据来自 ~/.claude/projects，Codex 数据来自 ~/.codex/sessions；会话与用量面板约每秒检测变化并实时刷新。Codex rename 后的会话标题从 ~/.codex/session_index.jsonl 同步。带 parent_thread_id 的 Codex 内部子会话不会单独显示，其消息数和用量会归并到父会话；通过 /fork 创建的会话仍作为独立会话显示。

远程后端部署

Remote API 默认监听 127.0.0.1:17322，该端口只提供明文 HTTP，自身不终止 TLS。同机反向代理可以直接使用 http://127.0.0.1:17322 作为上游，但不能把公网 HTTPS/TCP 流量直接转发到 17322，也不能把 https://127.0.0.1:17322 配置成上游。客户端填写的地址和 --public-url 都应是反向代理对外提供的 HTTPS 根地址，例如 https://akmux.example.com，不包含 /api 路径。

设备 Token 等同于宿主机当前用户权限下的终端控制凭证，应分别为每台设备创建并及时撤销；Token 明文只显示一次，数据库仅保存 HMAC 摘要，~/.config/akmux/remote-auth.pepper 必须与数据库一同备份。GUI 的“配对链接”输入框不接收设备 Token，只接收 akmux backend pair create 生成的短时 akmux://pair?... 链接；长期 Token 由原生客户端在配对过程中领取并写入系统凭证存储。

推荐让 Caddy 在同一主机终止 TLS：

akmux.example.com {
  reverse_proxy http://127.0.0.1:17322
}

也可以使用 Tailscale Serve 将 loopback 服务发布到 Tailnet：

tailscale serve --bg https / http://127.0.0.1:17322

随后将 --public-url 配置为实际的 HTTPS 地址。AkironMux 不会自动修改 DNS、防火墙、Caddy 或 Tailnet；不要把 17322 的明文 HTTP 监听器直接暴露到公网。仅配置 DNS、TCP 端口映射或四层转发不能替代 TLS 反向代理。Remote 默认拒绝 wildcard 和公网 IP 直绑，只允许 loopback、私网、link-local 和 Tailnet/共享地址。确实需要容器或多网卡环境中的 wildcard 监听时，必须显式传入 --allow-wildcard-bind，并先通过主机防火墙、Tailnet ACL 或同机 TLS 反向代理限制 17322；该开关不会允许绑定具体公网 IP。

首次启用并把桌面 GUI 配对到远程后端时，按以下顺序操作：

  1. 在服务器配置 Remote，并创建一个临时引导设备。当前版本要求至少存在一个活动设备才能启用监听；device create 输出的 Token 不要粘贴到 GUI。

    akmux backend remote configure \
  --bind 127.0.0.1:17322 \
  --public-url https://akmux.example.com
akmux backend device create --name "Bootstrap" --show-token
akmux backend remote enable

  2. 确认会话后端服务正在运行，并分别检查明文上游和公网 HTTPS。两次请求都应返回 200 与 {"status":"ok"}。

    curl -i -H 'Host: akmux.example.com' http://127.0.0.1:17322/healthz
curl -i https://akmux.example.com/healthz
akmux backend diagnostics

  3. 生成新的 60 秒配对链接，把完整的 akmux://pair?... 链接粘贴到 GUI 的“配对链接”，后端地址填写同一个 https://akmux.example.com。新建 Remote Profile 尚无凭证时应直接点击“保存”；“测试连接”只适用于已经配对并保存凭证的 Profile。

    akmux backend pair create

  4. GUI 发起配对请求后，在服务器确认对应的 pending ID。

    akmux backend pair pending
akmux backend pair confirm <pairing-id>

  5. GUI 配对成功后，可以撤销不再使用的临时引导设备，但不要撤销刚刚配对生成的客户端设备。

    akmux backend device list
akmux backend device revoke <bootstrap-token-id>

defaults.toml

Claude 与 Codex Provider 分别使用 claude_providers 和 codex_providers；旧的 providers 字段不再支持。

version = 1

[[claude_providers]]
id = "deepseek"
name = "DeepSeek"
api_url = "https://api.deepseek.com/anthropic"
api_key = "env:DEEPSEEK_API_KEY"

[[claude_providers.profiles]]
id = "v4"
name = "V4"
opus = "deepseek-v4-pro[1m]"
sonnet = "deepseek-v4-pro[1m]"
haiku = "deepseek-v4-flash"
subagent = "deepseek-v4-flash"
default = true

[[claude_providers]]
id = "openrouter"
name = "OpenRouter"
api_url = "https://openrouter.ai/api"
api_key = "env:OPENROUTER_API_KEY"

[[claude_providers.profiles]]
id = "claude"
name = "Claude"
opus = "anthropic/claude-opus-4"
sonnet = "anthropic/claude-sonnet-4"
haiku = "anthropic/claude-haiku-4"
subagent = "anthropic/claude-haiku-4"

[[codex_providers]]
id = "codex-proxy"
name = "Codex Proxy"
api_url = "https://api.example.com/v1"
api_key = "env:OPENAI_API_KEY"
codex_catalog = "custom"

[[codex_providers.models]]
slug = "third-party-coder"
display_name = "Third-party Coder"
description = "Agentic coding model"
context_window = 128000
max_context_window = 256000
effective_context_window_percent = 95
default_reasoning_effort = "high"
supported_reasoning_efforts = ["low", "high"]
input_modalities = ["text"]
supports_parallel_tool_calls = true
support_verbosity = true
default_verbosity = "low"
supports_search_tool = false
default = true

API Key 格式

格式 说明
env:VAR_NAME 从进程环境、HM 的 envVars 文件或 ~/.config/akmux/env 读取，推荐
sk-xxx... 直接文本（明文存储，不安全）
空值 Claude 使用 $CLAUDE_API_KEY；Codex 使用 $OPENAI_API_KEY

TUI 快捷键

全局

键 功能
Tab / Shift+Tab 切换侧边栏标签页
Space 切换顶栏 Claude | Codex Tab
Q / q 退出

模型标签页

Claude Code 使用 Provider → Profile，Codex 使用 Provider → Model。Codex 内置目录 Provider 不需要维护模型；第三方 Provider 必须配置至少一个模型。

键 功能
J/K ↑/↓ Provider 列表导航 / Profile 导航
Enter 进入 Profile 列表 / 切换模型
A 添加 Provider / Profile
E 编辑 Provider / Profile
D 删除 Provider / Profile（需确认）
Esc 返回 Provider 列表

会话标签页

键 功能
J/K ↑/↓ 上下导航（循环滚动）
Enter 打开会话（根据顶栏启动 Claude Code 或 Codex）
D 删除会话（弹窗确认）
/ 搜索（分词匹配标题 + 项目名）
Esc 退出搜索 / 关闭弹窗

用量标签页

键 功能
J/K ↑/↓ 导航模型列表
T 切换时间范围（天/周/月）
/ 搜索模型
PgUp/PgDn 滚动右侧日用量图表

左侧显示选中模型的今日/本周/总计/请求数统计卡片及模型排名。右侧显示选中模型的近 7 天用量柱状图。首次启动时用量数据在后台异步扫描，右侧面板显示扫描进度条。

设置标签页

单面板居中布局，所有设置项垂直排列。

键 功能
J/K ↑/↓ 选择设置项
H/L ←/→ 切换选项值

设置面板由 Claude 与 Codex 共用，支持切换主题（7 种）、模式（local / proxy）、语言（中文 / English）及会话后端。会话后端默认关闭；启用后才启动 akmux-sessiond 并监听 127.0.0.1:17321，关闭时立即停止。模式设置只对 Claude 生效；Codex 不区分 local/proxy。

写入映射

切换 profile 时写入 Claude Code 的 settings.json。

Local 模式

环境变量 值
ANTHROPIC_AUTH_TOKEN 解析后的 API key
ANTHROPIC_BASE_URL 上游 API 地址
ANTHROPIC_MODEL sonnet
ANTHROPIC_DEFAULT_OPUS_MODEL opus
ANTHROPIC_DEFAULT_SONNET_MODEL sonnet
ANTHROPIC_DEFAULT_HAIKU_MODEL haiku（去 [1m]）
CLAUDE_CODE_SUBAGENT_MODEL subagent（去 [1m]）

Proxy 模式

环境变量 值
ANTHROPIC_AUTH_TOKEN ccswitch-proxy（占位符）
ANTHROPIC_BASE_URL http://127.0.0.1:15721

Opus/Sonnet/Haiku 变量不在 settings.json 中设置，由 proxy server 透明处理；Subagent 使用内部标记以便代理识别并映射。

Codex Provider 切换

Codex 不使用 Claude Profile，也不区分 local/proxy。TUI 内建不可编辑的 OpenAI Provider，用于恢复官方 Codex 套餐。第三方 Responses Provider 的所有模型会聚合写入 ~/.codex/akmux/models.json。官方套餐和第三方都统一使用 AkironMux 保留的 akmux Provider ID，避免覆盖 Codex 内建的 openai，并保证两种认证方式创建的历史会话互相兼容：

model_provider = "akmux"
model = "third-party-coder"
model_reasoning_effort = "high"
model_catalog_json = "/home/user/.codex/akmux/models.json"

[model_providers.akmux]
name = "Codex Proxy"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

[akmux.last_switch]
source = "codex-proxy"
at = "2026-01-01 12:00:00"

切换到第三方 Provider 时，当前官方 auth.json 会移动到 auth_openai.json，然后创建只包含第三方 Key 的 auth.json：

{
  "OPENAI_API_KEY": "解析后的 provider API key"
}

切回内建 OpenAI 时，第三方 auth.json 会备份为 auth_akmux.json，auth_openai.json 恢复为 auth.json，并将 model_providers.akmux 更新为 name = "OpenAI"、base_url = "https://chatgpt.com/backend-api/codex"。其他使用 codex_catalog = "built-in" 的第三方 Provider 同样通过 model_providers.akmux 工作；切换这类 Provider 时，AkironMux 只移除自己管理的 model_catalog_json 引用，不覆盖其他外部 Catalog 文件。

模式

本地模式（Local）

直接修改 ~/.claude/settings.json 的 env 字段，Claude Code 直接访问上游 API。

代理模式（Proxy）

  1. akmux service install 安装后台服务（或 akmux proxy start 手动启动）
  2. 代理监听 127.0.0.1:15721
  3. settings.json 的 ANTHROPIC_BASE_URL 指向代理，Claude Code 所有请求经过代理
  4. 代理自动进行模型名转换：
    • 请求体：Opus/Sonnet/Haiku/Subagent 分别映射到对应 Profile 字段，并去除 [1m]
    • 响应流：message.model 还原为原始名称，注入 ccs_model / ccs_proxy 标记
  5. 切换 profile 无需重启代理，代理每次请求从 DB 读取最新配置
  6. 自动记录 Token 用量到 SQLite

开发

nix develop    # 进入开发环境（Rust 工具链）
cargo build    # 构建
cargo test     # 测试
cargo run --bin akmux  # 启动 TUI
nix build .#tui        # 封装 Release 中的 TUI/CLI
nix build .#gui        # 封装 Release 中的 TUI/CLI + 桌面 GUI

发布

Release 工作流分为两个阶段，以保证 Tag 中记录的 hash 与最终发布文件完全一致：

  1. 在 GitHub Actions 中以目标 Tag 名运行 prepare，下载生成的 release candidate，并将其中的 nix/release-assets.nix 提交到仓库。
  2. 在该提交上创建并推送 Tag，再以 prepare run ID 运行 publish。publish 只会发布第一阶段保存的原始文件。

已发布的同名资产不可覆盖；内容变化时必须升级版本并创建新 Tag。

License

GPL-3.0

About

Unified TUI and desktop workspace for managing Claude Code and Codex providers, sessions, history, usage, and configurations.

Topics

ai-codingclaude-codecodex-clicoding-agentdesktop-appdeveloper-toolsnixnixosopenai-codexprovider-managerreactrustsession-managertauriterminal-uitui

Resources

Readme
GPL-3.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages