本地执行机

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

本地执行机

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

适合这些场景：

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

当前支持与安装前提

  • 当前支持 macOS 和 Linux，Windows 桌面端暂不在支持范围内
  • 安装命令有效期为 24 小时，过期后需要重新生成
  • 注册码有效期为 24 小时，过期后需要重新启动 Agent 获取
  • 安装脚本依赖 curl 和 tar
  • 安装脚本会检查 Git
  • Linux 下如果未安装 Git，会尝试通过系统包管理器自动安装
  • macOS 下如果未安装 Git，且没有 Homebrew，需要先手动补装
  • 本地 Agent 默认监听 127.0.0.1:3001
  • 如需自定义端口，可在安装前使用 KNODO_AGENT_PORT=3101 curl -fsSL '安装链接' | bash
  • 安装脚本支持重复执行；重复安装会尽量复用已有端口和服务配置，并按需做增量更新

安装后会得到什么

  • 安装目录：~/.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
  • 如果系统服务不可用，管理命令会回退到后台进程方式启动

Claude Code 运行策略

本地执行机并不总是固定使用内置 Claude Code。

  • 如果当前机器的 PATH 中已经存在可执行的 claude 命令，本地执行机会优先使用本机 Claude Code
  • 如果没有可用的本机 claude，安装脚本会下载并维护一个随 Agent 分发的内置 Claude Code 运行包
  • knodo-agent version 和 knodo-agent --version 展示的是当前实际使用中的 Claude Code 版本
  • “我的主机 / 本地 Agent”列表里展示的 Claude Code 版本，也是 Agent 心跳上报的当前实际版本

这意味着：

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

核心绑定关系

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

三条安装路径

路径 A：从个人设置一键安装

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

操作路径：

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

安装完成后：

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

路径 B：先启动，再用注册码认领

适合已有二进制、预装服务、离线预装或运维分发安装包的场景。

操作路径：

  1. 在本地启动 Agent
  2. 终端会显示注册码
  3. 打开「个人设置」→「本地 Agent」
  4. 输入注册码并完成认领

认领完成后：

  • 设备归属到当前账号
  • 不会自动绑定工作空间
  • 如果注册码失效，需要重新启动 Agent 获取新码

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

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

操作路径：

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

安装完成后：

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

绑定、切换与同步

手动绑定已有设备

如果设备已经通过路径 A 或路径 B 接入，可以直接在工作空间里绑定：

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

说明：

  • “绑定时同步云端数据到本地”默认开启
  • 关闭后只建立绑定关系，不主动覆盖你的本地目录

执行模式

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

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

行为规则：

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

数据同步

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

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

同步过程中会展示：

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

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

解绑与换绑规则

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

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

解绑完成后：

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

自动 Git 版本管理

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

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

自动升级

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

升级规则：

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

当前限制

  • Windows 桌面端暂不支持
  • 建议把本地目录指向具体项目目录，不要直接指向整个用户主目录
  • 一个工作空间最多只能绑定一个本地执行机
  • 已绑定本地执行机的工作空间，当前不支持把本地数据“链接共享知识”或“设置为共享”

安全边界

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

  • 绑定设备时，你只能选择属于自己的本地 Agent
  • 一旦绑定成功，该工作空间成员可能通过 AI Agent 间接操作你绑定的本地目录
  • 工作空间管理员或组织管理员可以管理绑定关系、执行模式和同步
  • 删除设备或解绑工作空间，都不会删除你的本地目录文件

推荐做法：

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

常见问题

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

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

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

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

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

A：不会。平台只会移除绑定关系，并把相关工作空间切回云端模式，不会删除你的本地目录。

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

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

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

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

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

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

相关文档

本地执行机 | Knodo 文档