跳到主要内容

使用多个账户

CLI 同时支持 N 个账户。典型场景：

  • SaaS 上的个人账户，加上另一组织中的公司账户。
  • 用于客户的 SaaS 账户，加上用于内部开发的 self-hosted 实例。
  • 多个 self-hosted 实例（生产、staging、本地机器）。

它们都保存在 ~/.almirant/config.json。

心智模型​

每个账户有四个重要部分：

字段用途
id稳定标识符。almirant link 会将其写入 .mcp.json。
label供人使用的本地名称，例如 prod-saas 或 local-m1pro。
apiBaseUrlCLI 与之通信的后端。
apiKey密钥令牌；绝不会完整输出。

电子邮件不足以作为标识符，因为同一用户可以存在于多个实例中。

查看已配置账户​

almirant accounts list
# o, por compatibilidad:
almirant config accounts list

典型输出：

[*]  1  local-m1pro       [email protected]                  https://macbook-m1-pro.tailnet.ts.net/api  alm_***
[ ]  2  prod-saas         [email protected]                  https://api.almirant.ai                    alm_***
信息

完整 API key 绝不会输出。你只会看到前缀或状态指示符。

添加新账户​

# SaaS
almirant login

# Backend concreto
almirant login --api-url https://almirant.miempresa.com/api

# Alias equivalente
almirant accounts add --api-url https://almirant.miempresa.com/api

使用有意义的标签重命名账户​

almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant accounts rename prod-saas clientes

标签只在本地有效。它们描述实例或用途，不必与电子邮件或 URL 一致。

切换活动账户​

# Selector interactivo
almirant use

# Directo por label, ID, email unico o indice
almirant use local-m1pro
almirant use 2

# Ver la activa
almirant current

活动账户是在未传入明确账户时由命令使用的账户。

活动账户与仓库中固定的账户​

有两种有效模式：

  1. 固定账户：almirant init / almirant link 的默认模式。.mcp.json 包含 --account <account-id>，因此即使你稍后在其他上下文中执行 almirant use，仓库也始终与同一实例通信。
  2. 活动账户：高级模式。若从代理参数中移除 --account，仓库将跟随通过 almirant use 选择的活动账户。

我们建议使用固定模式：它可避免旧仓库将记忆、任务或评论保存到错误的实例。

无密钥 MCP​

生成的 .mcp.json 不包含 API key：

{
  "mcpServers": {
    "almirant": {
      "type": "stdio",
      "command": "almirant",
      "args": ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id>"]
    }
  }
}

almirant mcp proxy 从 ~/.almirant/config.json 读取账户，并在内存中附加 bearer token。

Codex .codex/config.toml​

[mcp_servers.almirant]
command = "almirant"
args = ["mcp", "proxy", "--project-id", "<project-id>", "--account", "local-m1pro"]

请勿将令牌保存在 .codex/config.toml、.zshrc 或 .bashrc 中。若需切换实例，请通过 almirant use 切换活动账户，或更新项目的 --account。

删除账户​

almirant accounts remove <ref>
almirant accounts remove <ref> --yes

这会从本地配置中删除账户。若要同时使后端中的令牌失效，请从 Almirant 轮换或撤销 API key。

轮换账户的 API key​

almirant config rotate api-key --account <ref>

这会生成新密钥，在本地配置中替换旧密钥，并使服务器中的旧密钥失效。由于仓库使用代理且不存储令牌，轮换后通常无需重写 .mcp.json。

修改账户的 API URL​

如果将 self-hosted 实例迁移到另一个域名，此命令很有用：

almirant config set api-url https://nueva-url.example.com/api --account local-m1pro

重置所有内容​

若要从头开始（删除所有本地账户）：

almirant config reset
almirant config reset -y