1. 项目概述AIMGR一个专为AI开发者设计的账户管理器如果你和我一样日常工作中需要同时管理多个AI服务比如OpenAI Codex、Claude、Pi的付费账户并且这些账户还要被不同的自动化代理如OpenClaw、Hermes或本地CLI工具共享使用那你一定体会过那种混乱。浏览器里登录着A账户命令行工具用的是B账户的token而自动化脚本又指向了C账户的过期凭证。手动同步不仅容易出错一旦某个账户的会话过期所有依赖它的服务都会瞬间瘫痪排查起来更是噩梦。aimgr命令行工具叫aim就是为了解决这个痛点而生的。它不是什么大而全的云平台而是一个聚焦于单一任务的、运行在你本地的“AI账户管家”。它的核心哲学很简单一个中心化的真相源Single Source of Truth, SSOT管理所有付费账户的凭证和状态然后根据规则将这些“真相”编译并分发到下游的各个消费端。这些消费端包括OpenClaw这样的多代理框架、本地的Codex CLI、Claude CLI以及Pi CLI。简单来说aimgr让你从“管理一堆分散的token和浏览器会话”的泥潭中解放出来转而用“标签”Label来思考。你不再需要记住acct_xxx这个token对应哪个邮箱或者~/.codex/auth.json里现在写的是谁。你只需要知道我有一个标签叫boss它代表我的主力OpenAI账户另一个标签叫claudalyst代表我的Claude团队账户。aimgr负责确保这些标签背后的账户是有效的Ready、绑定了正确的浏览器环境并且能按需、智能地分配给需要它们的工具。2. 核心设计理念与架构解析2.1 为什么是“标签”而不是“凭证”这是aimgr设计上最精妙的一点。直接操作原始的API密钥、刷新令牌或会话Cookie是脆弱且易错的。这些凭证会过期、会轮换而且它们本身不携带任何业务语义。aimgr引入了“标签”作为一层抽象。一个标签如boss,lessons,qa绑定了一个具体的AI服务提供商Provider如openai-codex,anthropic和一个期望的账户身份如邮箱。标签的状态对操作者而言是直观的ready就绪可用、reauth需要重新认证、blocked被阻止如达到限额。操作者也就是我们的思维模型从此变得极其简单我不关心boss标签背后此刻具体的refresh_token是什么我只关心它是不是ready状态。如果是我就可以放心地把它分配给需要它的任务。aimgr在背后默默处理了凭证的刷新、验证和存储。2.2 唯一的真相源~/.aimgr/secrets.json所有持久化的、权威的数据都存储在一个文件里~/.aimgr/secrets.json。这是整个系统的基石也是“SSOT”原则的物理体现。这个文件包含了账户定义(accounts): 每个标签的元数据如提供商、期望的邮箱、认证模式等。凭证数据(credentials): 每个标签当前有效的访问令牌、刷新令牌、过期时间等。这是最敏感的部分。导入状态(imports): 记录从“权威主机”同步过来的标签信息用于解决多机器间的数据冲突。池状态(pool): 记录使用历史、各代理的需求量等用于智能分配算法。目标状态(targets): 记录当前各个下游消费端OpenClaw, Codex CLI等被分配了哪个标签。任何对账户状态的操作如认证、刷新最终都会原子化地更新这个文件。aimgr在写入前会自动创建带时间戳的备份secrets.json.bak.timestamp提供了简单的回滚机制。2.3 明确的浏览器绑定模型许多AI服务尤其是OpenAI的认证流程严重依赖浏览器会话。aimgr没有采用模糊的“自动探测”策略而是要求为每个需要浏览器认证的标签显式配置绑定模式。这消除了不确定性共有四种模式aim-profile:aimgr为这个标签管理一个独立的、隔离的Chrome用户数据目录位于~/.aimgr/browser/label/user-data。这是最干净、最推荐的方式完全避免了与你个人浏览器的冲突。chrome-profile: 绑定到一个已存在的、原始的Chrome用户数据目录和具体的配置文件。你需要提供完整的--user-data-dir路径和可选的--profile-directory名称。这适用于你想复用某个现有Chrome配置的场景。agent-browser: 绑定到特定的agent-browser实例一种常用于自动化的浏览器工具需要指定--profile路径和--session名称。manual-callback: 无本地浏览器绑定。aimgr会生成OAuth URL你需要手动在任意浏览器中完成登录然后将回调URL粘贴回终端。这适用于无头环境或极其特殊的网络配置。重要提示对于Claude标签aimgr采用了完全不同的“原生捆绑包”Native Bundle策略不再使用浏览器绑定。这是因为Claude CLI有其独立的认证体系。你需要通过aim claude capture-native命令从已登录的本地Claude客户端捕获凭证包。这种显式绑定的设计虽然初期配置稍显繁琐但带来了巨大的长期收益状态清晰、可调试、可迁移。你不会再遇到“这个脚本到底在用哪个浏览器配置文件”这样的幽灵问题。2.4 派生目标而非竞争真相这是aimgr的另一个核心原则。OpenClaw、Codex CLI、Claude CLI、Pi CLI 都是“消费者”或“目标”。它们不应该自己存储权威的账户状态。OpenClaw:aimgr根据池子状态和代理需求计算出分配方案然后将结果写入OpenClaw的配置中。OpenClaw只是读取并使用这些分配。Codex/Pi CLI:aimgr选择最合适的标签然后将对应的凭证写入~/.codex/auth.json或~/.pi/agent/auth.json。CLI工具启动时读取这个文件。Claude CLI:aimgr将捕获的“原生捆绑包”写入~/.claude/.credentials.json和~/.claude.json。所有这些写入操作都是单向的、派生式的。如果下游工具因为某些原因修改了认证状态比如Claude CLI自动刷新了tokenaimgr设计了相应的同步机制如aim claude use时的preSwitchSync来将变化捕捉回自己的SSOT而不是被下游工具覆盖。3. 实战部署与核心工作流3.1 环境准备与安装aimgr是一个Node.js工具要求Node版本 20并且主要面向macOS环境虽然部分功能在Linux上也可用。从源码安装推荐用于迭代和固定版本:# 1. 克隆仓库并进入目录 cd /path/to/aimgr/repo # 2. 安装依赖并创建全局软链接 (方便开发) npm install npm link # 验证安装 which aim aim --help # 或者安装一个固定的全局版本非软链接 npm install -g . # 3. 对于使用nvm等Node版本管理工具的用户推荐安装到独立目录避免PATH问题 npm install npm run install:local # 这会安装到 ~/.local/bin前置条件检查:确保已安装Google Chrome。如果你要管理OpenClaw确保openclaw命令在PATH中。如果你要管理本地Codex CLI确保其配置为文件存储模式检查~/.codex/config.toml中的cli_auth_credentials_store不是keyring或auto。3.2 核心操作流程整个aimgr的日常操作可以概括为以下几个核心动作它们构成了清晰的操作者路径。第一步查看全局状态 (aim status)这是你的控制面板。在任何操作前后都应该先运行它来了解现状。aim status # 或获取JSON格式的详细信息便于脚本处理 aim status --json | jq .它会告诉你所有标签的状态ready,reauth,blocked。OpenClaw当前的分配情况。本地Codex、Claude、Pi CLI当前激活的标签。Hermes集群的映射状态。池子容量和下一个可用的候选账户。最后一次同步、选择、监控操作的结果。第二步维护或认证一个标签 (aim label)这是管理单个账户的主要入口。在终端中运行它会进入一个交互式引导面板。aim boss对于OpenAI Codex类标签面板会提供选项打开绑定浏览器、重新认证/刷新登录、更改浏览器设置、查看详情。你只需要按数字选择即可。对于Claude标签面板选项会变为使用该标签、刷新原生捆绑包、捕获当前登录等。如果你需要在脚本或非交互式环境中执行认证可以使用aim login label命令它会执行一次性的维护流程。第三步为OpenClaw代理重新分配账户 (aim rebalance openclaw)这是aimgr智能化的体现。它不仅仅是简单轮询而是基于需求的加权分配。aim rebalance openclaw这个命令会从OpenClaw读取每个代理近期的会话令牌使用量作为“需求”指标。评估池中所有ready状态标签的剩余容量例如基于5小时窗口的剩余量。运行一个分配算法目标是将多个代理合理地分配到仍有容量的账户上而不是僵化的一对一绑定。这能最大化利用付费账户的额度。只有当预测的总需求超过总供应量时才会跳过某些代理。将分配结果写入OpenClaw的配置并生成一份包含allocationMode和perAccountLoad的详细回执。如果你只是想应用当前已记录的分配方案而不重新计算可以使用aim sync openclaw或它的别名aim apply。第四步激活本地CLI工具对于本地开发你需要将池中的账户应用到你的命令行环境。激活Codex CLI:# 首先从权威主机同步池数据如果是消费机 aim sync codex --from agentsamirs-mac-studio # 然后让aimgr为你选择并激活下一个最合适的账户 aim codex use这个命令会检查当前Codex主目录选择池中下一个符合条件的标签并更新~/.codex/auth.json文件。请注意这只会影响新启动的Codex进程不会热替换正在运行的进程。激活Claude CLI:# 同步Claude标签数据 aim sync claude --from agentsamirs-mac-studio # 自动选择或指定标签激活 aim claude use # 自动选择下一个 aim claude use claudalyst # 指定激活claudalyst标签Claude的激活涉及写入两个文件~/.claude/.credentials.json和~/.claude.json中的oauthAccount部分。aimgr在切换前会智能地同步本地Claude可能已刷新的token避免凭证失效。激活Pi CLI:aim pi use其逻辑与aim codex use类似但写入的是~/.pi/agent/auth.json文件。3.3 自动化守护监控与轮换AI服务的会话通常有使用限制如OpenAI的5小时窗口。手动轮换低利用率账户是不现实的。aimgr提供了监控守护功能。为Codex CLI设置自动监控:# 一次性运行检查适用于cron任务 aim codex watch --once --rotate-below-5h-remaining-pct 20 # 前台循环运行用于测试 aim codex watch --interval-seconds 300 --rotate-below-5h-remaining-pct 20--rotate-below-5h-remaining-pct 20意味着当当前激活账户的5小时剩余额度低于20%时触发自动轮换到池中的下一个可用账户。aimgr甚至提供了便捷的安装脚本帮你配置系统级的定时任务LaunchDaemon on macOS, systemd timer on Linuxcd /path/to/aimgr bash ./scripts/install-codex-watch.sh安装后守护进程会定期执行--once检查实现全自动的账户容量管理。为Hermes集群设置监控 (aim hermes watch):逻辑与Codex监控类似但它监控的是本机上所有运行的Hermes实例的家目录并在需要时触发aim rebalance hermes来为整个集群重新分配账户。4. 多机器协作权威主机与消费机模式aimgr优雅地支持团队或多设备共享一个账户池。1. 权威主机 (Authority Host)这是存储“官方”secrets.json的机器。通常是你管理所有原始账户认证的地方。在这台机器上你直接使用aim label进行认证和维护。使用aim rebalance openclaw管理本地的OpenClaw代理。这台主机是“数据源”。2. 消费机 (Consumer Machine)这是使用共享账户的机器比如团队成员的开发机或构建服务器。首先从权威主机同步账户池aim sync codex --from authority。这里的authority可以是SSH路径如agentsamirs-mac-studio也可以是文件路径。然后就可以像在权威主机上一样使用aim codex use,aim claude use等命令了。如果在消费机上刷新了某个导入标签的凭证比如因为会话过期aimgr会标记该标签为“脏”状态。你需要使用aim promote codex --to authority label将更改推回权威主机完成双向同步。这采用了比较-交换保护防止覆盖他人的并发更新。这种模式确保了凭证管理的集中化和安全性同时允许在消费机上进行必要的本地刷新操作。5. 高级配置与故障排查实录5.1 浏览器绑定模式详解与选择选择正确的浏览器绑定模式对长期稳定运行至关重要。以下是我的经验之谈aim-profile(首选): 这是最干净、最隔离的方式。aimgr会为每个标签创建独立的Chrome数据目录。这意味着这个浏览器环境只用于该标签的AI服务认证没有插件、没有历史记录干扰也完全不会影响你日常使用的Chrome。缺点是首次打开时需要重新登录所有服务但aimgr会帮你保存会话。chrome-profile: 当你已经有一个配置完善的Chrome配置文件比如已经登录了所有工作账号并且想直接复用时使用。你需要找到Chrome的用户数据目录macOS通常在~/Library/Application Support/Google/Chrome和配置文件名称。注意aimgr操作时可能会打开浏览器窗口如果你正在使用该配置文件可能会有冲突。agent-browser: 专为与agent-browser这种自动化浏览器工具集成设计。如果你整个AI工作流都基于此类工具这是最佳选择。manual-callback: 最后的手段。当你在无头服务器、Docker容器或网络环境极其特殊如需要特定代理时使用。流程是aimgr打印URL - 你在任何能登录的浏览器中访问并完成认证 - 将最终跳转的URL回填给aimgr。切换绑定模式如果你需要更改一个标签的绑定模式使用aim browser set命令家族# 切换到aim-profile模式并可选择从一个现有的OpenClaw浏览器配置初始化 aim browser set boss --mode aim-profile --seed-from-openclaw profileId # 切换到指定的Chrome用户目录和配置文件 aim browser set boss --mode chrome-profile --user-data-dir ~/Library/Application\ Support/Google/Chrome --profile-directory Profile 1 # 切换到agent-browser模式 aim browser set boss --mode agent-browser --profile /path/to/agent-browser/profile --session boss-session # 切换到手动回调模式 aim browser set boss --mode manual-callback5.2 Claude原生捆绑包管理跨设备同步的密钥Claude CLI的认证不依赖于传统的OAuth流程而是使用一个“原生捆绑包”其中包含了CLI内部使用的凭证。aimgr对此提供了完整的工作流在主机A上捕获捆绑包确保Claude CLI已登录目标账户。aim claude capture-native claudalyst这会将当前登录状态保存到aimgr的secrets.json中。可选导出为文件以便传输aim claude export-live --out ~/claude-bundles/claudalyst.json你可以将此文件安全地复制到另一台机器。在主机B上导入捆绑包aim claude import-native claudalyst --in ~/claude-bundles/claudalyst.json在主机B上激活该标签aim claude use claudalyst重要机制Claude CLI会自动刷新token并写入本地文件。aimgr的aim claude use命令在切换前会先读取本地Claude文件如果发现token已更新会先将这些更新同步回aimgr存储的捆绑包中然后再进行切换。这避免了因切换账户而导致另一个账户的刷新token失效的问题。5.3 常见问题与解决方案问题aim codex use返回blocked。原因池中没有处于ready状态的账户。排查运行aim status查看哪些标签是reauth或blocked状态。解决对reauth的标签执行aim label进行重新认证。如果是blocked如达到限额需要等待或联系服务商。问题aim sync codex --from ...失败提示会丢弃本地更改。原因你在本地消费机上刷新了某个从权威主机导入的标签但尚未将更改推送回去。解决# 1. 查看哪些标签是脏的 aim status # 2. 将本地更改推回权威主机 aim promote codex --to agentsamirs-mac-studio 脏标签名 # 3. 重新同步 aim sync codex --from agentsamirs-mac-studio或者如果你确认要放弃本地更改使用--discard-dirty参数强制同步。问题aim rebalance openclaw后某些代理没有被分配账户。原因分配器的加权算法预测当前所有ready账户的剩余总容量不足以满足所有代理的历史/预测需求。排查运行aim status --json并查看pool.openaiCodex.agentDemand和pool.openaiCodex.history了解需求分布和账户使用情况。解决增加池容量认证更多ready标签或者检查是否有代理产生了异常高的需求可能是bug或配置错误。问题aim codex watch守护进程似乎没有工作。排查# 检查最后一次watch回执 aim status | grep -A 10 lastWatchReceipt # 手动运行一次查看详细输出 aim codex watch --once --rotate-below-5h-remaining-pct 20 --verbose # 检查系统调度器状态 (macOS) sudo launchctl list | grep aim_codex_watch # 或查看日志 (macOS) sudo log show --predicate subsystem com.funcountry.agents_host --last 1h常见原因Node.js路径问题、aimgr脚本路径问题、权限问题、或者当前激活的标签本身无法读取5小时剩余量。问题Claude CLI切换账户后原账户的token失效了。原因旧版本的aimgr或手动操作可能没有处理Claude的token同步。解决确保使用最新版aimgr。在切换账户前aim claude use命令现在会自动检测并同步本地Claude文件中的新token到aimgr存储的捆绑包中。如果已经发生失效需要在原账户仍处于登录状态时重新执行aim claude capture-native 原标签。5.4 安全与备份实践secrets.json是命根子这个文件包含了所有AI服务的刷新令牌。务必确保其安全。将其纳入你的密码管理器备份流程。文件权限应设置为600(chmod 600 ~/.aimgr/secrets.json)。aimgr的自动备份 (secrets.json.bak.*) 提供了短期回滚但不能替代正式备份。谨慎处理权威主机访问消费机通过SSH访问权威主机的secrets.json。确保SSH密钥安全并考虑使用受限的SSH账户和授权密钥仅允许读取该特定文件。隔离浏览器环境强烈建议为AI账户使用独立的浏览器配置文件aim-profile模式避免与包含个人数据、银行cookie的日常浏览器混用降低安全风险。定期审计使用aim status定期检查标签状态、分配情况和池容量。建立习惯在感觉“某个服务变慢了”的时候首先检查相关标签是否处于reauth状态。aimgr将AI账户管理从一项繁琐、易错的手工劳动转变为一个声明式、自动化的基础设施组件。它要求你在初期投入一些时间理解其模型和配置但一旦运转起来它将无声无息地为你保障着整个AI开发流程的账户供给稳定性让你能更专注于构建应用本身而不是整天忙于处理“Token又过期了”的警报。