第1章 Kortix 第1章：计算机连接入门
计算机 连接你自己的机器，让智能体可以操作其中的文件、命令和应用程序。计算机是你自己的设备——笔记本电脑、台式机或服务器——通过 Kortix 连接。计算机不是沙箱。沙箱是 Kortix 为会话临时创建的云端机器。计算机是你已经拥有的设备，它跨会话保持连接。 连接的计算机是“计算机”连接器下的一个账户，就像个人 Gmail 邮箱是“Gmail”连接器下的一个账户。每个项目都内置了“计算机”连接器，无需手动添加或移除。每位成员连接自己的计算机，它会跟随成员移动：无论成员属于哪个项目、哪个工作区，它都是该成员的一个账户，无需在每个项目中单独设置。
连接你的计算机
如果你还没有连接计算机，项目侧边栏会显示“连接你的计算机”卡片。如果不需要，可以点 × 关闭；该卡片在此浏览器中保持隐藏。如果部署未启用计算机功能，此卡片也不会显示。
使用桌面应用：点击卡片上的“连接此计算机”。在弹出的窗口中批准请求。应用会安装一个后台服务，即使应用关闭也能保持连接状态，并在睡眠、网络变更或重启后自动恢复。菜单栏（macOS）或通知区域（Windows、Linux）中的图标显示连接状态，并提供与下文“你的计算机”相同的管理功能。
在浏览器中：点击卡片上的“连接你的计算机”。对话框提供“下载 Kortix 桌面版”选项，安装后可一键连接。如果不想使用应用，请选择“改用 CLI”，然后在计算机上运行显示的命令：
npx --yes @kortix/agent-tunnel@latest connect --api-url
你的计算机（桌面应用） 打开工作区菜单（侧边栏顶部的项目名称），选择“你的计算机”。旁边的圆点表示计算机状态。对话框显示计算机名称和一种状态：在线、连接中、离线、已暂停或需重新连接（计算机在别处断开；“连接此计算机”可重新配对）。在此你可以： 暂停连接 / 恢复连接：停止或重启后台服务。暂停的计算机对智能体离线（computer_offline），重启后保持暂停状态。 访问权限：是否允许智能体在计算机连接时使用它。参见下文“计算机上的访问权限”。 插电时保持此计算机唤醒（macOS 和 Linux）：计算机在接通电源时不进入睡眠，以便智能体访问。默认关闭。Windows 上该行显示此功能尚不可用。 共享：打开“计算机”连接器的“账户”选项卡，点击计算机所在行的“共享”。 显示日志：打开智能体日志文件。 断开连接：从 Kortix 和所有项目中移除该计算机，并停止后台服务。
计算机上的访问权限 无论项目允许什么，计算机本身决定是否让智能体使用它。你在“你的计算机 → 访问权限”或菜单栏图标中设置： 每次询问（桌面应用连接计算机的默认值）：智能体发起首次调用时，计算机上会显示提示：允许 24 小时、允许 1 小时（默认按钮）或拒绝。批准覆盖文件、Shell 以及屏幕键盘，适用于所有能访问该计算机的智能体，直到时间结束。批准期间，对话框显示“允许至 14”和“立即撤销”。拒绝后，调用会在 10 分钟内立即失败，不再弹出新提示。更改模式会结束当前的批准或拒绝状态。 始终允许：无提示。这是仅通过 CLI 连接计算机的默认值，因为该计算机无法显示提示。在此设置存在之前连接的计算机，保持此行为直到你更改。 关闭：拒绝所有调用。 只有你（在计算机上）可以扩大访问权限。当 Kortix 页面请求“始终允许”或新的批准时，桌面应用会先显示原生对话框，仅当你点击“允许”时才应用更改。每次新的配对都从默认值重新开始，断开连接会移除设置。 设置存储在计算机本地（~/.agent-tunnel/access.json）。账户行和状态工具会报告此设置，以便智能体告知你正在等待批准。
谁可以使用计算机 计算机遵循与其他连接器账户相同的规则： 私有计算机（默认值，仅自己）仅在所有者所属的所有项目中的私有会话中运行。其他成员无法看到或使用它。 点击计算机所在行的“共享”会打开与 Gmail 账户相同的对话框：选择人员、组或项目内所有人。在你选择“保存”之前没有任何更改，除非你移除自己，否则你保留访问权限。 共享需要管理项目连接的权限。计算机在该项目中仍是一个账户；该行随后显示谁可以使用它。 分享给所有人的计算机在项目内对所有人运行，包括无人值守运行：触发器、计划任务以及未链接用户的 Slack 消息。无人值守运行只能访问共享计算机。 你自己的行跟随你移动，因此不会单独从某个项目中移除。断开连接会从 Kortix 和所有项目中移除计算机。若想保持连接但不用，可将计算机上的访问权限设为关闭。 为高风险调用增加人工把关，可在“计算机”连接器的“工具”选项卡中设置连接器策略（例如，请求 shell.exec）。之后请求会出现在项目的批准列表中。
计算机允许什么 你在批准计算机时选择功能。若之后允许某项功能，需重新连接计算机并选中该功能。 本地智能体配置是所有调用的硬性上限，无论 Kortix 允许什么。它位于计算机的 ~/.agent-tunnel/config.json： 字段 默认值 效果 enabledCapabilities 你批准的功能 机器接受的功能范围。 allowedPaths 你的主目录 文件调用可访问的路径。 blockedPaths /etc/shadow, /etc/ssh, /proc 等 调用不可触碰的路径。 allowedCommands 空（任意命令） 设置后，shell.exec 仅运行这些可执行文件。 blockedCommands 空 shell.exec 永不运行的可执行文件。 无限制的 Shell 可以运行用户可用的任何可执行文件。请根据工作需求收窄 allowedPaths 和 allowedCommands。 计算机操作需要单独安装本地 cua-driver。智能体不会下载、安装或更新该可执行文件。
智能体如何使用计算机 智能体像调用其他连接器一样调用“计算机”连接器，并用 --account 选择计算机： kortix connectors accounts computer kortix connectors call computer status '{}' --account "Studio Mac" kortix connectors call computer fs.read '{"path":"/Users/me/notes.md"}' --account "Studio Mac" kortix connectors call computer shell.exec '{"command":"git","args":["status"]}' --account me 工具包括 status、fs.read、fs.write、fs.list、fs.stat、fs.delete、shell.exec 以及 desktop.cua.* 计算机操作工具。 status 返回所选计算机的名称、在线状态、平台、功能和访问设置。 调用失败时会返回明确原因，而非猜测： 原因 含义 解决方案 account_required 有多台计算机可访问，但未指定名称或未固定。 传入 --account，或在账户选项卡中固定默认值。 computer_offline 计算机已配对但当前未连接。 唤醒计算机，或在桌面应用中恢复访问。 computer_unpaired 账户指向已断开的机器。 重新连接计算机。 computer_capability_not_approved 计算机批准时未选择此功能。 重新连接计算机并选择该功能。 computer_access_pending 所有者尚未在计算机上响应提示。 在计算机上响应提示，然后让智能体继续。 computer_access_denied 所有者选择拒绝。 从菜单栏图标或“你的计算机”中允许访问。 computer_access_off 所有者将访问权限设为关闭。 更改计算机上的访问权限。 account_not_found --account 或旧版计算机参数未命名任何可访问的计算机。 使用 kortix connectors accounts computer 中的标签。
断开计算机 在桌面应用中：在工作区菜单或菜单栏图标中打开“你的计算机”，选择“断开连接”。Kortix 会移除该机器及所有指向它的账户。断开连接的账户不再显示在任何账户列表中。 通过 CLI：在计算机上运行 npx --yes @kortix/agent-tunnel@latest logout。它使用自己的令牌从 Kortix 移除机器，然后删除本地凭证。离线时，仅删除本地凭证。 从其他地方，例如笔记本电脑丢失：在“自定义 → 连接器 → 计算机 → 账户”中，打开计算机所在行并选择“断开连接”。该计算机上仍在运行的桌面应用会显示“需重新连接”。 共享计算机，从单个项目：管理员在账户选项卡中打开其所在行并选择“断开连接”。计算机保持连接，但在该项目中恢复为仅所有者可用。
计算机使用机器专属令牌进行身份验证，令牌存储在计算机上。API 仅存储其哈希值。远程连接需要 HTTPS/WSS。你在仪表盘中配置计算机，而非在 kortix.yaml 中。 安全传输二进制文件 对于电子表格、PDF、图像和其他二进制文件，直接从源文件传输字节。切勿让智能体从工具输出中复制 base64 载荷。这可能会在保持文件大小不变的同时改变字节。 在持有源文件的机器或沙箱上，配置 TUNNEL_API_URL、TUNNEL_TOKEN 和 TUNNEL_ID，然后运行： agent-tunnel-cli fs_upload '{"source":"/tmp/report.xlsx","path":"/Users/me/Desktop/report.xlsx"}' 命令支持最大 3 MiB 的文件，并需要文件系统功能。它从源文件计算 SHA-256，并检查目标返回的哈希值。若响应缺少 sha256 字段，请更新连接的智能体。 对于大文件，在目标位置生成工件。交付前验证源文件格式。哈希匹配证明字节未更改；文件大小和扩展名不能证明 Excel 能打开工作簿。
