使用智能体
Codeg 不附带自己的模型。它是一个为智能体而生的工作区——它连接到你已经在运行的编程智能体 CLI，例如 Claude Code、Codex 和 Gemini，并给它们每一个都提供同一套界面：同一个 composer、同样的文件和 diff、同样的 git 和终端。你选择由哪个智能体处理一段对话，而它周围的一切都保持不变。
本页涵盖要点——启用一个智能体、确认它已准备好运行，以及开启一个会话。相邻的三个页面讲得更深入：支持的智能体是完整名单，自定义智能体介绍如何添加名单之外的智能体，而认证与模型介绍登录和选择模型。
智能体的工作原理
每个智能体都是一个独立的命令行程序。当你开启一个会话时，Codeg 会把该程序作为后台进程启动，并通过 Agent Client Protocol（ACP）与它通信——这种共通的语言让一个工作区能够驱动许多不同的智能体。这正是无论你选择哪一个，体验都保持一致的原因。
Codeg 开箱即支持十五个智能体，通过两种方式交付——而且它会为你安装和更新它们：
- 大多数通过 npx（一个 npm 包）运行，因此它们需要你的机器上装有 Node.js。
- OpenCode、Cursor 和 Google Antigravity 是原生二进制文件，由 Codeg 为你的平台下载（Cursor 自带运行时，因此同样无需 Node.js）。
由于 ACP 是一项开放协议，这十五个并不是上限：你可以自己注册任何其他兼容 ACP 的智能体——从该协议的公开注册表，或从它的 distribution JSON——Codeg 会以同样的方式驱动它。→ 自定义智能体
对于每个智能体，有两件事是分开跟踪的：它是否已启用（允许出现在 Codeg 中），以及它是否已安装（实际存在于你的机器上）。二者相互独立——你可以在安装某个智能体之前先启用它，等时机到来时 Codeg 会帮你安装它。
启用一个智能体
智能体在设置 → 智能体中管理（标题为 Agent SDK Management）。左侧的智能体列表包含每一个受支持的智能体；选择一个即可在右侧查看它的详情。所有智能体默认都已启用，因此通常无需开启任何东西——但每个智能体标题栏中的启用开关可以让你隐藏那些你不使用的。右上角的 + 添加自定义智能体按钮，则是你把这份列表扩展到内置十五个之外的入口。→ 自定义智能体
只有已启用的智能体才会出现在 composer 的智能体选择器中。把那些你永远不会碰的禁用掉，可以让列表保持简短；如果你把所有的都禁用了，composer 只会提示你打开智能体设置并重新启用一个。这个开关的影响还不止于选择器：你关闭的智能体也会从其他智能体可委派的目标中被剔除。
确认它已就绪——预检
打开设置 → 智能体，Codeg 会对每个智能体运行一次预检检查——一份快速的健康报告，让你在依赖它之前就知道它确实能运行。你会看到一行版本状态（最新版本与本地已安装版本的对比，或未安装），随后是一份简短的核对清单，每一项都标记为 PASS、WARN 或 FAIL。
它检查什么，取决于智能体是如何交付的：
- npx 智能体——检查 Node.js 和 npm 是否已安装且版本足够新（每个智能体都设定了一个最低 Node 版本）。
- OpenCode 和 Cursor——检查你的平台是否受支持、二进制文件是否已下载（OpenCode 还会安装它的插件）。
每一项未通过的检查旁边都配有一个修复按钮——安装 Node.js、安装插件等等——版本行还会按需提供安装、升级或卸载。在 Codeg 之外改动了什么？刷新检查会重新运行预检。
自己装过某个智能体的 CLI？ Codeg 会认这一点。在它没有自己托管的安装记录时，它会在系统中探测该命令——通过 npm list -g 找 npx 包、在你的 PATH 上找二进制文件，或使用直白的 --version 惯例——并报告真实版本，而不是未安装。既然会话本来就优先使用你 PATH 上的安装，这只是让版本行与实际运行的东西保持一致。Claude Code 和 Codex 是例外——Codeg 在这两项上探测的是一个有着自己可执行命令名的 ACP 适配器，而不是你已有的 claude 或 codex。→ ACP 适配器
而对这两个智能体，面板现在会自己把话说清楚。 "我终端里明明有 claude，Codeg 却说没装"——这件事足够令人费解，所以 Codeg 就地作答：智能体名称旁边有一个 ACP adapter 徽章，而它预检的第一行就是一段 ACP 适配器说明，并带有一个了解更多链接。它读的是你这台机器的实际情况，而不是照本宣科：如果找到了你自己的 CLI，它会说明在哪里找到的，指出它真正需要的是哪个适配器包，并说明两者可以共存、读同一个配置目录，因此不需要再登录一次。连接失败时也同样具体：它会告诉你缺的是 SDK 还是 ACP 适配器。
预检检查的是底层环境，而非登录
预检确认的是运行时、版本和安装情况——而不是你是否已登录。让一个智能体完成认证（用它自己的订阅、一个 API 密钥或一个自定义端点）是一个单独的步骤。→ 认证与模型
当 Codeg 与你的终端说法不一致时
有时某个智能体在你的终端里运行得很好，但 Codeg 却坚称它没有安装。这几乎总是 PATH 差异：从程序坞启动的桌面应用不会像终端那样继承 shell 的配置，因此由 nvm、fnm 或 Homebrew 安装的 Node 对它来说可能是不可见的。
诊断——位于预检列表旁边，以及会话被拦截时出现的横幅上——会运行环境诊断来查明原因。它探测的是应用本身如何解析这些内容，而不是你的 shell：它看到的 Node 和 npm、npm 全局前缀、它在哪些位置查找过该智能体的可执行文件、任何版本管理器目录，以及最有用的部分——与你的登录 shell 的对比，列出你的终端有、而应用没有的那些 PATH 条目。它最后会给出一个直白的判断，例如"该命令在你的终端中能解析，但在应用中不能——这是 GUI PATH 差异"，并常常给出具体的解决办法，比如彻底重启应用。全部复制可以把整份报告放到剪贴板，便于提交问题反馈。
预检会在你每次打开该界面时自行运行；而诊断是当预检与实际情况不符时，由你自己运行的更深层探测。
配置一个智能体
大多数智能体一经安装就能工作，但每个智能体的详情面板都有许多可供你调整的地方——而且有两种方式来做：用可视化控件处理日常设置，或用智能体的原始配置文件处理任何 UI 未暴露的内容。
- 可视化设置。 面板将常见选项以普通表单控件的形式呈现——登录、模型选择、自定义端点、推理强度，以及每个智能体自己的各种开关——因此你很少需要手动编辑任何东西。登录和选择模型在认证与模型中介绍。
- 环境变量。 在智能体启动时传递给它的
KEY=value键值对。 - 配置管理。 直接从 Codeg 编辑智能体自己的原生配置文件（它的 Native JSON Config），用于处理可视化控件触及不到的设置。
- 拖动可重新排序。 智能体列表的顺序同时也是一种偏好设置——当没有指定其他智能体时，第一个已启用的智能体就是 Codeg 会选用的那个（详见下文）。
在会话打开期间更改某项设置，该会话会继续以它旧的配置运行——Codeg 不会在任务中途打断你。取而代之的是，一个横条会出现在对话顶部，提示它仍在使用先前的配置；点击重新连接以应用，会话就会带着新设置重新加载，同时保留其完整历史。无需关闭再重新打开任何东西。
当智能体不接受某项设置时
composer 里提供的一部分选项其实是一次请求，而不是命令——智能体会回复它实际采纳了哪些。挑一个某个智能体不接受的模型或模式，以前看起来就像下拉框莫名其妙地弹了回去。现在 Codeg 会说明它实际采纳的是什么，并保留你的偏好供下次使用：一次拒绝往往只针对这一个会话，而不是这个选择本身——一次在对话中途被拒绝的模型切换，换到新会话里常常就成功了。
让智能体自己处理文件和命令
通常情况下，智能体的文件读取、文件写入和终端命令都由 Codeg 通过协议代为执行。这很方便——但它意味着这些操作跑在 Codeg 的进程里，落在智能体给自己套的那层沙箱之外。一个配置了「拒绝读取 **/.env」的智能体没法对一次由它委托出去的读取执行这条规则：它自己的审计日志会记录该策略已应用、无违规，因为它所控制的一切从来没有真正接触过这次访问。
每个智能体页面上、环境变量编辑器旁边的一个开关——让智能体自己处理文件和命令——会把这三样交还给它。此时 Codeg 两个通道都不再通告，即便被调用也会拒绝，于是智能体在自己的规则之下做自己的 I/O。
它默认关闭，原因就写在开关上：Codeg 自身不提供沙箱，因此只有当智能体确实配置了沙箱时才打开它。 大多数智能体并不带沙箱，所以对它们而言，打开这个开关只是用一个能用的文件通道换来了什么都没有。
它同时会收走委托能力
打开它会为该智能体去掉委托工具，因为 delegate_to_agent 是通往同一个房间的第三扇门——它让 Codeg 在自己的进程树里再起一个智能体，再把输出转发回来，而这恰恰就是这个开关要堵上的那处泄漏。多智能体协作面板会点名这条规则当前适用于哪些智能体，而不是在工具其实没发过去的时候仍显示「已启用」。在该智能体的环境变量里设置 CODEG_ACP_HOST_TOOLS=agent 效果相同。→ 配置
OpenCode：不用写 JSON 的权限配置
OpenCode 用 opencode.json 里的 permission 块来决定哪些操作可以无人值守地运行。它设置页上的一张权限卡片替你编辑这个块：
- 自动接受所有权限——一个开关，一条放行一切的规则。它同时会清掉其他还能拦下运行的地方，因为残留的按智能体配置块或旧版配置块会悄悄地把它覆盖掉。
- 全局默认值——那条
*规则：对下方没有单独覆盖的一切采取允许、询问还是拒绝。 - 按工具的权限——OpenCode 已发布 schema 中所列的每个工具各一项：执行 shell 命令、修改文件、读取文件、访问工作目录之外的路径、启动子智能体、加载技能、搜索、抓取网页等等，每一项都配有一行说明它涵盖什么。
- 对支持模式匹配的工具还有细粒度规则——
*匹配任意字符，?精确匹配一个，开头的~展开为你的主目录。
这张卡片真正要解决的坑是顺序。OpenCode 会把整个块摊平成一个列表，并取最后一条匹配，因此写在 bash 之后的一条 * 会悄悄把它覆盖掉——你精心写下的规则确实在文件里，却什么也没做。Codeg 总是把 * 写在最前面；而一个反着写的文件会被标出并附上「修正顺序」按钮，而不是被当作正在生效的样子渲染出来。当两条互相重叠的模式并不存在唯一正确顺序时，它会如实说明，把选择权留给你。
权限块之外的每一个键都会原封不动地熬过这次编辑，而一个 Codeg 无法解析的文件会让可视化编辑器暂停，而不是被改写。
Pi：项目信任
Pi 会加载仓库自带的 .pi/ 文件——设置、技能、提示词，以及 .pi/extensions，那是一些 JavaScript 模块，其顶层代码会在 pi 启动时以你的权限运行。它对某个文件夹是否这么做，取决于 pi 自己的信任决定；而从 0.25 起，这个决定归你。
当你在一个带有这些文件、且尚无任何信任记录覆盖它的仓库里打开 Pi 会话时，对话中会出现一条提示。查看…会打开一个对话框，列出它找到的每一个文件，标出其中会执行代码的那些，并说明两件容易被忽略的事：这个回答会被它内部的每一个文件夹继承，而且它写入的是 pi 自己的信任文件，因此你自己在终端里运行 pi 时同样适用。选择信任会让 pi 重启，因为它只在启动时解析一次信任关系；而选择不信任则不会，因为正在运行的那个进程本来就在跳过这些文件。
pi 设置页上的项目信任卡片列出你已经做过决定的每一个文件夹，每行都带一个撤销。
如果你在 0.25 之前用过 Pi
早先的版本会把它启动过 pi 的每一个文件夹都标记为受信任，且从不询问——这足以让「在一个刚克隆下来的仓库里创建或恢复一个 Pi 对话」就运行掉它自带的任何 .pi/extensions，没有发出任何提示词，对话记录里也什么都没有。去掉这个行为并不会收回它已经写下的授权，因此那些文件夹现在会阻止启动，直到你确认它们，并且每一条都会列出来供你查看。它们被保留而非删除，是因为 pi 的那个文件不记录来源——删除它们会悄悄撤销你自己在 pi 里做出的决定。问题编号 #446。→ 隐私与安全
Pi：自定义供应商上的思考强度
只有当一个模型声明了自己会思考时，pi 才会为它发送思考强度——而一个未声明的模型，它的每一档都会被压到 Off，这就是以前在自定义供应商上一碰 composer 的思考强度选择器它就弹回去的原因。
pi 页面上的思考卡片就是你做这个声明的地方：一个开关、pi 接受的六个档位（以标签形式呈现），以及折叠起来的、每一档实际发出去的值——一个期望收到 LOW/HIGH 的端点需要的正是这个。这个列表不能自由填写，因为 pi 的也不能；六个之外的名称会被适配器拒绝。默认档位的下拉框只会收窄到你实际开放出来的那些档。
Codex：沙箱与审批
Codex 的面板中有一个沙箱与审批分组——对应两个问题：它能触及多少，以及何时停下来询问：
- 审批策略——Codex 请求许可的积极程度：按需请求（由它自行决定何时询问）、不受信任（只有已知安全的只读命令才会无人值守运行）、从不（完全没有提示），或精细，即按提示类型分别设置——shell 提权、策略规则、技能脚本、权限请求以及 MCP 提示——每一类要么展示给你，要么自动拒绝。若不作设置，它会遵循 Codex 自己"按需询问"的默认行为。
- 沙箱模式——它能写入什么：只读、工作区可写或完全访问（无沙箱）。工作区可写还会增加额外可写文件夹（绝对路径，每行一个），以及用于网络访问、是否排除 TMPDIR 和 /tmp 的开关——默认全部关闭。
有两点需要了解：这些会写入你全局的 ~/.codex/config.toml，因此 codex CLI 及其 IDE 会话也会读取它们；而且它们是线程默认值——它们管辖 Codex 自行开启的那些回合，而普通提示则遵循 composer 自己的审批预设。更改后需重启会话方能生效。在 Windows 上，除非你启用了 Codex 的实验性 Windows 沙箱，工作区可写会回退为只读。
::: warning「不受信任」在这里没有对应项 在 0.25 之前，这两项设置在每一个 Codeg 会话里其实都是失效的——适配器每个回合都会重新发送它自己的策略，于是一个被明确设为只读的沙箱可能被悄悄放宽成可写工作区。现在 Codeg 会依据你的配置来决定启动方式，并以沙箱模式为准，因为那正是猜错会扩大访问范围的那条轴：它绝不放宽沙箱，也绝不在没有精确匹配的情况下选中一个免审批的预设。
不受信任是唯一无法被兑现的那一档——ACP 适配器只有三种审批预设，其中没有它，因此 Codeg 会话会回退到按需询问：由模型决定何时发问，而沙箱本就允许的操作不再提示。面板会如实说明这一点，而不是让这个控件看起来生效了。如果你原本是靠「不受信任」来做约束的，请改为收紧沙箱模式。（此外，当某个 default_permissions 配置档覆盖了根级键时，Codeg 会干脆不做任何推导——因为 Codex 会通过那个配置档解析，推导出的预设反而会把它覆盖掉。） :::
同一个面板里还有两个开关值得知道：
- 允许在默认模式下提问。 Codex 只在 Plan 模式下才允许调用它的
request_user_input工具，所以在普通的一轮里，它的提问会被直接拒绝，你根本不会收到任何提问卡片——智能体问了、被告知工具不可用，然后继续靠猜。打开这个开关，它在普通轮次里也能向你发问。它会把[features].default_mode_request_user_input写进你的~/.codex/config.toml—— 与 Codex 自己的codex features enable所设置的是同一个键，而这个标志在上游仍处于开发中。功能标志在线程创建时解析，因此它在你下一个会话中才生效，而不是当前已打开的这个。 - 自定义模型可以按两种形态添加。默认那种克隆的是原生 GPT 条目；如果要接第三方网关，请选 OpenAI 兼容那种，Codex 会发出一个朴素的 Responses 请求——不带 code-mode 工具、不带 multi-agent、不带 responses-lite、不带自定义的 apply-patch 工具——而这些正是这类网关所实现的全部。它是叠在普通逐项覆盖之上的一个预设，所以已经存在的模型也可以随时在两种形态之间切换。
Claude Code：归属标识与遥测
Claude Code 的面板带有两个开关，Codeg 特意让它们与 Claude Code 自身的默认值相反：
- 向接口发送归属/计费标识——关闭，因此 Codeg 不会添加该标识性请求头。
- 禁用遥测或多余的网络请求——开启，因此非必要流量保持关闭。
Codeg 会明确写入这两项，而不是任其隐含，因此面板上显示的就是实际生效的。如果你的环境需要，可以把任一项改回去——比如按归属请求头计费的受管账户。→ 隐私
Qoder：登录，或者给无头机器一个令牌
Qoder 的面板开头是一行账户状态，说明你是否已登录，以及 Qoder 自己记录的认证方式。登录走的是 Qoder 自家的浏览器流程——面板会给出可以直接粘进终端的那条 qoder login 命令，并且写的是 Codeg 所管理的那一份的完整路径，因为那一份位于 Codeg 的缓存里而不在你的 PATH 上，光敲 qoder login 只会得到「命令未找到」。跑完它，再点刷新。
对于打不开浏览器的机器——服务器、容器——则有一个个人访问令牌字段，以 QODER_PERSONAL_ACCESS_TOKEN 传入。留空即使用账户登录。
Qoder 读取的其他一切都在同一个文件里，$QODER_CONFIG_DIR/settings.json（默认 ~/.qoder），与 qoder CLI 共用——而高级：原始 settings.json 会原样编辑它。这是刻意的：把整个文件写回去，也是删除一个键的唯一方式，而逐字段的编辑器表达不了这件事。
模型和思考强度不在这里。Qoder 通过 ACP 上报它们，所以由 composer 自己的选择器按会话掌管。→ 认证与模型
Antigravity：由一个文件决定它如何登录
Antigravity 的 ACP 服务器只从一个地方读取它的认证意图——$GEMINI_HOME/antigravity-acp/settings.json 中的 auth.type——没有它，每一个新会话都会直接失败，报需要认证。Codeg 会在启动时替你写这个文件，所以你不会撞上这堵墙：当文件和这个面板都没有指定方式时，它写入使用 Google 登录，而这只不过让服务器打开一个浏览器而已。文件中已有的方式绝不会被覆盖。这个面板，是你换成别的方式的地方。
四种方式，各自只要它真正需要的东西：
| 方式 | 需要什么 |
|---|---|
| 使用 Google 登录 | 你的 Google 账户，适用于包括免费档在内的任何 Antigravity 套餐。第一个新会话会打开浏览器完成登录，之后令牌被缓存复用 |
| Gemini Enterprise | 一个 GCP 项目和区域，外加第一个会话时的浏览器登录 |
| Gemini API 密钥 | 一个 Gemini Developer API 密钥，以 GEMINI_API_KEY 传入 |
| Gemini Enterprise Agent Platform | 即原先的 Vertex AI。要么单独用一个 API 密钥，要么用项目和区域配合应用默认凭据（gcloud auth application-default login） |
如果某种方式所需的条件没填齐就保存，面板会点名缺了什么并拒绝保存，而不是放任会话在之后以一个你只能靠猜的理由失败。
有两点行为值得知道：
- 你所选方式之外的凭据会在启动时被清除。 留在你 shell 里的
GEMINI_API_KEY，无法悄悄接管一个你按 Google 登录配置好的会话。 - 如果 Codeg 写不了那个设置文件——比如你把它设成了只读——它会明说，而不是假装保存成功了。你的选择在 Codeg 这一侧存下了，但 Antigravity 仍会按那个文件所写的方式认证，所以要么你自己去设
auth.type，要么把文件挪开再保存一次。
模型和会话模式通过 ACP 传来，因此它们在 composer 里而不在这里。
开启一个会话
开启一个新对话，composer 会显示一个智能体选择器——一排药丸形按钮，每个已启用的智能体一个。点击其中一个，Codeg 就会连接到它；接着，在 composer 中选择一个模型和一个模式。这两个列表都来自智能体本身，而非 Codeg，因此可供选择的内容取决于你正在运行哪个智能体。你对智能体的选择会在你发送第一条消息后锁定——一段对话会一直由开启它的那个智能体来处理。
默认用哪个智能体？ Codeg 按以下顺序选择：
- 文件夹的默认智能体，如果你设置过的话（文件夹菜单 → 设为默认智能体）。
- 否则，就是你在设置 → 智能体中排序里的第一个智能体。
因此，按文件夹设置的默认值总是优先，而列表顺序是后备方案。→ 工作区 介绍了如何设置文件夹的默认值。
当你第一次在会话中使用某个智能体时，你会看到 正在连接…，此时 Codeg 正在启动 CLI 并完成握手。如果它无法连接——智能体被禁用、未安装、在你的平台上不受支持，或响应缓慢——Codeg 会弹出一个提醒（状态栏中的铃铛），说明出了什么问题，并指引你前往设置 → 智能体去修复它。
连接状态
在你工作时，底部的状态栏会显示活动的智能体及其状态——正在连接…、已连接、正在响应… 或 已断开——当智能体忙碌时，它的图标会跳动。
你没有在看的会话可能会在闲置几分钟后断开连接以释放资源，但你正在活跃使用的标签页会保持连接，而当你回到某个会话时，Codeg 会自动重新连接。