# 接入 AI 编程工具

AI Light 当前面向最终用户提供 Claude Code、Codex 和 WorkBuddy 的一键接入。连接成功后，工具支持的工作、等待、完成和失败状态会自动同步到 AI Light。

## 开始之前

请确认：

- 目标 AI 编程工具已经安装；
- AI Light 应用正在运行；
- 电脑已安装 Node.js 和 npm；
- 首次安装配套组件时可以访问 npm 软件源。

“接入”页面会先检查运行环境。AI Light 需要 Node.js 20 或更高版本、可执行的 npm，以及 AI-Light Adapter。检查结果会显示在“运行环境”卡片中；环境未就绪时，卡片会给出安装、升级、选择文件或恢复自动检测的操作。

如果 Adapter 尚未安装或版本不兼容，点击工具卡片的“连接”后，AI Light 会先显示确认安装或升级的提示。确认后才会通过 npm 安装或升级，并继续写入该工具的 Hook。安装过程不提升权限，也不修改系统 PATH。

如果 Node.js、npm 或 Adapter 路径无法自动找到，可以展开运行环境详情，选择实际的可执行文件。选择的是文件而不是文件夹：Windows 上的 Node.js 通常是 `node.exe`，npm 可选 `npm.cmd` 或 `npm-cli.js`。完成修复后选择“重新检测”。

检查或恢复操作失败时，运行环境卡会保留上一次检测结果并显示错误；可以重新检测，或复制诊断信息用于排查。

## 连接 Claude Code

1. 打开“接入”页面。
2. 找到 Claude Code 卡片。
3. 选择“连接”。
4. 等待卡片显示“已连接”。
5. 新建一次 Claude Code 任务，检查 AI Light 状态是否变化。

## 连接 Codex

1. 打开“接入”页面。
2. 找到 Codex 卡片。
3. 选择“连接”。
4. 等待卡片显示“已连接”。
5. 新建一次 Codex 任务，检查 AI Light 状态是否变化。

实际可用能力取决于本机 Codex 版本及其 Hook 支持情况。云端运行、没有经过本机 Hook 的任务不会自动同步。

## 连接 WorkBuddy

1. 打开“接入”页面。
2. 找到 WorkBuddy 卡片。
3. 选择“连接”。
4. 等待卡片显示“已连接”。
5. 新建一次 WorkBuddy 任务，检查 AI Light 状态是否变化。

AI Light 只修改 `~/.workbuddy/settings.json`。WorkBuddy 当前提供的 Hook 可以同步工作、等待提问、本轮完成和会话结束，但没有可靠的失败事件，因此不会根据输出内容猜测“出错了”。

## 连接操作会修改什么

AI Light 会安装或调用配套组件，并在目标工具的配置中加入由 AI Light 管理的 Hook。配置写入采用合并方式：

- 不覆盖已有的其他 Hook；
- 重复连接不会反复添加相同配置；
- 配置变更前会保留必要备份；
- AI Light 不可用时，不应阻断 AI 编程工具本身的运行。

日常使用不需要知道服务端口，也不需要手动填写网络地址。

## 断开接入

在已连接的工具卡片中选择“断开”。AI Light 只删除自己管理的 Hook，保留工具中的其他配置。

断开 AI 编程工具不会：

- 卸载 AI Light 应用；
- 断开 AI Light 设备；
- 删除用户主题；
- 删除目标工具的其他 Hook。

## 如何确认同步正常

不要只看“已连接”标签。完整验证应包含：

1. 发起真实任务；
2. “状态”页面变为“工作中”；
3. 请求授权或输入时变为“等你回复”；
4. 任务结束时变为“已完成”或“出错了”；
5. 已连接的实体状态灯同步变化。

如果卡片显示已连接但任务状态不变化，请查看[接入已连接，但任务状态不更新](./troubleshooting.md#接入已连接但任务状态不更新)。