AWR 不运行你的 agent。agent 客户端（Codex、Claude Code、Kimi、Cursor、 Grok）用自己的工具完成工作；AWR 为同一个已初始化的项目提供当前的项目 事实、工作上下文、认领和可恢复的会话记忆。AWR 会话记录中的 provider 和 model 标签只是元数据——它们绝不会启动或配置客户端。
每个受支持的客户端都遵循同样的模式：
- 从 AWR 源码检出构建两个可执行文件：
cargo build --locked -p awr-cli -p awr-mcp
- 从项目经过评审的来源清单初始化目标项目（见快速上手）， 然后把
awr-mcp服务器注册到客户端，用--project指向项目的绝对 路径。每个服务器绑定一个规范的项目根目录；不同项目的服务器要使用 不同的名称。 - 验证连接——磁盘上的配置文件不等于活跃连接——并在开始任何工作之前 用一次状态读取确认项目身份。
- 按共享的会话生命周期工作：启动或恢复会话、读取上下文、交接前保存 检查点、停止时结束会话。见 CLI 和 MCP 工具。
下面各节给出每个客户端的合并路径、配置和注意事项。凡客户端声称支持 自动生命周期钩子，在你亲眼见到真实的触发和回执之前都应视为未验证； 手动检查点/恢复流程总是可用的。
Codex
Codex 只对受信任的项目加载项目配置；它的 CLI、桌面端和 IDE 客户端在 同一台主机上共享 MCP 配置。两种方案选一：把 MCP 配置模板合并到项目的 .codex/config.toml（替换其中的两个路径，保留已有配置），或在用户级 注册：
codex mcp add awr -- /absolute/path/to/awr-mcp \
--project /absolute/path/to/initialized/project
codex mcp get awr --json
在客户端的 /mcp 视图中确认 awr 服务器已连接，并在工作前核验项目 身份；配置了服务器不等于连接已激活。预期的读取工具： awr_project_status、awr_work_ready、awr_work_get、 awr_context_compile、awr_search。变更工具：awr_work_transition、 awr_event_append、awr_evidence_record。该服务器不需要模型 API 密钥。
Codex 是唯一拥有自动生命周期钩子安装器的客户端：使用 awr client install 可以在 --accept 之前预览确切的配置内容。安装会 保留已有钩子，绝不会自动批准其信任。Codex 文档记录了 SessionStart （startup|resume|clear|compact）、PreCompact（manual|auto）和 SessionEnd（建议性、短超时）。请在客户端中验证触发的实际送达——在 此之前，交接或压缩前请手动保存检查点。
Claude Code
Claude Code 通过一个具名的受控适配器连接（适配器 id 为 claude_code）。它不可自动启动：AWR 不会替你启动 Claude Code，也不会 自行停止它——这些步骤始终由你完成。适配器支持的是读取状态、重连/恢复 和结果取证。
操作路径：
- 自己启动 Claude Code。
- 用通用客户端和原生对话 ID 把它绑定到 AWR：
awrj client bind --client generic --external-session claude:<native-id> \
--work "$AWR_WORK" --session "$AWR_SESSION"
- 需要 AWR 观测数据时，通过共享 CLI 的外部执行报告上报阶段。
- 重试时，先重连同一个执行身份，再开始任何新工作。
Kimi
本指南针对 Kimi Code 0.41.0（检查日期 2026-09-08）；更早的 kimi-cli 版本使用不同的配置路径和参数，因此请先查看 kimi --version 和 kimi --help。使用 Kimi 的终端工具调用 AWR CLI，也可以选择通过 stdio MCP 连接同一个项目：把下面的服务器合并进项目的 .kimi-code/mcp.json （用户级：~/.kimi-code/mcp.json），保留其他条目：
{
"mcpServers": {
"awr": { "command": "/absolute/path/to/awr-mcp",
"args": ["--project", "/absolute/path/to/initialized/project"],
"cwd": "/absolute/path/to/initialized/project" }
}
}
项目配置需要工作区信任。用 /mcp-config 配置，用 /mcp 查看连接状态； 通过编辑配置添加的服务器会在新创建的会话中生效。用 awr_project_status 确认项目身份。Kimi 会话元数据的 provider 标签是 moonshot。
Kimi 自己的 kimi --continue、kimi --session <kimi-conversation-id> 和 /compact 操作的是它自己的对话；它们的 ID 与 AWR 的 ID 互不相关。 压缩之后，为同一个活跃的 AWR 会话编译上下文即可——显式的 AWR resume 只用于真正的交接。Kimi 文档记录了 SessionStart、SessionEnd、 PreCompact 和 PostCompact 钩子，但本集成不安装任何自动适配器；请 使用手动检查点流程。
Cursor
已对照 Cursor 3.18.9（2026-09-17）核验。不要为 Cursor 运行 awr client install（会报 Unsupported），也不要在绑定时传 --client cursor（会报 InvalidInput）——请使用下文所示的通用客户端 身份。把 stdio 模板合并到项目的 .cursor/mcp.json 或用户级的 ~/.cursor/mcp.json：
{
"mcpServers": {
"awr": { "type": "stdio", "command": "/absolute/path/to/awr-mcp",
"args": ["--project", "/absolute/path/to/initialized/project"] }
}
}
Cursor 的 stdio 字段表要求 "type": "stdio"，且不接受 cwd。AWR 只 需要一个绝对的 command 加上 --project。重新加载窗口，启动失败时 查看 Output → MCP Logs；当两个配置文件同时存在时，在 Customize 中确认 Agent 窗口实际附着的是哪一个。两点注意事项：
分组工具。 在当前源码树中，默认的 tools/list 返回八个域工具 （awr_query、awr_context、awr_work、awr_evidence、awr_session、 awr_continuity、awr_change、awr_compaction），而不是扁平的工具名。 通过 awr_query 探测状态：
{"child_tool": "awr_project_status", "arguments": {}}
扁平名称仍然可以调用，但不在默认目录中；只有当您的 Cursor 构建版本 无法经由域路由时，才设置 AWR_MCP_TOOL_EXPOSURE_MODE=flat。打包发布版 不暴露分组形式的 awr_query——要走这条路径请从源码树构建，并先检查 你的构建版本的工具目录。
Cloud Agents 无法访问笔记本上的 awr-mcp 或 127.0.0.1；它们需要 一个可达的 HTTPS 前门，且项目根目录在服务器侧。AWR 的共享 HTTP 服务 使用 bearer token（不是 Cursor OAuth）：
{
"mcpServers": {
"awr": { "url": "http://127.0.0.1:8080/mcp",
"headers": { "Authorization": "Bearer ${env:AWR_ENGINEERING_TOKEN}" } }
}
}
身份方面，用原生对话 ID 绑定通用客户端，并在其为空时直接失败，这样 就绝不会绑定到字面量 cursor:：
: "${HOST_CONVERSATION_ID:?set the native host conversation ID first}"
AWR_EXTERNAL="cursor:${HOST_CONVERSATION_ID}"
awrj client bind --client generic --external-session "$AWR_EXTERNAL" \
--work "$AWR_WORK" --session "$AWR_SESSION"
Cursor 在 .cursor/hooks.json 中记录了 sessionStart、sessionEnd 和 preCompact 钩子，但针对这种方言没有安装器——在你见到真实的钩子触发 和检查点回执之前，请手动保存检查点。
Grok
已对照 Grok Build 1.0.13（2026-09-08）核验。使用 Grok 的终端工具调用 AWR CLI，或从项目目录连接它的 stdio MCP 客户端：
cd /absolute/path/to/initialized/project
grok mcp add --scope project awr -- /absolute/path/to/awr-mcp \
--project /absolute/path/to/initialized/project
grok mcp doctor awr --json
add --scope project 会写入或更新 .grok/config.toml（省略该标志时 默认是用户范围）；如果 awr 已指向另一个项目，请使用不同的服务器名称。 等价的配置表是：
[mcp_servers.awr]
command = "/absolute/path/to/awr-mcp"
args = ["--project", "/absolute/path/to/initialized/project"]
在 Grok Build 中用 /mcps 查看和刷新连接，然后调用 awr_project_status 并核验项目身份。项目信任是独立的前置条件：不受 信任的文件夹会让服务器无法启动，因此请先在该客户端正常的信任流程中 审查项目。Grok 会话元数据的 provider 标签是 xai。
Grok 的原生对话续接与 AWR 的会话恢复是两回事：
grok --cwd "$AWR_PROJECT" --continue
grok --cwd "$AWR_PROJECT" --resume <grok-conversation-id>
Grok 的 --session-id 创建的是新对话——它既不是 AWR ID，也不是恢复 标志。原生压缩之后，为同一个活跃的 AWR 会话编译上下文即可；显式的 AWR resume 流程只用于真正的交接。
Grok Build 在其钩子系统中记录了会话和压缩事件，但这里没有安装任何 自动适配器；在你验证过真实的触发和回执之前，请使用手动检查点流程。 Grok 网页版的自定义连接器需要一个可达的 MCP URL——本地可执行文件路径 不能作为该 URL 输入；AWR 的共享 HTTP 服务可以承担这个角色，但部署它并 满足连接器的认证要求是另外的步骤，本指南未做验证。
