账户、计费与 API Keys
在 Settings 中管理账户、执行机器、计费状态、API keys 和应用偏好。
Account
Account 区域包含 profile、subscription、credits 和已连接的 OAuth accounts。
Profile
在 Settings -> Profile 中可以更新：
- 头像
- 用户名
- 邮箱地址
用户名和邮箱必须唯一。如果另一个账户已经使用该值，应用会显示校验错误。
OAuth Accounts
连接 OAuth accounts 后，Agentrix 才能代表你访问 GitHub 或 GitLab 等 providers。Repository mode 会使用这些连接列出仓库、issues 和 MRs。
如果仓库访问失败，回到 Settings 确认对应 OAuth account 是否已连接。
Subscription
打开 Settings -> Subscription 可以查看当前 plan 和可用 plans。当部署启用了 billing 后，该页面可以：
- 显示当前 plan、续费或到期日期、月费和包含的 credits。
- 打开 customer portal 管理现有订阅。
- 为新 plan 启动 checkout。
- 显示 plan features，并在配置后标记 popular plan。
如果页面显示 subscription features are not configured，说明当前部署环境的管理员没有启用 billing。
Credits
打开 Settings -> Credits 可以查看账户余额、有效 credit packages 和交易历史。
Credits 页面会显示：
- 当前总余额。
- 有效 credit buckets 和过期时间。
- 可用时显示充值入口。
- Recharge 和 usage 交易历史。
如果最近的支付或用量记录还没出现，可以刷新页面。Credits 页面打开时，应用也会通过 WebSocket 监听 billing 更新。
Devices
Local Machines
打开 Settings -> Local Machines 可以查看绑定到账户的机器。列表会显示在线状态、host 信息、平台和 CLI 版本。
你可以在这里 unbind local machine。解绑会移除这台机器与账户的关联；下一次在该机器上运行 agentrix start 时，需要重新认证。
Private Clouds
打开 Settings -> Private Clouds 可以创建和管理团队 runner pool。Private Clouds 的完整说明见 Private Cloud 部署。
Preferences
Preferences 区域可以调整：
- Layout
- Theme 和 appearance
- Language
这些偏好只影响应用 UI，不会改变 daemon 行为。
Privacy
打开 Settings -> Privacy 可以查看、复制或修改本地账户 entry password。应用的加密和恢复流程会用到它。
请把这个 password 当作敏感信息处理。拥有该 password 和必要账户上下文的人，可能恢复受保护的数据。
API Keys
API keys 用于 agentrix-run、GitHub Actions、GitLab CI 和自定义脚本等自动化场景。
打开 Settings -> API Keys 可以：
- 用名称创建 key。
- 在 reveal modal 中一次性复制完整 key。
- 查看 key prefix、last-used time、expiry 和 enabled 状态。
- 删除不再使用的 keys。
请把 API keys 存到 secret manager 或 CI secret store。Agentrix 只会在创建后立即显示完整 key。
API Key 可访问的常用只读接口
API key 可以作为 bearer token 调用下列常用只读接口。部分接口会返回 secret、加密 key 或带凭证的 URL，请按敏感信息处理：
Authorization: Bearer YOUR_API_KEY
| 范围 | 接口 | 说明 |
|---|---|---|
| 账户 | GET /v1/auth/me | 查询当前用户资料、OAuth accounts 和 Git server accounts。 |
| API Keys | GET /v1/api-keys | 查询当前账户的 API key metadata。不会再次返回完整 key。 |
| 计费 | GET /v1/billing/balance | 查询当前 credits 余额。 |
| 计费 | GET /v1/billing/packages | 查询当前账户的 credit packages。 |
| 计费 | GET /v1/billing/transactions | 查询当前账户的交易记录。 |
| 计费 | GET /v1/billing/transactions/task/:taskId | 查询指定 task 的计费交易。 |
| 计费 | GET /v1/billing/stats | 查询当前账户的用量统计。 |
| 订阅 | GET /v1/subscription | 查询当前订阅和 entitlement。 |
| 配置 | GET /v1/openapi-config | 查询 LLM gateway base URL、默认 API key 和模型配置。请按敏感信息处理。 |
| Environment Variables | GET /v1/environment-variables | 查询指定 owner 的 environment variables。需要当前账户拥有该 owner。 |
| Local Machines | GET /v1/machines | 查询当前账户可用的 local machines、cloud runners 和 private cloud runners。Local machine 条目会包含该账户的 dataEncryptionKey。 |
| Local Machines | GET /v1/machines/:machineId/models | 查询指定 local machine 当前可用的模型。机器必须在线。 |
| Private Clouds | GET /v1/machines/clouds/:cloudId/models | 查询指定 private cloud runner 当前可用的模型。runner 必须在线。 |
| Private Clouds | GET /v1/private-clouds | 查询当前账户加入的 private clouds 和 private cloud entitlement。 |
| Private Clouds | GET /v1/private-clouds/:id/machines | 查询指定 private cloud 的 runner machines。 |
| Private Clouds | GET /v1/private-clouds/:id/members | 查询指定 private cloud 的成员列表。 |
| Private Clouds | GET /v1/private-clouds/:id/runner-secret | 查询 runner secret。只有 owner 或 admin 应调用；请按 secret 处理。 |
| Auth Requests | GET /v1/auth/machine/status | 查询指定 local machine auth request 的审批状态。 |
| Auth Requests | GET /v1/auth/cloud | 查询 private cloud join request 的审批结果。 |
| Auth Requests | GET /v1/auth/cloud/status | 查询指定 private cloud join request 的 pending 状态。 |
| Workspaces | GET /v1/workspaces | 查询当前账户的 workspaces。 |
| Chats | GET /v1/chats | 查询当前账户可访问的 chats。 |
| Chats | GET /v1/chats/:chatId | 查询 chat 详情。 |
| Chats | GET /v1/chats/:chatId/members | 查询 chat 成员。 |
| Chats | GET /v1/chats/:chatId/tasks | 查询 chat 下的 tasks。 |
| Tasks | GET /v1/tasks | 查询 task 列表。 |
| Tasks | GET /v1/tasks/:taskId | 查询 task 详情。 |
| Tasks | GET /v1/tasks/:taskId/events | 查询 task event 历史。 |
| Tasks | GET /v1/tasks/:taskId/patch | 查询 task patch。 |
| Tasks | GET /v1/tasks/:taskId/project/* | 读取 task workspace 中的项目文件。 |
| Tasks | GET /v1/tasks/:taskId/channel-attachment | 读取 channel attachment。 |
| Tasks | GET /v1/tasks/sub-tasks | 查询直接子任务。 |
| Tasks | GET /v1/tasks/recent | 查询最近 tasks。 |
| Tasks | GET /v1/tasks/find-by-agent | 按 agent 查询已有 task。 |
| Repositories | GET /v1/inbox | 查询当前账户的 repository inbox。 |
| Repositories | GET /v1/repos/install-url | 查询 GitHub App installation URL。 |
| Repositories | GET /v1/repos | 查询当前账户授权的 repositories。 |
| Repositories | GET /v1/repos/:repoId | 按 repository ID 查询详情。 |
| Repositories | GET /v1/repos/:repoId/inbox | 查询指定 repository 的 inbox。 |
| Repositories | GET /v1/repos/:owner/:repo | 按 owner/name 查询 repository。 |
| Repositories | GET /v1/repos/:owner/:repo/git-url | 查询带凭证的 Git URL。请按敏感信息处理。 |
| Repositories | GET /v1/repos/:owner/:repo/branches | 查询 branches。 |
| Repositories | GET /v1/repos/:owner/:repo/issues | 查询 issues。 |
| Repositories | GET /v1/repos/:owner/:repo/issues/:number | 查询 issue 详情。 |
| Repositories | GET /v1/repos/:owner/:repo/issues/:number/comments | 查询 issue comments。 |
| Repositories | GET /v1/repos/:owner/:repo/references | 查询 issues、pull requests 或 merge requests。 |
| Repositories | GET /v1/repos/:owner/:repo/references/:number | 查询 reference 详情。 |
| Repositories | GET /v1/repos/:owner/:repo/references/:number/comments | 查询 reference comments。 |
| Repositories | GET /v1/repos/:owner/:repo/references/:number/inline-comments | 查询 inline comments。 |
| Repositories | GET /v1/repos/:owner/:repo/references/:number/activity | 查询 reference activity。 |
| Repositories | GET /v1/repos/:owner/:repo/references/:number/diff | 查询 reference diff。 |
| Git integrations | GET /v1/git-servers | 查询可用 Git servers。 |
| Git integrations | GET /v1/git-servers/:gitServerId | 查询 Git server 详情。 |
| Git integrations | GET /v1/git-servers/:gitServerId/apps | 查询 Git server apps。 |
| Git integrations | GET /v1/git-apps | 查询当前账户的 Git apps。 |
| Git integrations | GET /v1/git-apps/:appId/repositories | 查询 Git app 下的 repositories。 |
| Files | GET /v1/files | 查询当前账户的 files。 |
| Files | GET /v1/files/:fileId | 获取可访问文件的下载跳转 URL。 |
| Contacts | GET /v1/contacts | 查询联系人。 |
| Contacts | GET /v1/contacts/candidates | 搜索可添加的联系人候选。 |
| Agents | GET /v1/agents | 查询 agents。 |
| Agents | GET /v1/agents/user/:userId | 查询指定用户发布的 agents。 |
| Agents | GET /v1/user-agents | 查询当前账户的 agents 和 draft agents。 |
| Agents | GET /v1/agents/:agentId | 查询 agent 详情。 |
| Agents | GET /v1/agents/:agentId/git-url | 查询 published agent 的 Git URL。请按敏感信息处理。 |
| Hive | GET /v1/hive/me | 查询自己发布的 Hive listings。 |
| Hive | GET /v1/hive/installed | 查询自己安装的 Hive listings。 |
部分公开浏览接口不需要 API key，例如 GET /v1/resources、GET /v1/hive/listings、GET /v1/hive/listings/:id 和 GET /v1/hive/trending。
安全轮换 API Key
- 创建一个命名清楚的新 key，比如
github-actions-agentrix。 - 更新 CI secret 或自动化环境变量。
- 运行一次自动化任务，确认新 key 可用。
- 从 Settings -> API Keys 删除旧 key。
agentrix-run 可以通过 AGENTRIX_API_KEY 或 GitHub Action 的 api-key input 传入 key。CI 示例见 agentrix-run。