capgo-organization-management

Capgo 组织管理

通过 CLI 安全地管理 Capgo 账户和组织。

以下信息已根据 @capgo/cli 8.77（2026 年 10 月）核实。所有命令均接受 -a, --apikey。

适用场景

以下情况时使用：

• 用户需要获取自己的 Capgo 账户 ID 或邮箱以联系支持（account whoami）。
• 用户要列出、创建、重命名或删除组织。
• 用户要审计成员或 2FA 状态，或强制启用 2FA、密码策略、API 密钥有效期或哈希 API 密钥。
• 用户需要知道某个应用归属哪个组织（app list --show-org --show-org-id）。
• 命令因组织级 2FA 或权限错误而失败。

以下情况时不要使用：

• 工作涉及 bundles、channels 或 rollouts。请使用 capgo-release-management。
• 用户需要原生云构建。请使用 capgo-native-builds。
• 用户希望将 Agent 连接到 Capgo 账户（MCP）。请使用 capgo-cli-usage。

命令一览

目标	命令（npx @capgo/cli@latest ...）
我是谁	account whoami（别名 account id）
列出组织	organization list
创建组织	organization add --name "My Company" --email [email protected]
成员和 2FA 状态	organization members ORG_ID（查看 2FA 状态需要 super_admin）
重命名 / 更改邮箱	organization set ORG_ID --name "New Name" --email [email protected]
强制启用 2FA	organization set ORG_ID --enforce-2fa（撤销设置请使用 --no-enforce-2fa）
密码策略	organization set ORG_ID --password-policy --min-length 12 --require-uppercase --require-number --require-special
API 密钥有效期	organization set ORG_ID --require-apikey-expiration --max-apikey-expiration-days 90（1 到 365）
哈希 API 密钥	organization set ORG_ID --enforce-hashed-api-keys
查看各组织的应用	app list --show-org --show-org-id 或 app list --filter-by-org-id ORG_ID --output-text
删除组织	organization delete ORG_ID（仅限所有者，且不可撤销）

请使用 organization。organisation 拼写已弃用，之后将移除。

操作步骤

1. 确认范围和角色

npx @capgo/cli@latest account whoami
npx @capgo/cli@latest organization list

确认目标 ORG_ID。安全设置需要 super_admin 角色。删除组织需要所有者权限。

2. 强制执行前先检查

npx @capgo/cli@latest organization members ORG_ID

列出尚未启用 2FA 的成员，然后在强制启用前向用户说明情况。强制启用 2FA 会使这些成员无法访问 CLI 和 API，直到他们启用 2FA。

3. 一次更改一项策略

每次只应用一项 organization set 更改，验证后再继续下一项。至少保留一名已正常启用 2FA 且密钥有效的管理员，确保组织不会被锁定。

4. API 密钥策略的副作用

• --require-apikey-expiration / --max-apikey-expiration-days 会影响新密钥。托管 MCP 为 OAuth 创建的密钥（MCP · <client>）有效期本来就不超过 90 天；如果组织设置了更严格的限制，则以组织限制为准。
• --enforce-hashed-api-keys 表示密钥仅在创建时显示一次。现有 CI 密钥仍可使用，但若密钥丢失，则必须重新创建。

注意事项

• organization delete 无法撤销，且只有所有者才能运行。先运行 app list --filter-by-org-id ORG_ID，让用户查看该组织包含的内容，然后获取用户对组织名称的明确确认。
• organization members 需要 super_admin 才能显示 2FA 状态。较低权限的角色只能查看部分数据。
• 不要要求用户在聊天中粘贴用于管理操作的 API 密钥。让他们运行 npx @capgo/cli@latest login，或在 shell 中设置 CAPGO_TOKEN。

验证

1. 再次运行 organization list。应能看到名称和邮箱的更改。
2. 强制启用后，再次运行 organization members ORG_ID。所有仍在组织中的成员都应显示已启用 2FA。
3. 使用非管理员成员的密钥运行只读命令（例如 app list）。他们启用 2FA 后，命令应能成功运行。

错误处理

字符串	解决方法
🔐 Access Denied: Two-Factor Authentication Required / This organization requires all members to have 2FA enabled.	在 https://console.capgo.app（账户设置）中启用 2FA，然后重试。文档：https://capgo.app/docs/webapp/2fa-enforcement/
Insufficient permissions for <key>	执行操作的用户或密钥缺少相应角色。安全设置需要 super_admin，删除操作需要所有者权限
No organizations available	该密钥对应的用户尚无组织。使用 organization add 创建一个
No Capgo API key found. Run ... first, then retry this command.	运行 npx @capgo/cli@latest login、设置 CAPGO_TOKEN，或传入 -a

资源

• 组织参考：https://capgo.app/docs/cli/reference/organization/
• 账户参考：https://capgo.app/docs/cli/reference/account/
• 2FA 强制要求：https://capgo.app/docs/webapp/2fa-enforcement/