跳到主要内容

连接仓库

这是最常见的流程：你在 Almirant 中拥有账户（SaaS 或 self-hosted），并希望本地仓库显示为项目，同时能从 IDE（Claude Code、Codex、OpenCode、Cursor 等）访问 AI 智能体。

预计用时：2 分钟。

前提条件​

  • 已安装 CLI（bun add -g almirant@latest 或 npm i -g almirant）。
  • 一个 Almirant 账户。如果还没有，请在 almirant.ai 创建账户，或按 self-hosted 指南部署自己的实例。

第 1 步：进行身份验证​

根据要验证的后端选择命令：

# SaaS
almirant login

# Instancia self-hosted
almirant login --api-url https://almirant.miempresa.com/api

CLI 会打开浏览器进行 OAuth，并将账户以 600 权限保存到 ~/.almirant/config.json。

提示

每个后端只需执行一次 login。如果使用多个实例（例如同时使用 SaaS 和 self-hosted），请为每个实例执行一次 almirant login，用 almirant accounts rename 为它们设置标签，再用 almirant use 切换活动账户。参见使用多个账户。

第 2 步：选择活动账户​

如果有多个账户，请使用标签。四个月后你会记得 local-m1pro，而不是一个很长的 URL。

almirant accounts list
almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

第 3 步：关联仓库​

进入要连接的仓库根目录并执行：

cd mi-repo
almirant link

CLI 会：

  1. 读取已存储账户，并使用活动账户或允许你选择。
  2. 列出该账户的项目，并允许你选择或创建项目。
  3. 使用本地 stdio 代理将 almirant 条目合并到 .mcp.json。
  4. 将 skill 模板复制到 .claude/skills/ 和 .agents/skills/。

如果这是你的首次使用且尚未执行 almirant login，请使用 almirant init 而不是 link：init 也会在同一个命令中触发 OAuth 流程。

第 4 步：在 IDE 中验证​

在智能体中打开仓库，并请求类似内容：

Lista mis work items de Almirant

如果看到列表，说明已全部连接。如果得到 Unauthorized，请检查：

  • .mcp.json 是否存在于仓库根目录。
  • .mcp.json 的 --account 是否指向现有账户（almirant accounts list）。
  • 本地 API key 是否仍有效（almirant current 仅显示前缀，不显示密钥）。
  • 后端是否正在运行且可访问，尤其对于 self-hosted 实例。

仓库中会保留什么​

执行 link 后，仓库包含：

mi-repo/
├── .mcp.json              ← arranca almirant mcp proxy; no contiene tokens
├── .claude/
│   └── skills/            ← plantillas de skills para Claude Code
└── .agents/
    └── skills/            ← mismo contenido, para agentes no-Claude

生成的 MCP 条目遵循此模式：

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

API key 保存在 ~/.almirant/config.json 中，而不在 .mcp.json 中。智能体启动代理时，代理会在内存中附加 bearer token。

Codex .codex/config.toml​

如果使用 Codex 且 MCP 服务器在 .codex/config.toml 中声明，请使用同一个代理：

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

请勿在 .codex/config.toml 中写入 bearer token。若希望该仓库始终跟随活动账户，请省略 --account；对于团队协作或旧仓库，我们更建议按 ID 固定账户。

从旧配置迁移​

如果 .mcp.json 包含 type: "http"、url 和 Authorization: Bearer ...，请重新执行：

almirant link

如果该令牌曾提交到 git，请轮换它：

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

管理多个账户和项目​

若使用多个账户（典型情况：个人账户加公司账户，或 SaaS 加内部实例），请参阅使用多个账户。

若要更改已初始化仓库所关联的项目，请再次执行 almirant link 并选择新项目：CLI 会重写 .mcp.json 中的 almirant 条目，同时保留其他服务器。