本地执行机

了解如何安装、绑定和管理工作空间的本地执行机

本地执行机

本地执行机会把你自己的电脑注册成工作空间可用的执行环境。工作空间切到本地模式后，AI 不再只在云端沙箱里运行，而是会直接在你指定的本地项目目录中读写文件、执行代码任务，并继续使用 Claude Code CLI 或 Codex CLI 链路完成会话。

适合这些场景：

  • 需要直接操作你电脑上的真实项目目录
  • 需要联调本机进程、内网服务、数据库或浏览器环境
  • 需要继续使用本地 IDE、调试器、终端和已有仓库分支

本地执行机

文件传输兼容性

Rust Backend 与 Rust 本地执行机均升级并重新连接后，支持的文件分块读写会自动使用二进制传输，减少 Base64 带来的网络开销。旧版本或未协商该能力的连接仍使用原有传输方式，无需手工迁移配置；不会在传输中途切换协议或自动重放已经发送的写入。

系统配置 ws.agentRawFileRequestLimitBytes 控制单个文件分块读写请求的大小上限，默认 1 GiB，可在 1 KiB～8 GiB 范围内调整。配置更新只对新请求生效，不重建连接、不影响在途请求。超过上限直接拒绝；文件聚合不预留进程级内存，原有帧级流控保持不变。此限制不是整个进程 RSS 上限。

大文件读取、ZIP 下载继续使用既有 HTTP 二进制流，大文件分块写入复用新的二进制 chunk 通道。路径权限、断点续传入口和超时设置不变。

当前支持与安装前提

  • 当前常规发布产物支持 macOS Intel、macOS Apple Silicon 和 Linux x64
  • Windows 桌面端暂不在支持范围内
  • 安装命令有效期为 24 小时，过期后需要重新生成
  • 安装脚本依赖 curl 和 tar
  • 安装脚本会检查 Git
  • Linux 下如果未安装 Git，会尝试通过系统包管理器自动安装
  • macOS 下如果未安装 Git，且没有 Homebrew，需要先手动补装
  • 本地 Agent 默认监听 127.0.0.1:9910
  • 如需自定义端口，可在安装前使用 KNODO_AGENT_PORT=9910 curl -kfsSL '安装链接' | bash；安装命令默认兼容 HTTPS 自签名证书
  • 安装脚本支持重复执行；重复安装会尽量复用已有端口和服务配置，并按需做增量更新

本地执行机安装

代理网络环境

如果本机或所在内网不能直连 Knodo 平台，需要通过 HTTP/HTTPS 代理出站访问，可以在执行安装命令前先设置代理环境变量：

export HTTP_PROXY="http://<proxy-host>:<proxy-port>" export HTTPS_PROXY="$HTTP_PROXY" export http_proxy="$HTTP_PROXY" export https_proxy="$HTTPS_PROXY" export NO_PROXY="localhost,127.0.0.1,::1,.internal,<内网域名>,<内网IP段>" export no_proxy="$NO_PROXY"

然后再执行页面生成的本地 Agent 安装命令。安装脚本会读取当前 shell 中的代理变量，并写入本地 Agent 配置文件：

~/.knodo/agent/config/agent.env

这些代理配置会影响：

  • 本地 Agent 连接 Knodo Backend 的 WebSocket 和 HTTP 请求
  • 本地 Agent 下载升级包、CLI 运行包、插件或 Skill 资源
  • 本地 Agent 启动 Claude Code / Codex runtime 时的出站网络

工作空间或组织也可以通过环境变量配置 runtime 代理：

变量说明
HTTP_PROXY / http_proxyHTTP 代理地址
HTTPS_PROXY / https_proxyHTTPS 代理地址；未配置时通常复用 HTTP 代理
NO_PROXY / no_proxy不走代理的域名、IP、CIDR 或本机地址

代理配置优先级为：

  1. 工作空间环境变量
  2. 组织环境变量
  3. 本地 Agent agent.env 中持久化的代理
  4. 平台系统配置兜底

JAVIS_HTTP_PROXY 和 JAVIS_NO_PROXY 是平台内部环境变量，不作为组织或工作空间环境变量配置入口。需要给本地执行机 runtime 配置代理时，请使用上表中的标准代理变量。

修改组织或工作空间代理变量后，新会话会使用新的代理配置；已经运行中的 Claude Code / Codex 会话不会被强制中断。如果修改的是本机 agent.env，需要重启本地 Agent：

knodo-agent restart

本地执行机代理模式不等同于远程专属主机的网络隔离。远程专属主机通常通过 Agent Service 内置正向代理和 Sandbox 网络隔离控制容器出站；本地执行机运行在用户电脑上，主要通过标准 HTTP_PROXY / HTTPS_PROXY / NO_PROXY 环境变量控制本机进程出站。

连接与大文件传输

本地 Agent 始终主动连接 Knodo 平台，不需要在用户电脑上开放可被平台访问的入站端口。注册、心跳、任务命令、取消、升级和终态继续使用 WebSocket JSON Text，默认协议不会因版本升级自动改变。

当平台和本地 Agent 都运行支持版本的 Rust 实现时，系统默认通过 WSS Binary Data V1 传输字节流；任务参数、心跳、取消、结束状态和升级流程仍走 WebSocket JSON Text 控制通道。能力协商、连接 Profile、灰度门禁或 circuit breaker 未通过时，新流使用 JSON Text；任一端为 Node 版本时也只使用 JSON Text。

如果新 Binary 协议未就绪，新任务直接使用 JSON Text。已经开始执行的同一任务不会在协议之间静默切换，以避免重复执行。单台本地 Agent 网络缓慢或停止响应时，平台只会让该 Agent 的任务变慢或失败，不会阻塞其他 Agent 的注册、心跳和任务处理。

操作系统与兼容性

当前安装脚本会根据系统和 CPU 架构下载对应产物：

操作系统架构发布状态说明
macOSApple Silicon（arm64）支持推荐使用 macOS 13 或更新版本
macOSIntel（x64）支持推荐使用 macOS 13 或更新版本
Linuxx64支持需要 glibc 2.28 或更新版本
Linuxarm64暂未发布安装脚本可识别该架构，但当前不作为常规产物
Windowsx64 / arm64暂不支持暂不提供 Windows 桌面端安装包

Linux 兼容性重点看 glibc 版本。本地执行机是基于 Node SEA 打包的单文件二进制，当前 Linux x64 产物的基线要求为 GLIBC_2.28。如果系统 glibc 低于 2.28，可能出现二进制无法启动、缺少符号或运行时异常。

建议优先使用这些系统：

  • Ubuntu 20.04 / 22.04 / 24.04 LTS
  • Debian 11 / 12
  • RHEL 9 或更新版本
  • Rocky Linux 9 或更新版本
  • AlmaLinux 9 或更新版本
  • CentOS Stream 9 / 10
  • macOS 13 或更新版本

不建议用于生产使用的环境：

  • CentOS 7、RHEL 7 及其他 glibc 低于 2.28 的旧版 Linux
  • Alpine Linux 等 musl libc 发行版
  • 32 位操作系统
  • 未纳入常规发布产物的 Linux arm64 主机

安装后会得到什么

  • 安装目录：~/.knodo/agent
  • 数据目录：~/.knodo/data
  • 配置文件：~/.knodo/agent/config/agent.env
  • 日志目录：~/.knodo/agent/logs
  • 常用管理命令：knodo-agent start、stop、restart、status、logs、version、upgrade、uninstall

系统会自动注册本机服务：

  • Linux 优先使用 user-level systemd
  • macOS 使用 launchd
  • 如果系统服务不可用，管理命令会回退到后台进程方式启动

CLI 运行策略

本地执行机并不总是固定使用平台内置的 CLI 运行包。

  • 如果当前机器的 PATH 中已经存在可执行的 claude 命令，本地执行机会优先使用本机 Claude Code
  • 如果没有可用的本机 claude，安装脚本会下载并维护一个随 Agent 分发的内置 Claude Code 运行包
  • 如果当前机器的 PATH 中已经存在可执行的 codex 命令，本地执行机会优先使用本机 Codex CLI
  • 如果没有可用的本机 codex，安装脚本会下载并维护一个随 Agent 分发的内置 Codex CLI 运行包
  • knodo-agent version 和 knodo-agent --version 会展示 Knodo Agent、Claude Code 和 Codex CLI 的当前版本
  • “我的主机 / 本地 Agent”列表里展示的 Claude Code 和 Codex 版本，也是 Agent 心跳上报的当前实际版本
  • Codex 会复用工作空间已经同步到本地 Agent 的插件资产：.mcp.json 会转换为本次 app-server 启动参数，skills/ 会作为额外 Skill Root 注入
  • 本地 Codex 不会因为插件复用而替换 CODEX_HOME，也不会默认写入用户全局 CODEX_HOME/config.toml

这意味着：

  • 如果你机器上的本机 claude 或 codex 版本和平台内置版本不一致，系统不会强制把本机命令升级或降级到内置版本
  • 自动升级只会升级 Knodo Agent 自身，以及它当前正在管理的内置 Claude Code / Codex CLI 运行包
  • 插件绑定、解绑或远程同步变化默认只影响新的 Codex 对话；已有 Codex 对话继续使用创建时的插件快照
  • 如果需要让已有 Codex 对话立即使用最新插件，需要显式重建或重启对应的 Codex app-server 会话

核心绑定关系

  • 一台电脑安装后，会注册成一个本地 Agent
  • 一个本地 Agent 可以绑定多个工作空间、执行环境或存量执行空间
  • 空间设置中的「空间模式」用于配置默认环境的云端或本地执行方式
  • 空间设置中的「执行环境」用于添加新会话可显式选择的本地执行机和目录
  • 存量执行空间仍可以维护自己的执行位置，但执行空间已停止新增
  • 设备拥有者可以在“个人设置 / 我的主机”里看到、认领、重命名或删除自己的设备
  • 本地 Agent 支持“成员可见”和“组织内可见”；成员可见仅设备拥有者和授权成员可绑定，组织内可见可被同组织工作空间绑定
  • 工作空间管理员或组织管理员才能管理工作空间的绑定、同步和执行模式

工作空间还可以建立多条“执行环境”绑定，每条绑定指向一台本地执行机和一个目录。成员创建新对话时可以选择其中一个执行环境；选择结果会在会话创建时固化，之后即使绑定被禁用、改目录或解除，历史会话仍使用原来的 Host 和目录快照。删除 Host 后历史记录仍保留执行环境说明，但不能再继续执行。

设备拥有者可以从“我的主机”查看本机被哪些空间使用并解除关系。这里仅展示固定掩码空间标识、目录摘要和受影响会话数，不展示空间名称、slug、组织信息或跳转链接。

安装入口

本地执行机统一从最外层「本地主机」菜单接入。这里用于管理当前账号可见的本地主机、生成安装命令、查看在线状态和资源状态。

本地主机入口

操作路径：

  1. 在左侧主导航打开「本地主机」。
  2. 点击「接入新主机」生成安装命令。
  3. 在目标机器终端执行安装命令。

点击「接入新主机」后，平台会生成一条一次性安装命令。复制命令到目标机器终端执行，安装完成后主机会自动注册到当前账号。

接入新主机安装命令

安装完成后：

  • 设备自动归属到当前账号
  • 不会自动绑定工作空间
  • 你可以稍后在工作空间设置的「空间模式」中设为默认环境的本地执行方式，或在「执行环境」中添加为新会话可显式选择的运行目录

如果同一个项目需要多个独立本地目录，建议在「执行环境」中添加多个绑定。执行空间是历史工作副本模型，已停止新增但存量继续可用。更多概念说明见 执行环境 和 执行空间。

重新安装

如果已有本地执行机需要更换设备、重装系统或迁移到新机器，不要使用「接入新主机」重新安装。接入新主机会注册一台新的本地执行机，原主机与空间模式、执行环境、存量执行空间之间的绑定关系不会自动转移。

正确做法是在「本地主机」列表中点击进入已有主机详情，打开「迁移命令」页，生成迁移命令后在新设备终端执行。迁移完成后，当前主机身份和所有工作空间绑定会迁移到新设备，原设备自动失联。

本地执行机迁移命令

适合使用迁移命令的场景：

  • 原电脑损坏、退役或需要更换到新电脑。
  • 重装系统后希望继续使用原来的本地执行机身份。
  • 希望保留已有空间模式、执行环境或存量执行空间绑定关系。

绑定空间

本地执行机接入后，需要在具体工作空间中配置空间模式或执行环境，就可以让空间直连到本地主机所在机器。

操作入口：

  1. 打开目标工作空间。
  2. 进入「空间设置」→「空间模式」，设置该空间未显式选择执行环境时的默认云端或本地运行方式。
  3. 如需多个可选目录，进入「空间设置」→「执行环境」，添加本地执行机和工作目录。

详细说明见 执行环境。

自动升级

本地执行机会持续通过心跳上报自身版本、平台信息和当前使用中的 Claude Code / Codex CLI 版本。服务端会把这些信息与当前安装产物清单做比较，并按需触发升级。

升级规则：

  • Local Agent 版本不一致时，会触发本地 Agent 自升级
  • 版本号不可用时，会回退到 SHA256 校验判断是否需要更新
  • 只有当前正在使用内置 Claude Code 或 Codex CLI 运行包时，才会检查并升级对应内置运行包
  • 如果当前优先使用的是本机 claude 或 codex 命令，不会强制同步到平台内置版本
  • 升级后会由 systemd / launchd 自动拉起新版本
  • 你也可以手动执行 knodo-agent upgrade

资源状态

“我的主机”和管理员的本地执行机列表会展示本机资源摘要，包括负载、可用内存、数据盘剩余空间、容器数和最近心跳。资源状态只用于帮助判断本机是否繁忙，不会替代在线 / 离线状态。

资源指标跟随本地执行机心跳上报。历史趋势由系统配置控制，默认保留 7 天；关闭历史存储后，页面仍展示最新资源状态。

当前限制

  • Windows 桌面端暂不支持
  • 建议把本地目录指向具体项目目录，不要直接指向整个用户主目录
  • 空间模式同一时间只能有一个默认本地执行机；需要多个可选本地目录时，请添加多个执行环境
  • 已绑定本地执行机的工作空间，当前不支持把本地数据“链接共享知识”或“设置为共享”

安全边界

使用本地执行机前，需要明确下面几点：

  • 绑定设备时，你只能选择成员可见且你是设备拥有者或授权成员的本地 Agent，或当前组织内可见的本地 Agent
  • 一旦绑定成功，该工作空间成员可能通过 AI Agent 间接操作你绑定的本地目录
  • 工作空间管理员或组织管理员可以管理绑定关系、执行模式和同步
  • 删除设备或解绑工作空间，都不会删除你的本地目录文件

推荐做法：

  • 为不同项目使用独立目录
  • 不要把整个用户主目录当作工作空间目录
  • 对生产配置、密钥文件和本机缓存目录保持额外隔离

常见问题

Q：一台电脑可以服务多个工作空间吗？

A：可以。同一个本地 Agent 可以绑定多个工作空间，但每个工作空间都要配置自己的本地目录。

Q：绑定后是不是只能一直用本地模式？

A：不是。绑定后仍可随时切回云端模式，绑定关系会继续保留。

Q：解绑或删除设备会不会删掉我本地的项目文件？

A：不会。平台只会移除绑定关系，不会删除你的本地目录。若解除的是显式执行环境，不会改写空间模式；若在空间模式中解绑默认本地执行机，空间会回到云端模式。

Q：为什么我看到的 Claude Code 或 Codex 版本和平台内置版本不一样？

A：如果你的机器上已经安装了本机 claude 或 codex 命令，本地执行机会优先使用它，所以页面和 knodo-agent --version 展示的是本机实际在用的版本，而不是平台内置包的目标版本。

Q：如果本机 Claude Code 或 Codex 和平台内置版本不一致，会被自动统一升级吗？

A：不会。平台只会升级它自己管理的内置 CLI 运行包；如果当前使用的是你本机自己安装的 claude 或 codex，平台不会强制把它升级或降级到内置版本。

Q：本地设备离线了怎么办？

A：可以先用 knodo-agent status 检查状态，用 knodo-agent logs 查看日志；如果暂时无法恢复，先把工作空间切回云端模式即可继续工作。

相关文档

本地 Agent 升级采用下载摘要校验、journal 恢复、warming readiness 和原子 promotion。升级中断会从 journal 继续，readiness 失败则保留旧进程并回滚；传输能力不可用时仍使用 JSON 兼容路径。