> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 更换连接并管理既有 Session

连接表示控制平面中的一个 Provider、模型或工具账户配置。更新、禁用、关闭依赖 Session 和删除连接是不同操作，分别影响配置可用性和资源生命周期。

需要连接管理权限；普通应用执行 Token 不能更新或删除连接。变更前记录连接 ID、受影响的 Session 和需要保留的执行证据。

## 更新后重新验证

Python：

```python theme={null}
import os
client.update_connection(connection_id, credential=os.environ['REPLACEMENT_CREDENTIAL'])
checked = client.validate_connection(connection_id)
if checked['status'] != 'ready':
    raise RuntimeError('Connection verification failed; keep it disabled')
client.update_connection(connection_id, enabled=True)
```

TypeScript：

```typescript theme={null}
const replacement = process.env.REPLACEMENT_CREDENTIAL;
if (!replacement) throw new Error('Missing replacement credential');
await client.updateConnection(connectionId, { credential: replacement });
const checked = await client.validateConnection(connectionId);
if (checked.status !== 'ready') throw new Error('Verification failed; keep disabled');
await client.updateConnection(connectionId, { enabled: true });
```

这是通过环境读取替换凭据的后端片段，不应打印变量内容。配置或凭据变更会使旧验证失效并禁用连接；不能在同一次更新中用 `enabled: true` 跳过重新验证。验证可能访问供应商接口，模型验证可能产生调用费用。

## 禁用的影响

对 Sandbox 和模型连接，禁用会阻止新 Session 和既有 Session 的新 Run。worker 在新 Harness invocation 前也检查，覆盖排队后禁用的情况。已经接受的同一幂等请求仍可返回原 Run，已有 invocation 的恢复和原资源清理仍需进行。

```python theme={null}
client.update_connection(connection_id, enabled=False)
```

```typescript theme={null}
await client.updateConnection(connectionId, { enabled: false });
```

禁用不是终止所有已发出外部调用的按钮，也不撤销供应商账户凭据。既有 Session 固定自己的配置，不会因为连接更新自动改成新执行定义。要使用新配置，按需求创建新 Session。

## 发布一次配置变更

区分凭据修复与执行环境变更。更新凭据后，验证和启用恢复的是可用资格，不证明新凭据仍能访问既有云资源。保留私有资源证据，便于调查账户或权限不匹配。更换连接账户不是资源迁移。

计划变更执行环境时，先识别依赖 Session、处理活动任务、准备并验证目标连接，再使用目标定义创建一个试运行 Session。真实执行所需任务并确认清理后，再将新任务导向它。既有 Session 保留固定执行配置，新验证结果不会改写该快照。

| 变更 | 需要检查的既有工作 |
| - | - |
| 禁用 Sandbox/模型连接 | 阻止新提交和尚未启动的 invocation；已接受请求的查询与清理仍需单独处理。 |
| 轮换凭据 | 就绪状态失效；重新验证后检查对既有资源的访问。 |
| 更换 Tool 账户或选定操作 | 检查固定账户/操作限制，并刷新受版本变化影响的审批记录。 |
| 删除连接 | 确认依赖 Session 已关闭且资源结果明确；删除不撤销上游账户凭据。 |

## 先清理依赖，再删除

查询依赖 Session，处理活动 Run，逐一 close 并确认云资源清理。仍有依赖时删除返回 `connection_in_use`。unknown 删除结果需要对账，不能为消除依赖而直接删除数据库记录。

完成依赖处理后调用 `delete_connection` / `deleteConnection`。它删除 Hexagon 中的连接，不删除供应商账户，也不等于在供应商侧撤销 API key。若要停用上游凭据，另行在供应商账户执行相应管理流程。

## 验收

在专用测试连接上验证：正常任务 → 禁用 → 新任务被拒绝 → 已有资源可清理 → 无依赖后可删除。更新凭据时分别测试错误凭据保持禁用和正确凭据验证后启用。核对旧 Session 初始化快照不被重写。

依据：[连接实现](https://github.com/NexusFox88/docs/blob/main/resources/modules/connections/connections.ts)、[执行边界](https://github.com/NexusFox88/docs/blob/main/resources/docs/architecture.md)。下一步：[故障恢复](https://docs.hexagon.autos/zh-CN/build/recovery.md)。

## 对照已有生命周期记录

[11 月 15 日 API 生命周期记录](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-15-connection-lifecycle.md)在实际 E2B/OpenCode/MiniMax 任务后，依次检查配置修改、无效凭据验证、恢复、显式启用、禁用、新工作被拒、禁用状态下清理以及有依赖时不能删除。使用同一上游凭据的另一连接仍有效，从而区分连接删除与账户或密钥撤销。另有 [Console 记录](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-15-connection-lifecycle-gui.md)覆盖交互编辑及验证状态。

将它作为验收范式，不要为了教程轮换共享生产凭据。使用专用连接，私下保留原目标配置。更换账户后清理失败时，保留原资源身份并调查账户访问；删除本地记录不等于删除远端资源。这些带日期的 E2B 记录不证明所有 Provider 或账户行为，也不是上文片段的新一次执行。

下一步：[凭据轮换](https://docs.hexagon.autos/zh-CN/operate/credentials.md)、[资源对账](https://docs.hexagon.autos/zh-CN/operate/reconciliation.md)、[初始化快照](https://docs.hexagon.autos/zh-CN/concepts/initialization.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.