本地执行机

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

本地执行机

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

适合这些场景：

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

本地执行机

浏览器内网直连

执行机管理员可在「本地执行机 → 基本信息」中开启允许内网直连，默认关闭，平台管理员不能代为修改。开启后，同一网络中的浏览器可以直接连接这台执行机访问文件，速度更快。

  • 内网地址可以不填写，系统会自动使用执行机检测到的地址；也可以逐行填写 IP、带端口的地址或 HTTPS 域名。默认端口通常是 9910 或 9911。
  • 开启后，执行机会自动允许局域网内的其他设备访问；关闭后只允许本机访问。平台不会修改你电脑的防火墙或 Docker 端口设置，如有需要请自行放行。
  • 文件变化订阅可设为打开、关闭或默认（当前为关闭）。打开后，文件区能更快显示执行机上的文件变化；关闭不影响正常使用，文件变化仍会按原方式刷新。

要真正使用内网访问，还需要平台管理员为组织开启内网直连、空间也允许内网访问，详见内网访问。

进入工作空间后，页面会自动检测并选择可用的内网地址，无需手动测试；网络暂时不通时会自动重试，仍不可用时继续使用普通网络。

文件传输

平台和本地执行机都升级到新版本后，读写文件会自动使用更高效的传输方式，大文件上传和下载更快。旧版本执行机继续使用原有方式，无需任何配置。

当前支持与安装前提

  • 当前常规发布产物支持 macOS Intel、macOS Apple Silicon、Linux x64 和 Windows 10 22H2 / Windows 11（x64）
  • Windows 的安装方式与其他系统不同，见下面的「在 Windows 上安装」；以下的 curl、tar、Git 说明适用于 macOS 和 Linux
  • 安装命令有效期为 24 小时，过期后需要重新生成
  • 安装脚本依赖 curl 和 tar
  • 安装脚本会检查 Git
  • Linux 下如果未安装 Git，会尝试通过系统包管理器自动安装
  • macOS 下如果未安装 Git，且没有 Homebrew，需要先手动补装
  • 本地 Agent 默认监听 127.0.0.1:9910
  • 是否允许局域网访问由执行机管理员在平台中控制，修改后无需重启执行机；可用 knodo-agent lan status 查看当前是否已允许局域网访问。如果开启后仍只能本机访问，请检查执行机版本是否已升级
  • 如需自定义端口，可在安装前使用 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支持Windows 10 22H2 或 Windows 11，无需管理员
Windowsarm64暂不支持暂不提供 Windows on ARM 安装包

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 优先使用 system 级 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. macOS / Linux 点击生成安装命令，在目标电脑终端执行；Windows 下载或打开已有安装器，生成安装码并粘贴到安装器中完成安装。

打开「接入新主机」不会立即生成安装命令或安装码。按所选系统完成对应步骤后，主机会自动接入当前账号。已有主机的迁移和重装也使用同一套步骤，入口位于主机详情的「迁移命令」页。

接入新主机安装命令

流程顶部提供「macOS / Linux｜Windows」系统选择卡片，默认选中你当前浏览器所在的系统。Windows 显示「下载安装器 → 生成安装码」，macOS / Linux 显示「生成安装命令」。个人设置、工作空间设置等命令行入口仍支持系统切换，并展示对应的终端安装指引。

如果 Windows 标注「未开放」，请联系平台管理员开启 Windows 安装后重试。此时不会提供 Windows 安装码或安装命令，也不会自动回退到 Bash。curl ... | bash 仅适用于 macOS / Linux，不能直接复制到 Windows PowerShell 或命令提示符中运行。

在 Windows 上安装

系统要求：Windows 10 22H2 或 Windows 11（64 位）。不需要管理员权限，也不需要预先安装 Git、Node 或其他依赖。

安装步骤：

  1. 在「本地主机」点击「接入新主机」，先选择操作系统。选择「Windows」后会显示安装器步骤，不再展示需要手动执行的 PowerShell 长命令。
  2. 首次使用时点击「下载 Windows 安装器」，下载完成后在目标电脑上双击 knodo-setup.exe，无需打开终端。如果已经下载过同一环境的安装器，直接打开已有安装器即可，无需重复下载。
  3. 如果出现「Windows 已保护你的电脑」，先核实安装器来自当前 Knodo 平台，再按下方「首次运行时的 SmartScreen 提示」点击「更多信息 → 仍要运行」。没有出现提示时直接继续。
  4. 点击「生成安装码」，再点「复制安装码」，将安装码粘贴到安装器中。「生成安装码」默认可点击，不要求先在本次页面下载安装器；安装器会询问是否创建桌面快捷方式，直接回车默认创建，输入 n 则不创建。
  5. 安装器会检查系统、下载并校验安装包、安装到当前用户目录、注册并启动。期间如果遇到防火墙或安全软件的联网拦截，请按下方「注意防火墙与联网权限」处理，不要直接关闭防火墙。
  6. 成功后按回车关闭安装窗口，Knodo 在右下角系统托盘运行；回到「本地主机」列表确认这台电脑显示在线。如果安装完成但仍显示离线，请先检查联网拦截，再从托盘菜单重新启动。

如果选择的是 macOS / Linux，则点击「生成安装命令」，将命令复制到目标主机的终端执行。

关于安装器和安装码：

  • 安装器是从你当前使用的平台下载的，它只会连接这个平台，安装码改不了安装来源。
  • 同一环境的安装器可用于再次安装、重装或迁移，每次使用重新生成有效安装码即可；切换到其他平台环境时，请下载对应环境的安装器。
  • 下载安装器本身不会生成安装码，也不会提前消耗有效期；点击「生成安装码」后才开始计算 24 小时有效期。过期后点击「重新生成」，无需重复下载安装器。
  • 个人设置、工作空间设置等入口仍可能提供命令行安装方式；已有主机迁移使用本页「迁移或重装已有主机」的分步流程。如果在工作空间里生成安装码，码里已带上要绑定的目录，不需要再填。

首次运行时的 SmartScreen 提示

双击安装器后，Windows 可能先显示下面的「Windows 已保护你的电脑」提示。这是 SmartScreen 的应用启动提示，不是防火墙的联网提示；此时安装器还没有打开。

Windows SmartScreen 启动提示：点击左上方「更多信息」查看应用详情

  1. 先确认文件是从你当前使用的 Knodo 平台「下载 Windows 安装器」入口下载的。来源不明、应用名称与下载文件不一致或无法确认时，选择「不运行」，联系管理员核实。
  2. 点击图中左上方的「更多信息」。最初只有「不运行」按钮时，需要先点击「更多信息」展开详情。
  3. 核对应用名称与刚下载的 Knodo 安装器一致后，点击「仍要运行」，再继续粘贴安装码。不要把这个操作用于其他来源不明的程序。
  4. 如果展开后仍没有「仍要运行」，或提示由组织策略阻止，请停止并联系公司 IT / 平台管理员，不要关闭 SmartScreen 或绕过组织策略。

注意防火墙与联网权限

安装完成不等于已连接成功。 Windows 防火墙、第三方安全软件或公司网络策略可能阻止下载、注册、后台连接或后续升级。安装后务必回到平台确认主机显示「在线」。

  • 联网拦截提示：如果安全软件询问是否允许安装器或 Agent 访问网络，先核对程序来源和路径；确认是从当前平台下载的安装器，或 %LOCALAPPDATA%\Knodo\agent 下的 Knodo 程序后，仅允许所需程序访问当前平台。不要放行来源不明的同名程序。
  • 需要允许的连接：安装器和后台 Agent 需要主动访问当前 Knodo 平台的域名及实际端口，以下载安装包、注册、建立 WebSocket 长连接和检查更新。公司网络限制出站访问时，请让管理员按当前平台地址配置必要的出站规则；自部署环境不要只按默认端口放行。
  • 不要误开放入站端口：基础安装、上线和任务执行使用 Agent 主动发起的出站连接，不需要为了接入平台而开放本机入站端口。如果弹窗提示「Windows Defender 防火墙已阻止此应用的部分功能」，不要把所有网络类型都勾上；这类入站权限并非基础接入的必选项。
  • 确需局域网访问时：只有在你明确使用需要其他设备访问本机的功能时，才按需通过「Windows 安全中心 → 防火墙和网络保护 → 允许应用通过防火墙」放行对应程序，并限制到所需的受信任网络；不要默认允许「公用网络」。修改规则可能需要管理员批准。
  • 已经拦截或一直离线时：查看 Windows 安全中心、第三方安全软件的拦截记录；公司统一管理的电脑请让 IT 核查出站规则、平台地址和 WebSocket 连接限制。规则调整后重新打开安装器，或从托盘菜单「重新启动」，再确认平台在线状态。联网恢复后仍失败时，再查看安装提示或运行 knodo-agent doctor 排查其他原因。

不要为了安装关闭 Windows 防火墙、实时防护或整个安全软件，也不要放开所有端口。 本机安装不要求管理员权限，但企业安全策略或防火墙规则的调整可能需要管理员处理。

安装过程与文件位置

  • Git Bash：AI 在 Windows 上通过 Git Bash 执行命令。电脑上已有 2.40 或更新版本的 Git for Windows 时直接复用；没有或版本太旧时，脚本会自动准备一份 Git Bash 运行环境，不会修改你的系统或用户 PATH。Git for Windows 采用 GPLv2 许可，来源说明会随运行环境一起保存。

  • 下载进度：会依次显示正在下载的 Git Bash 运行环境、Knodo Agent 安装包、jq 和 rg 及其版本；已有可复用 Git Bash 时会跳过该组件下载。下载期间每约 5 秒显示当前组件已接收的大小和等待时间，完成后显示正在校验完整性。首次安装可能需要几分钟，请保持窗口打开；持续显示大小不变时可能仍在等待网络响应，并不表示下载已经完成。

  • 校验：安装包会用 SHA-256 校验完整性，校验不通过会直接停止，不会写入安装目录。目前发布的 Windows 安装包没有做代码签名，所以不校验发布者签名；安装窗口不再额外显示证书兼容或未签名发布的技术提示，实际错误和安全校验失败仍会显示。

  • 失败时：终端会显示原因、处理办法和错误码，并清理这次写入的文件。

  • 窗口行为：安装器窗口用于输入安装码和显示进度，完成后按回车关闭即可。后台 Agent 启动、崩溃重启和版本切换不应另开空白终端窗口。

  • 开机自启：安装后会随你登录 Windows 自动运行；你没有登录时 Agent 不会运行。

  • 命令开头那段“放行证书”的内容：Windows 安装命令在 irm 之前，会先带一小段让 PowerShell 本次不检查服务器证书的代码。它是为自签证书部署准备的兼容处理：平台使用自签证书时，PowerShell 默认会因为不信任证书而下载失败，加上这一段就能直接安装。它只对这条命令启动的这个 PowerShell 进程生效，不会修改系统的证书设置。这段内容由平台生成，请原样复制执行，不要自己删改；改动后命令可能无法执行，也可能让安装来源不再受控。

  • rg、jq 等辅助工具：Windows 安装流程会像准备 Git Bash 一样，从当前平台下载 rg 和 jq 并用 SHA-256 校验，保存到 Agent 私有目录，不修改系统 PATH，也不需要你手动安装。后续平台发布新版本时，Agent 后台只会按需刷新或修复这两份工具。

  • 未签名与安全提示：Windows 版目前是未签名发布。首次启动按上方「首次运行时的 SmartScreen 提示」核实并操作；联网被拦截时按「注意防火墙与联网权限」处理。杀毒软件告警的处理见本页常见问题。

安装位置在当前用户的 %LOCALAPPDATA%\Knodo\agent。

桌面启动与系统托盘

  • 双击桌面上的「Knodo Agent」快捷方式即可启动，并弹出当前状态、版本和监听地址。安装时没有创建桌面快捷方式的，也可以从 Windows 开始菜单搜索同名应用启动。
  • 启动后不会常驻命令行窗口，而是在右下角通知区域显示 Knodo 图标。找不到图标时，点击任务栏的「显示隐藏的图标」箭头；可以把 Knodo 图标拖到常显区域。
  • 重复双击快捷方式不会创建多个 Agent 或多个托盘图标，而是显示当前状态。双击托盘图标同样可以查看状态，鼠标悬停可查看简要连接状态和版本。

右键托盘图标可使用以下菜单：

菜单用途
查看状态查看当前版本、在线 / 连接中 / 未运行状态及安装目录
重新启动停止并重新启动本机 Agent，托盘图标保留；正在执行的本机任务可能中断
检查更新向当前平台检查并发起升级，复用现有下载校验、空闲等待、健康检查和回滚机制；如果已有升级或需要等待，会显示实际反馈，不表示已经升级完成
退出确认后停止后台 Agent 并移除托盘图标；不会删除安装文件、凭据或项目目录

退出后可再次双击快捷方式启动。退出不等于卸载，也不会取消登录自启；下次登录 Windows 时仍会自动启动。升级过程中可通过「查看状态」确认当前版本，版本切换后托盘应用会跟随已安装版本重新接管。

迁移或重装已有主机

更换设备、重装系统，或需要在当前电脑修复安装时，都使用主机详情里的「迁移命令」，操作步骤与「接入新主机」相同。需要升级到新版本时，优先使用托盘菜单中的「检查更新」。

操作步骤：

  1. 在「本地主机」列表打开当前主机详情，进入「迁移命令」页，先选择目标电脑的操作系统。
  2. 选择 macOS / Linux：点击「生成安装命令」，复制到目标电脑的终端执行。
  3. 选择 Windows：「生成安装码」默认可点击。同一环境已下载过安装器时，可直接生成并复制安装码，双击已有的 knodo-setup.exe 并粘贴安装码；首次使用时先下载安装器，按提示完成安装，不需要打开 PowerShell。
  4. 安装完成后回到「本地主机」确认电脑已上线。如果安装码或命令已过期，点击「重新生成」即可，无需再次下载安装器。

同一台 Windows 电脑覆盖安装时，无需先卸载。安装器会停止本机旧 Agent 和托盘进程，备份同版本目录后安装；成功后清理备份，失败时尝试恢复原版本。

请提前备份项目文件。更换电脑或重装系统时，请先恢复项目文件到原来的目录。 安装不会自动复制另一台电脑上的文件；工作空间设置会继续保留，更换电脑完成后，原电脑会断开连接。

查看状态与诊断

  • 运行 knodo-agent doctor 会逐项检查与平台的连接、凭据、开机自启、Git Bash 和常用工具（git、node、python、rg、jq），并对每个问题给出错误码和处理办法。
  • 运行 knodo-agent status 查看当前是否在线。

卸载 Windows 本地 Agent

推荐使用 Windows 的标准卸载入口，无需手动删除文件：

  1. 打开 Windows「设置 → 应用 → 已安装的应用」（Windows 10 为「应用和功能」）。
  2. 搜索 Knodo Agent，选择「卸载」，并确认提示。卸载程序会自动停止托盘和后台 Agent，不需要先结束任务管理器里的进程。
  3. 卸载成功后会显示「卸载完成」。桌面 / 开始菜单中的 Knodo 快捷方式和右下角托盘图标都会移除，其余清理由程序在后台自动完成，无需手动删除文件。

如果系统设置里的卸载入口不可用，可以打开 PowerShell，执行下面的命令启动同一个图形化卸载确认流程：

$root = Join-Path $env:LOCALAPPDATA 'Knodo\agent' & (Join-Path $root 'knodo-agent-ui.exe') --uninstall --install-root $root

旧版没有托盘启动器时，可使用实际安装目录中的 CLI 卸载，不需要把命令加入 PATH：

$root = Join-Path $env:LOCALAPPDATA 'Knodo\agent' $version = (Get-Content -LiteralPath (Join-Path $root 'current.json') -Raw | ConvertFrom-Json).version & (Join-Path $root "versions\$version\knodo-agent.exe") uninstall --install-root $root

卸载会删除：

  • 当前用户的登录自启项和 Windows「已安装的应用」登记。
  • Knodo 创建的桌面 / 开始菜单快捷方式、后台进程和托盘应用。
  • %LOCALAPPDATA%\Knodo\agent 下的安装文件、保存的连接凭据、日志、缓存，以及由 Agent 自动准备的 Git Bash / rg / jq 等工具。

不会删除绑定的项目目录、项目文件或你自行安装的 Git / Node 等软件，也不会删除平台上的会话和工作空间。 卸载后，这台电脑可能继续在「本地主机」列表显示离线；确认不再使用时，可以在列表中删除。卸载后再次使用，需要从平台重新生成安装命令或安装码并安装。

Windows 上的目录与权限

绑定本地目录时：

  • 路径写法：盘符路径如 D:\code\my-project，或网络共享路径如 \\server\share\project。目录名可以包含中文和空格。不能使用相对路径，也不能包含 ..。
  • 不能绑定的位置：磁盘根目录（如 C:\）、Windows、Program Files、回收站和系统卷信息等系统目录。
  • 路径大小写不敏感：D:\Code\App 和 d:\code\app 是同一个目录，重复绑定会被拒绝。
  • AI 只能读写你绑定的目录之内。通过快捷方式、符号链接或联接点（junction）指向目录之外的路径，会被拒绝。
  • 网络盘或可移动磁盘不可用时（例如 U 盘已拔出、网络断开），文件操作会提示目录当前不可用，不会假装成功。映射的网络盘符（如 Z:）对 Agent 可能不可见，建议改用 \\server\share 路径。

AI 运行命令前是否需要你确认，与其他系统一样由会话的权限模式决定，Windows 没有额外的规则。

Windows 上暂不支持的能力

  • 主机间文件互传，以及部分面向平台管理的排障与资源监控能力
  • 部分插件默认只面向 macOS 和 Linux：插件需要明确声明支持 Windows 才会下发到 Windows 主机，不支持的插件不会出现在 Windows 主机的会话里

安装完成后：

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

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

组织限制普通成员安装

组织管理员可以限制普通成员接入新的本地主机。限制开启后：

  • 普通成员的「接入新主机」「在新设备安装」入口会置灰，并提示“组织已限制普通成员安装本地执行机，如需安装请联系组织管理员”
  • 通过注册码认领主机、把已有主机切换到该组织，同样仅组织管理员可以操作
  • 组织管理员不受影响，已经安装好的主机、已有绑定和历史会话也不受影响，可以继续使用
  • 迁移已有主机到新设备不属于“新增安装”，不受限制

管理员在「组织设置 → 运行配置 → 沙箱」中通过「允许普通成员安装本地执行机」开关控制，默认开启。

更换设备或重装系统

同一台电脑修复或覆盖安装、更换设备、重装系统，都使用主机详情里的「迁移命令」；不要先卸载。需要升级到新版本时，优先使用托盘菜单中的「检查更新」。

在「本地主机」列表打开已有主机详情，进入「迁移命令」页，先选择系统。macOS / Linux 生成命令后在终端执行；Windows 可复用同一环境已下载的安装器，直接生成安装码并粘贴到安装器中，首次使用再下载安装器。具体步骤见本页「迁移或重装已有主机」。

本地执行机迁移命令

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

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

绑定空间

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

操作入口：

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

详细说明见 执行环境。

自动升级

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

升级规则：

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

Windows 主机的升级独立于 macOS / Linux：发布清单包含新的 Windows 平台版本时，Windows 主机才会升级，未列入本次构建的平台不会被带动。升级会把新版本放在单独的目录里，旧版本保留；如果新版本启动后一段时间内没有恢复在线，Agent 会自动回退到上一个版本，列表里显示的仍是旧版本，不需要你手动处理。Agent 自带的 Git Bash 也会随平台清单独立更新，更新失败时继续使用当前版本。

资源状态

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

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

当前限制

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

安全边界

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

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

推荐做法：

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

本地主机离线排查

平台中的在线状态来自本地 Agent 主动连接平台后的心跳。电脑关机、睡眠、断网、Agent 进程退出或连接被拦截时，这台主机会显示离线。排查时先在本机执行，再根据结果区分 Agent 服务、网络和平台连接问题。

先确认影响范围

  1. 在这台电脑上用浏览器打开当前 Knodo 平台。如果平台本身打不开，先排查本机网络、DNS、VPN、代理或公司出站策略；平台恢复可达后再确认 Agent 状态。
  2. 在「本地主机」列表检查是否只有这台主机离线。如果同一账号或同一网络内的多台主机都离线，优先排查本地网络、代理或平台可用性，不要先重装 Agent。
  3. 电脑刚开机、从睡眠中唤醒或网络刚切换时，可以等待约 1 分钟再刷新；长时间仍离线时继续下面的诊断。

在本机诊断 Agent

在 macOS / Linux 终端或 Windows PowerShell 中执行：

knodo-agent status knodo-agent doctor knodo-agent logs
  • status 用于确认 Agent 当前是在线、连接中还是未运行。
  • doctor 会检查平台连接、凭据、开机自启和常用工具，并给出错误码与处理建议。
  • logs 用于查看最近的连接失败、进程退出、凭据失效和升级异常。

如果状态显示未运行或连接中，先重启本机 Agent：

knodo-agent restart

重启可能中断这台电脑上正在执行的本地任务；重启后再次执行 knodo-agent status，并回到平台确认在线状态。

排查网络与安全软件

本地 Agent 只需要主动出站访问当前 Knodo 平台域名，通常使用 HTTPS / WSS 和 443 端口；不需要为了上线开放本机入站端口。

  • 使用公司网络、VPN 或代理时，确认代理配置仍符合代理网络环境的要求；修改 ~/.knodo/agent/config/agent.env 后需要重启 Agent。
  • Windows 上查看安全中心或第三方安全软件是否有 Knodo Agent 的联网拦截记录，只放行 Knodo Agent 访问当前平台所需的出站连接，不要关闭防火墙或整体安全防护。
  • DNS、证书、代理或 WebSocket 被拦截时，doctor 和 logs 通常会显示连接失败或证书校验错误。公司统一管理的电脑请把错误码和日志时间提供给 IT / 平台管理员核对出站策略。

排查系统更新后的服务异常

如果离线发生在系统更新、重启或长时间睡眠后，即使电脑网络正常，也要检查系统服务是否成功把 Agent 拉起。

Linux systemd 模式可先查看服务状态和最近日志：

systemctl status knodo-local-agent --no-pager -l journalctl -u knodo-local-agent --since "1 hour ago" --no-pager -o short-precise

当日志显示服务反复重启，或状态中出现 start request repeated too quickly、StartLimitBurst 等启动次数上限提示时，先记录日志，再清除失败状态并重启：

sudo systemctl reset-failed knodo-local-agent sudo systemctl restart knodo-local-agent

如果这台电脑不允许使用 sudo，或重启后仍失败，先保留 status 和 journalctl 输出，再使用主机详情中的「迁移命令」覆盖修复安装，或联系平台管理员处理。不要手工删除安装目录或绑定项目。

macOS 可通过 knodo-agent status、knodo-agent logs 和 knodo-agent doctor 检查 launchd 是否拉起 Agent；仍失败时使用「迁移命令」覆盖修复安装。Windows 可从托盘菜单「查看状态」和「重新启动」入手，并在事件查看器或安全软件拦截记录中确认是否有启动或联网被阻止的记录。

排查系统更新问题时，除了 Agent 自身日志，也可以查看同一时间窗的系统日志和安全软件记录，确认是否发生服务批量重启、进程被结束或联网被拦截。需要人工处理时，提供离线开始时间、doctor 错误码和同一时间窗的 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 doctor 和 knodo-agent logs 定位 Agent、网络或系统服务问题；如果暂时无法恢复，先把工作空间切回云端模式即可继续工作。

Q：文件列表提示“无法访问工作目录”怎么办？

A：这表示本地 Agent 已连接，但操作系统拒绝了目录读取。macOS 的“桌面”“文稿”和“下载”目录通常受隐私权限保护。打开「系统设置 → 隐私与安全性 → 完全磁盘访问权限」，为 ~/.knodo/agent/bin/knodo-agentd 开启权限，然后执行 knodo-agent restart 并在文件列表中重试。如果不希望授予完全磁盘访问权限，可以把项目移动到 ~/Projects 等普通开发目录，再更新工作空间的本地目录绑定。

Q：Windows 安装时杀毒软件拦截了怎么办？

A：先区分拦截类型：SmartScreen 的蓝色启动提示，按上方「首次运行时的 SmartScreen 提示」核实来源后处理；防火墙联网拦截，按「注意防火墙与联网权限」检查必要的连接。如果杀毒软件或「受控文件夹访问」阻止了文件写入，请查看拦截记录，确认来源后联系 IT / 管理员评估是否为具体程序设置例外，不要直接关闭防护或信任整个磁盘。安装包会校验 SHA-256，但完整性校验不能代替对下载来源和安全告警的核实。处理后重新打开安装器，安装码过期时重新生成；knodo-agent doctor 可帮助检查安装文件是否缺失。

Q：Windows 提示安装完成，但主机一直离线，是否要关闭防火墙？

A：不要关闭防火墙。先检查安装器和后台 Agent 是否被阻止访问当前平台的域名、实际端口或 WebSocket 长连接；按上方「注意防火墙与联网权限」仅处理必要的程序和连接。基础接入不需要开放入站端口，也不需要勾选所有网络类型。公司策略限制时联系 IT，调整后从托盘重新启动并确认是否上线；仍离线时继续通过状态和诊断排查，不要把所有离线问题都当作防火墙拦截。

Q：公司网络需要代理，Windows 上安装失败怎么办？

A：PowerShell 会使用系统代理设置。安装命令开头已经放行证书校验，Agent 默认也信任自签证书，所以公司代理或平台使用自签证书时一般不需要额外处理。如果你的安全策略要求 Windows 上的 Agent 严格校验证书，可以把环境变量 KNODO_AGENT_INSECURE_TLS 设为 0，同时需要先把相应的根证书导入 Windows 的受信任根证书存储。连接失败时终端会显示「无法连接到平台服务」或「代理证书校验失败」及对应的错误码。

Q：Windows 上可以使用 WSL2 吗？

A：可以变通使用：在 WSL2 的 Linux 里按 Linux 方式安装本地执行机，把绑定目录放在 WSL 的文件系统里。这与 Windows 原生执行机是两台独立的主机。

Q：电脑重启或注销后，Windows 上的执行机还在线吗？

A：重新登录后会自动恢复在线；没有登录时 Agent 不运行，工作空间会显示该执行机离线。

相关文档

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