本地执行机

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

本地执行机

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

适合这些场景：

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

本地执行机

当前支持与安装前提

  • 当前常规发布产物支持 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 -fsSL '安装链接' | bash
  • 安装脚本支持重复执行；重复安装会尽量复用已有端口和服务配置，并按需做增量更新

本地执行机安装

操作系统与兼容性

当前安装脚本会根据系统和 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 心跳上报的当前实际版本

这意味着：

  • 如果你机器上的本机 claude 或 codex 版本和平台内置版本不一致，系统不会强制把本机命令升级或降级到内置版本
  • 自动升级只会升级 Knodo Agent 自身，以及它当前正在管理的内置 Claude Code / Codex CLI 运行包

核心绑定关系

  • 一台电脑安装后，会注册成一个本地 Agent
  • 一个本地 Agent 可以绑定多个工作空间
  • 一个工作空间同一时间最多绑定一个本地执行机
  • 每个工作空间都可以指定自己的本地目录
  • 设备拥有者可以在“个人设置 / 我的主机”里看到、认领、重命名或删除自己的设备
  • 本地 Agent 支持“个人可见”和“组织内可见”；个人可见仅设备拥有者可绑定，组织内可见可被同组织工作空间绑定
  • 工作空间管理员或组织管理员才能管理工作空间的绑定、同步和执行模式

两条安装路径

路径 A：从个人设置安装

适合先把自己的常用电脑接入账号，再按需绑定多个工作空间。

操作路径：

  1. 打开「我的主机」
  2. 进入「本地 Agent」相关页面
  3. 点击「生成安装命令」
  4. 在目标机器终端执行命令

安装完成后：

  • 设备自动归属到当前账号
  • 不会自动绑定工作空间
  • 你可以稍后在任意工作空间中手动绑定

路径 B：在工作空间内安装并自动绑定

适合第一次把某个项目切到本地执行时一步到位完成接入。

操作路径：

  1. 打开目标工作空间
  2. 进入「空间设置」→「本地执行机」
  3. 填写目标机器上的本地项目目录
  4. 选择是否「绑定时同步云端数据到本地」
  5. 点击「生成工作空间安装命令」
  6. 在目标机器终端执行命令

安装完成后：

  • 设备自动归属到当前账号
  • 当前工作空间会自动绑定到该设备和目录
  • 工作空间会自动切换到本地模式

本地执行机绑定空间

绑定、切换与同步

手动绑定已有设备

如果设备已经通过个人设置接入，可以直接在工作空间里绑定：

  1. 打开「空间设置」→「本地执行机」
  2. 选择一个可绑定的本地 Agent
  3. 填写该工作空间在这台机器上的本地目录
  4. 选择是否在绑定时同步云端数据到本地
  5. 点击「绑定到当前工作空间」

说明：

  • “绑定时同步云端数据到本地”默认关闭
  • 开启后会强制把云端文件同步到本地，可能清理本地目录
  • 关闭后只建立绑定关系，不主动覆盖你的本地目录
  • 个人可见主机仅限设备拥有者绑定；组织内可见主机需要先绑定到当前工作空间所属组织

本地执行机绑定空间

执行模式

工作空间有两种执行模式：

模式说明适用场景
云端模式继续使用远程沙箱执行本机离线、临时切回云端、只想保留绑定关系
本地模式AI 直接操作你绑定的本地目录本地开发、联调、调试、调用本机环境

行为规则：

  • 绑定成功后，工作空间会自动切到本地模式
  • 已绑定后可以在本地模式和云端模式之间来回切换，无需解绑
  • 切回本地模式时要求本地 Agent 在线
  • 切到云端模式时会保留绑定关系和本地目录配置

数据同步

系统支持两个方向的同步：

  • 云端同步到本地
  • 本地同步到云端

同步过程中会展示：

  • 当前任务状态
  • 已处理文件数和总文件数
  • 已处理字节数和总字节数
  • 删除文件数

同步任务执行中可以取消。取消后任务会在当前正在处理的文件结束后停止，可能留下部分已同步文件；如果需要恢复一致状态，可以重新执行“云端同步到本地”或“本地同步到云端”。

平台也会根据文件清单比较当前差异，用于判断是否还有未同步数据。

解绑与换绑规则

解绑或切换到新的设备 / 新目录前，平台会先检查当前绑定是否安全：

  • 如果有同步任务正在执行，不能解绑或换绑
  • 如果检测到未同步数据，不能直接解绑或换绑
  • 如果原设备离线，平台无法确认同步状态时，不能直接换绑
  • 如果你确认不需要保留未同步数据，可以执行强制解绑

解绑完成后：

  • 工作空间会自动切回云端模式
  • 绑定关系会被移除
  • 本地目录本身不会被系统删除

自动 Git 版本管理

现有代码不会在绑定本地执行机时自动改写工作空间当前的「自动 Git 版本管理」开关，而是保留工作空间已有设置。

  • 如果当前工作空间本来已开启自动 Git，绑定后会继续保持开启
  • 如果你手动关闭，后续不会自动执行 git init / git commit
  • 这个开关是工作空间级别的，可以在「空间设置」中随时调整

自动升级

本地执行机会持续通过心跳上报自身版本、平台信息和当前使用中的 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 查看日志；如果暂时无法恢复，先把工作空间切回云端模式即可继续工作。

相关文档