诊断智能体
本指南介绍如何查明某个智能体为何不再产生运行。
请自上而下排查：先看智能体自身的运行，再看它的后端，然后是服务器，最后是宿主。
1. 检查智能体的运行历史
标题为“1. 检查智能体的运行历史”的部分设置 → 工作区 → 智能体 → 选择该智能体 → 日志。
每条运行都会显示状态徽章、时长（进行中时显示“Running…”）、开始与完成时间、PID 以及它所使用的适配器。查看 会打开该运行的原始事件流。停止 会终止正在运行的进程，并把该运行标记为“Killed by user”；页眉中的 终止运行 会对该智能体所有正在进行中的运行做同样的事。
可以这样解读：
- 完全没有运行 —— 派发从未发生。编辑器中的提及由
@加单词字符（字母、数字、下划线）构成。解析方式是与智能体名称做精确匹配或前缀匹配，因此@code-reviewer会被解析为code，仍然可以唤醒名为code-reviewer的智能体。名称中带空格就无法作为一个词元被提及。这时请进入第 2 步。 - 一开始就报错结束的运行 —— 打开 查看。启动后端失败会在这里表现为进程错误。
- 卡在“Running…”的运行 —— 先停止它，再检查该智能体在 设置 标签页中的 静默超时。未设置超时则使用各模式的默认值。
- 已完成但没有有用输出的运行 —— 对于未交出所声明交付物的运行，运行日志的状态仍会停留在
completed；可信的信号是摘要文本，而不是徽章。
日志标签页不显示成本。要查看花费，请使用 可观测性 → 洞察 中按智能体划分的表格。
2. 检查智能体的后端
标题为“2. 检查智能体的后端”的部分设置 → 服务器 → 模型提供商（/settings/server/providers）。
检测到的运行器 列表会显示每个适配器及其探测结果——已安装的版本、“正在检查…”，或“未找到”——以及解析出的路径，和对已找到的 CLI 显示的能力标签。点击页面页眉中的 刷新 即可重新探测。
探测运行在托管 cc_server 的机器上，而不是你正看着的这台机器上。如果你使用的是 Web 客户端或已配对的设备，“未找到”意味着服务器宿主上缺少该 CLI。
有两件事需要确认：
- 该智能体到底有没有设置适配器。 适配器为空的智能体会被派发到 Control Center (built-in)，运行日志会记录
cc-harness，因此转录会写明实际运行的是什么。如果模型也没有设置，它会向 Anthropic 请求其默认模型——除非你已连接 Anthropic 账户，否则会以No credential for provider "anthropic"失败。预置的专家智能体发布时都没有适配器。 - 内置适配器有没有模型。 它的模型列表实时来自本页下方已连接的提供商，因此没有存储凭据的提供商贡献零个模型。
适配器目录本身是固定的——无法注册新的适配器。你在这里可以按适配器更改的是它的启动参数和环境变量。请注意，在解析凭据时，按适配器的环境变量覆盖会静默压过已连接的提供商账户。
3. 检查服务器
标题为“3. 检查服务器”的部分设置 → 服务器 → 连接与状态（/settings/server/connection）显示此客户端正在与哪台服务器通信，以及它报告了哪些内容。
对于无界面服务器，GET /healthz 无需客户端就能提供同样的信息。它按设计不要求认证，并且对 CORS 开放：
curl http://localhost:9030/healthz它返回服务器的状态、以秒计的运行时长、实时连接数、绑定的端口、构建版本与 git SHA、工作区 schema 版本、RPC 目录版本、服务器 id、名称与身份指纹、绑定是否不安全，以及一个带有 watching / indexing / pending 计数的 codeGraph 块。当某个缓存曾有过流量时，它还会包含一个 caches 块；演示服务器会额外给出 demo: true。
当某项改动“在测试里能用，在应用里却不行”时，有两件事值得了解：
- 桌面端会优先启动 预构建 的
cc_server二进制文件，而不是源码。新的 RPC 操作或 MCP 工具在二进制文件重新构建之前不会出现；当子进程的 git SHA 与应用的不一致时，启动日志会记录一条警告。 - 如果启动的服务器在 20 秒内没有打出就绪横幅，桌面端会终止它并落到错误界面。
4. 检查宿主
标题为“4. 检查宿主”的部分设置 → 服务器 → 诊断与隐私（/settings/server/diagnostics）是宿主层面的页面。它包含：
- 沙箱 —— 总开关、检测到的后端和安装提示。只有检测到的后端来自服务器；参见下方的警告。这里没有重置控件。
- 语义搜索 —— 设备端嵌入模型的生命周期：已安装、正在下载并显示百分比、未安装，或安装出错。在它安装之前，记忆和代码搜索都只按关键词进行。
- 系统行为 —— 智能体运行时保持电脑唤醒。
- 日志级别 —— 在复现故障之前先把它调高。
- 隐私 —— 是否允许把原始 diff 内容转发给智能体的模型，以及是否发送崩溃报告。
常见故障
标题为“常见故障”的部分运行始终不开始，且适配器显示“未找到”
标题为“运行始终不开始，且适配器显示“未找到””的部分请 在服务器宿主上 安装该 CLI，然后在模型提供商页面上点击 刷新。或者把该智能体切换到内置适配器——它不需要任何 CLI——并在同一页面上连接一个提供商。
智能体无法推送或创建 pull request
标题为“智能体无法推送或创建 pull request”的部分看看 git 或智能体打印了什么。Control Center policy: … 表示某条操作规则拒绝了它，或者某个审批没有得到回应：在 设置 → 工作区 → 智能体权限 中检查推送到远程仓库和打开 pull request。如果 git 提示 Control Center 没有能推送的 GitHub 凭据，请在该仓库上安装 GitHub App，或连接 GitHub。
语义搜索返回不了有用的结果
标题为“语义搜索返回不了有用的结果”的部分检查 设置 → 服务器 → 诊断与隐私 → 语义搜索。在嵌入模型安装之前，搜索只按关键词进行。在模型安装之前写入的行永远不会被回填，因此此后它们仍然只能靠关键词检索。
服务器完全无法启动
标题为“服务器完全无法启动”的部分原生库是必需的，而且没有降级模式。缺少某个 dylib 会让 cc_server 拒绝启动，并在错误中指明缺失的那一个。请用 scripts/natives/build_natives.sh 暂存原生组件，然后重新构建服务器二进制文件。
某项操作被静默拒绝
标题为“某项操作被静默拒绝”的部分在未连接任何审批人的情况下，prompt 护栏决定会被拒绝，这是有意为之。请在 设置 → 工作区 → 智能体权限 下检查该工作区的规则。