文档

您本地机器上的编码智能体

在你启动任务的设备上,你的AI配置文件中的角色会由编码智能体来执行,该智能体仅可使用CoRoid提供的工具,不会调用设备上的其他资源。

您的AI配置文件中的某个角色可以在您本地机器上运行的编码智能体而非由CoRoid调用的模型。该智能体在您设置的账户下,以您的身份在其提供商的平台上执行该角色的推理逻辑。CoRoid会为其提供该角色所需的工具,同时保留工作流的其他所有内容:任务、检查规则与关卡,以及操作记录。

涵盖范围

  • 除决策引擎外的配置文件中的所有角色:该 架构师以及协调员, 开发人员、质量保证人员, 审核员、网页测试员、翻译人员及其他角色。决策引擎并非以智能体形式运行:它会向决策模型询问每个允许答案的概率,而编码智能体无法提供此类结果。
  • 四种智能体:Codex和OpenCode,部分组织目前还可选用Claude Code和Cursor。每种智能体均在您自身的提供商套餐下运行(详见您的智能体套餐)。
  • 任务的运行方式在协调员模式下,协调员及其分配给他子的任务会像其他角色一样交由智能体处理。

您的智能体套餐

该智能体在您自己的登录账号下,于您所选的提供商套餐中运行:Claude Code对应Anthropic,Codex对应OpenAI,Cursor对应Cursor,OpenCode则对应您自行设置的提供商。CoRoid无法查看您的登录信息,也不会转售或共享任何人的套餐:每位用户需自行连接其机器,智能体将执行他们发起的任务。

某套餐的条款是否允许通过其他产品使用该套餐,以及适用于何种工作场景,均由您与提供商协商确定。不同提供商的规定、其个人版与企业版套餐的要求、可处理的工作量上限均存在差异,且相关规定也可能随时调整。请查阅您的套餐条款,如有疑问可向提供商确认。

为智能体分配角色的组织需同步核查其成员所用的套餐情况。该组织的政策可能仅允许使用已通过条款审核的智能体(详见贵组织的允许范围)。

连接方式

您的电脑

CoRoid 连接器

开源软件。它会在一个全新的空目录中启动智能体,任务结束后即停止。

您的编码智能体

您使用的智能体,以您的身份登录,其自身工具处于关闭状态。

  1. 1请求分配工作任务。 每个请求的处理时限为 25 秒;连接器会每 3 秒汇报一次智能体的反馈。
  2. 2调用该角色所对应的工具。 仅限本次任务使用的令牌,任务结束后即失效。
  3. 3向其内置模型发起询问。 这与不使用 CoRoid 时的情况相同。CoRoid 不会看到该登录信息。

CoRoid

编排器

它将角色的工作分配给发起任务人员的电脑(1)。

该智能体的工具集

在任务沙箱中运行,您的代码会保留在其中(2)。

该智能体的提供者

它会在您的登录状态下、根据您的套餐为您响应智能体的模型请求(3)。

没有任何程序能访问电脑内部:连接器不会打开端口、发送文件,也不会自行执行命令。

您的智能体登录信息以及智能体为本次任务保存的内容会留在电脑中。

所有连接都从电脑启动,再通过 HTTPS 传输。代码仓库会留在 CoRoid 的任务沙箱中;智能体仅能通过角色的工具对其进行操作。

该机器通过 CoRoid 的CoRoid连接器为小型开源程序,需您自行安装并运行。每次连接均从机器端发起:连接器向CoRoid请求任务,智能体在任务的沙盒环境中调用该角色所需的工具,随后在您的登录状态下向其提供商请求模型输出结果。连接器不会开放端口,也不会传输机器的任何文件。连接器的安全性涵盖了其功能边界及核查发行版的方法。

连接机器

  1. 在机器上安装智能体并登录,流程与您亲自使用时的操作一致。

  2. 在macOS或Linux系统上可通过Homebrew安装连接器:

    brew install coroid-ai/tap/coroid-connector

    或在任意支持Node.js 20及以上版本的系统上通过npm安装:

    npm install --global @coroid/connector
  3. 如需使用Codex或Claude Code,需添加智能体:coroid-connector add codex(或 add claude)。此举会安装智能体的ACP适配器,进而将其专属的智能体副本(约350 MB)置入~/.coroid/connector,该副本来自连接器发行版中经哈希锁定的软件包。OpenCode和Cursor无需额外添加:CoRoid会直接使用您自行安装的版本。

  4. 打开设置 → 连接 → 您的机器,运行此处显示的命令(coroid-connector --api …)。浏览器会弹出提示,请您批准该机器加入您的组织。仅可批准您刚刚启动的连接器。

此后连接器会持续运行,直至您手动停止,期间会不断向CoRoid请求任务。您的机器页面会列出已连接的机器,包括连接器在该机器上发现的智能体及其版本号。只有当智能体版本经过CoRoid测试验证后才会显示为可用状态;其他版本虽会列出但不会被使用。

coroid-connector status页面会从机器端显示相同信息,包括每个智能体当前设定的模型。

您的机器信息仅您可见。断开连接操作会终止该机器的登录状态,其连接器会在一分钟内停止运行。

为智能体分配角色

组织所有者可在自定义配置文件中通过设置 → AI配置文件完成此操作(详见AI配置文件)。

  1. 打开配置文件的详情页。在角色对应的首个字段中,列表首项为在您本地机器上:即组织可提供使用的智能体,每个智能体旁会标注您的机器是否已准备好使用该智能体。
  2. 选择所需的智能体后,会显示另外两个字段:
    • 模型在:该角色要使用的模型,来自所连接设备上上报的可用模型。按设备上的设置为准。会使智能体采用其所有者为该角色设定的模型。
    • 如果没有已连接的设备:当没有设备承接工作时,运行该角色的模型。也就是该角色原本所用的模型。
  3. 保存。

再次在第一个字段中选择模型会致使智能体被转移,同时该模型也会随之被选用。

任务运行时会发生什么

任务分配由组织决定;设备则由个人掌控。角色启动时,CoRoid会查找启动该任务的人员所对应的设备:

  • 过去一分钟内在本组织中已连接的设备,
  • 且所分配的智能体已准备好运行CoRoid验证过的版本,
  • 如果分配中指定了模型,该设备还需能提供该模型。

若存在符合条件的设备,角色的工作便会交由该设备处理。若不存在,角色则会在以下模型上运行:如果没有已连接的设备,工作流程与原有设定完全一致。无需等待设备响应。无人手动触发的任务(如基于事件的自动化任务、定时任务)没有对应的设备,因此会在其模型上运行。

在设备上,连接器会在全新的空目录中启动智能体,并为其会话配备一套工具:仅用于本次工作的、CoRoid为该角色定制的工具。开发者可通过这些工具在CoRoid中的任务工作区修改代码,就如同模型操作一般;QA人员和审核人员也会通过这些工具评判相关变更。智能体工作时添加到任务中的消息,会随下一次工具返回结果一同送达智能体。

处于等待状态的角色会重新交还给智能体。协调员会将工作分派给开发者、QA人员和审核人员,并等待各自的结果;子角色可能会等待协调员的答复。等待结束后,角色会重新交还给智能体,智能体也会收到迄今为止的对话记录。一台设备最多可同时运行四个角色(连接器版本0.4.0),因此开发者启动的探索进程会与它们并行运行。

如果设备在角色运行过程中停止响应,该角色会在同一对话流程中切换至其云端模型继续运行,云端模型也会获知这一情况。被暂停的任务会同时中止智能体的运行。角色结束后,其智能体会被终止,对应目录也会被删除。

设备上会保留哪些内容

连接器会删除角色运行时的对应目录。智能体在其自身存储中保留的工作内容则因智能体类型而异:

智能体保留的内容
Claude Code无会话记录:连接器启动时会关闭会话持久化功能。
Codex每个会话的记录会存储在~/.codex/sessions,其中包含它读取的文件。
OpenCode其会话会存储在自身的数据库中,路径为~/.local/share/opencode
Cursor每个会话会存储在自身的数据库中,路径为~/.cursor/acp-sessions

目前Codex、OpenCode和Cursor暂不支持此项功能的开关。如果贵组织要求代码不得存储在笔记本电脑上,可在策略中仅允许使用Claude Code(详见下文)。

贵组织允许的选项

所有者或管理员可在设置 → 身份与访问权限 → 组织策略, 在人员设备上的编码智能体,针对所有套餐均适用:

  • 允许在人员设备上运行编码智能体。该功能关闭时,所有角色都会在其模型上运行,包括配置文件中已分配给智能体的角色。
  • 每个智能体对应一个开关贵组织可选择是否启用,同时还能指定该智能体在设备上保留的内容。一旦所有智能体均开启,后续CoRoid推出的新智能体也会自动启用。

AI的配置文件仅会显示策略允许的智能体,且角色无法重新分配给其他智能体。策略更改前已分配的角色会保留原有分配,配置文件中会标注该角色运行于其模型上。项目的策略可缩小组织的允许范围,但绝不会扩大允许范围。

智能体能做什么、不能做什么

  • 仅限CoRoid的工具。各智能体自身的工具(如Shell、文件编辑、网页搜索、专属MCP服务器及连接器)在会话期间会被关闭,具体由对应智能体决定。任何使用其他工具的请求都会被拒绝。
  • 不会涉及设备上的任何内容。智能体不会在您的代码检出目录中工作,也获取不到设备上的文件。CoRoid同样无法访问设备:连接器仅会向CoRoid请求工作任务,并反馈智能体的输出结果。
  • 遵循相同的校验规则。智能体所做的变更会经过与模型工作相同的QA审核、校验流程,并受步骤限制规则的约束。
  • 发送的内容角色所需的内容(包括代码、需求、工具输出结果以及附件中的图片)会被发送至机器,再经由该机器上的登录凭证传递给对应的智能体供应商。如果贵组织要求将代码存储在特定的供应商处,在给智能体分配角色前需提前考虑这一点。

成本与记录

智能体的推理开销由执行任务的设备所属人员承担,而非计入CoRoid的模型费用中。任务活动会显示此类运行记录,例如:Ada笔记本电脑上的Codex(gpt-6-luna)· 不计入计费,绝不会显示为0个令牌。如果某个角色使用了云端模型,该部分仍会按常规方式计费。

CoRoid会记录其分配给机器的每一项工作:所用机器和智能体、模型名称、任务结束状态以及工具调用次数。

导出与导入

分配的智能体及其模型会随配置文件一同导出,组织策略中选择的智能体也会随组织策略导出。对于没有本地智能体、无法使用该智能体或策略不允许使用该智能体的组织,导入时仅会包含云端模型,导入提示中会说明这一点。请参阅导出与导入设置。