配置 Runtime

本指南介绍如何在 Sink 中配置和管理 Agent Runtime。Runtime 定义了如何启动和运行 AI Agent（如 Claude Code、Codex 等）。

前置条件

• 已安装 Sink 二进制文件
• 了解 Agent Client Protocol (ACP) 基本概念
• 访问互联网以从 ACP 注册中心下载 Runtime

什么是 Runtime

Runtime 是一个配置项，定义了如何启动特定 Agent 的流程：

• ID: 唯一标识符（如 claude-code、codex）
• 名称与描述: 可读的 Runtime 信息
• 分发方式: 指定如何启动 Agent（通过 npm 包或本地命令）
• 环境变量: 启动 Agent 时需要的环境配置

所有 Runtime 配置存储在 ~/.sink/runtimes.json。

添加 Runtime

最简单的方式是使用交互式命令添加 Runtime：

运行创建命令

sink runtime create

此命令会：

1. 提示你选择「从 ACP 注册中心」（从官方注册中心浏览和安装）或「手动输入」（手动输入 Runtime 详细信息）
2. 如果使用注册中心：从 ACP 注册中心获取可用的 Agent 列表（仅显示具有 npm 包分发方式的 Agent），显示交互式选择菜单，然后将选定的 Runtime 写入 runtimes.json
3. 如果手动输入：提示输入 Runtime ID、分发方式（npx 或 local）、包名/命令以及参数

注意：runtime create 的 ACP 注册中心流程仅获取具有 npm/npx 分发方式的 Agent。这与 init 不同——init 通过探测本地命令来检测已安装的 Builtin Runtime（Claude Code、Codex、Factory Droid、OpenCode）。两者都会填充 runtimes.json，但机制不同。

注册中心示例

$ sink runtime create
  ✔ Sink — Create Runtime
  ◆ How would you like to add a runtime?
  │  ● From ACP registry  /  ○ Manual entry
  ...
  ✔ Fetched 5 compatible agents from ACP registry (5 total)

  ✔ Select agent runtimes to install
  ⊙ agent-x         Agent X (some-agent-x)
  ◯ agent-y         Agent Y (some-agent-y)

  ✔ Synced 1 runtime (added: 1, replaced: 0)

注意：实际显示的 Agent 名称取决于 ACP 注册中心的内容。以上示例仅供参考。

添加后，新的 Runtime 立即可用，无需重启 Gateway。

查看已安装的 Runtime

查看所有已配置的 Runtime：

sink runtime list

输出示例：

  ✔ Sink Runtimes
  ℹ claude-code — Claude Code v1.0.0
    $ npx -y @anthropic/claude-code
  ℹ codex — Codex v2.1.0
    $ npx -y @anthropic/codex --mode interactive
  ✔ 2 runtimes installed

禁用 Runtime

要禁用某个 Runtime 而不删除它，在 metadata 中设置 disabled 字段为 true：

{
  "agentRuntimes": {
    "old-agent": {
      "description": "Old Agent",
      "metadata": {
        "disabled": true
      },
      "distribution": {
        "npx": {
          "package": "@myorg/old-agent"
        }
      }
    }
  }
}

禁用的 Runtime 不会出现在 UI 中，但配置仍保留。

故障排除

问题: 运行 sink runtime create 时选择注册中心选项，出现连接错误

解决方案:

• 检查网络连接
• 确认能访问 ACP 注册中心：curl https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json
• 尝试手动添加 Runtime

问题: Runtime 启动失败，提示”找不到命令”

解决方案:

• 检查 distribution.npx.package 或 distribution.local.cmd 是否正确
• 确保 npm 包已发布或本地命令文件存在且可执行
• 检查环境变量是否正确设置

问题: Runtime 启动时缺少环境变量

解决方案:

• 确认环境变量已在系统中设置：echo $VAR_NAME
• 检查 Runtime 配置中 env 字段中的插值语法是否正确
• 若在 systemd 服务中运行，检查 EnvironmentFile 或 Environment 是否包含所需变量

后续步骤

配置完 Runtime 后，你可以：

1. 创建 Profile 将 Runtime 与 Agent 人格配置关联
2. 快速开始 创建第一个 Task