跳到主要内容

Windows(原生)指南

Kopi Agent 可在 Windows 10 和 Windows 11 上原生运行 —— 无需 WSL,无需 Cygwin,无需 Docker。本页是深入介绍:哪些功能原生可用、哪些仅限 WSL、安装脚本实际做了什么,以及你可能需要调整的 Windows 专属配置项。

如果你只是想安装,首页或安装页面上的一行命令就够了。等遇到意料之外的情况时再回来看这里。

想改用 WSL?

如果你偏好真正的 POSIX 环境(例如面板内置终端、fork 语义、Linux 风格的文件监视器等),请参阅 Windows(WSL2)指南。两者可以干净共存:原生数据存放在 %LOCALAPPDATA%\kopi,WSL 数据存放在 ~/.kopi。

快速安装​

打开 PowerShell(或 Windows Terminal)并运行:

iex (irm https://raw.githubusercontent.com/Kopi Ai Agent Pte Ltd/kopi-ai-agent/main/scripts/install.ps1)

无需管理员权限。安装程序会安装到 %LOCALAPPDATA%\kopi\,并把 kopi 添加到你的 用户 PATH —— 完成后请打开一个新的终端。

安装程序选项(需要使用 scriptblock 形式来传参):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Kopi Ai Agent Pte Ltd/kopi-ai-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main
参数默认值用途
-Branchmain克隆指定分支(适用于测试 PR)
-Commit未设置固定安装到指定 commit SHA(覆盖 -Branch)
-Tag未设置固定安装到指定 git tag(例如 v0.14.0)
-NoVenvoff跳过 venv 创建(高级用法 —— 自行管理 Python)
-SkipSetupoff跳过安装后的 kopi setup 向导
-HermesHome%LOCALAPPDATA%\kopi覆盖数据目录
-InstallDir%LOCALAPPDATA%\kopi\kopi-ai-agent覆盖代码位置

安装程序会自动重试不稳定的 git fetch,并去除下载的 install.ps1 载荷中的 BOM,这样 HTTP 传输过程中带上的 UTF-8 BOM 就不会再破坏 [scriptblock]::Create((irm ...)) 形式。

桌面安装程序(替代方案)​

还提供了一个轻量的 GUI 安装程序 —— 如果你更愿意双击 .exe 而不是打开 PowerShell,它会很有用。下载 Kopi Agent Desktop,运行安装程序,首次启动时 GUI 会在底层调用 install.ps1 来配置 Python(通过 uv)、Node、PortableGit,以及下文所述的其余依赖引导流程。首次运行之后,桌面应用与通过 PowerShell 安装的 kopi CLI 共用同一个 %LOCALAPPDATA%\kopi\kopi-ai-agent 安装目录和 %LOCALAPPDATA%\kopi 数据目录 —— 可以在 GUI 和 CLI 之间自由切换。

当你想要熟悉的 Windows 安装体验,或者要把 Kopi Agent 交给非开发者使用时,请使用桌面安装程序;当你已经身处终端时,请使用 PowerShell 一行命令。

依赖引导(dep_ensure)​

首次启动时(以及检测到缺失工具时按需执行),Kopi Agent 会运行一个小型 Python 引导程序 —— kopi_cli/dep_ensure.py —— 检查并惰性安装所需的非 Python 依赖。在 Windows 上,相关的依赖有:

依赖Kopi Agent 需要它的原因
PortableGit为终端工具提供 bash.exe,为会话内克隆提供 git。在安装时配置,而非由 dep_ensure 负责。
Node.js 22浏览器工具(agent-browser)、TUI 的 web bridge 以及 WhatsApp bridge 都需要它。
ffmpeg用于 TTS / 语音消息的音频格式转换。
ripgrep快速文件搜索 —— 不可用时回退到 grep。
npm 包agent-browser、Playwright Chromium 以及各工具集的 Node 依赖会在首次使用浏览器工具时一次性安装。

每个依赖都有 shutil.which(...) 风格的检查;如果某个二进制缺失且当前为交互式运行,dep_ensure 会询问是否安装(实际安装逻辑交由 scripts\install.ps1 -ensure <dep> 执行)。非交互式运行(gateway、cron、无头桌面启动)会跳过提示,改为给出清晰的 this feature needs <dep> 错误。

安装程序实际做了什么​

从头到尾,按顺序:

  1. 引导安装 uv —— Astral 的快速 Python 管理器。安装到 %USERPROFILE%\.local\bin。
  2. 安装 Python 3.11,通过 uv。无需已有 Python。
  3. 安装 Node.js 22(优先用 winget,否则使用便携版 Node tarball 解压到 %LOCALAPPDATA%\kopi\node)。用于浏览器工具和 WhatsApp bridge。
  4. 安装便携版 Git —— 如果 git 已在 PATH 上,安装程序会直接使用它;否则会下载一个精简、自包含的 PortableGit(约 45 MB,来自官方 git-for-windows release)到 %LOCALAPPDATA%\kopi\git。无需管理员权限,不写 Windows installer 注册表,不会干扰机器上的其他任何东西。
  5. 克隆仓库到 %LOCALAPPDATA%\kopi\kopi-ai-agent,并在其中创建 virtualenv。
  6. 分层 uv pip install —— 先尝试 .[all],如果某个 git+https 依赖在受速率限制的 GitHub 上失败,则回退到逐级精简的集合([messaging,dashboard,ext] → [messaging] → .)。避免了"单次失败就导致仅基础安装"的失败模式。
  7. 根据 .env 自动安装消息 SDK —— 如果存在 TELEGRAM_BOT_TOKEN / DISCORD_BOT_TOKEN / SLACK_BOT_TOKEN / SLACK_APP_TOKEN / WHATSAPP_ENABLED,则运行 python -m ensurepip --upgrade 和针对性的 pip install 调用,确保每个平台的 SDK 真正可导入。
  8. 将 KOPI_GIT_BASH_PATH 设置为解析出的 bash.exe,让 Kopi Agent 在全新 shell 中都能确定地找到它。
  9. 将 %LOCALAPPDATA%\kopi\kopi-ai-agent\venv\Scripts 添加到用户 PATH 并设置 KOPI_HOME=%LOCALAPPDATA%\kopi —— 打开新终端后即可使用 kopi 命令(并将其指向你的数据目录)。
  10. 运行 kopi setup —— 常规的首次运行向导(模型、provider、工具集)。可用 -SkipSetup 跳过。
在 Windows 上省去逐一寻找 provider 的麻烦

在 Windows 上,逐个工具配置 API key(Firecrawl、FAL、Browser Use、OpenAI TTS)是让 agent 真正好用过程中最繁琐的部分。一个 KOPI Proxy 订阅通过一次 OAuth 登录即可覆盖模型以及上述全部工具。安装程序完成后,运行 kopi setup --portal 即可完成全部接线配置。

功能矩阵​

除仪表板的嵌入式终端窗格外,其他所有功能均可在 Windows 上原生运行。

功能原生 WindowsWSL2
CLI(kopi chat、kopi setup、kopi gateway 等)✓✓
交互式 TUI(kopi --tui)✓✓
消息网关(Telegram、Discord、Slack、WhatsApp 等 15+ 平台)✓✓
Cron 调度器✓✓
浏览器工具(通过 Node 运行 Chromium)✓✓
MCP 服务器(stdio 和 HTTP)✓✓
本地 Ollama / LM Studio / llama-server✓✓(通过 WSL 网络)
Web 仪表板(会话、任务、指标、配置)✓✓
仪表板 /chat 嵌入式终端窗格✗(需要 POSIX PTY)✓
登录时自动启动✓(schtasks)✓(systemd)

仪表板的 /chat 标签页通过 POSIX PTY(ptyprocess)嵌入了一个真实终端。原生 Windows 没有等价的原语;Python 的 pywinpty / Windows ConPTY 可以胜任,但那是一套独立的实现 —— 将其视为后续工作。仪表板的其余部分可原生运行 —— 只有那一个标签页会显示“请为此使用 WSL2”的横幅。

Kopi Agent 如何在 Windows 上运行 shell 命令​

Kopi Agent 的终端工具通过 Git Bash 运行命令,与 Claude Code 采用的策略相同。这样可以在不重写每个工具的情况下绕过 POSIX 与 Windows 之间的差异。

bash.exe 的解析顺序:

  1. 如果设置了 KOPI_GIT_BASH_PATH 环境变量,则使用它。
  2. %LOCALAPPDATA%\kopi\git\usr\bin\bash.exe(安装程序管理的 PortableGit)。
  3. %LOCALAPPDATA%\kopi\git\bin\bash.exe(较旧的 Git for Windows 目录布局)。
  4. 系统安装的 Git for Windows(%ProgramFiles%\Git\bin\bash.exe 等)。
  5. 作为最后手段,使用 PATH 上的 MSYS2、Cygwin 或任何 bash.exe。

安装程序会显式设置 KOPI_GIT_BASH_PATH,这样新的 PowerShell 会话无需重新探测。如果你想让 Kopi Agent 使用特定的 bash,可以覆盖它 —— 例如系统 Git Bash,或通过符号链接指向的 WSL 中的 bash。

陷阱: MinGit 的目录结构与完整的 Git for Windows 安装程序不同 —— bash 位于 usr\bin\bash.exe 下,而非 bin\bash.exe。Kopi Agent 会检查这两个位置。如果你手动解压 MinGit 的 zip 包,请确保选择 非 busybox 版本(MinGit-*-64-bit.zip,而非 MinGit-*-busybox*.zip)—— busybox 构建版提供的是 ash 而不是 bash,而且缺少大多数 coreutils。

Windows 上的 UTF-8 控制台​

Python 在 Windows 上的默认 stdio 使用控制台的活动代码页(通常是 cp1252 或 cp437)。Kopi Agent 的横幅、斜杠命令列表、工具输出流、Rich 面板和 skill 描述都包含 Unicode。若不加处理,其中任何一项都会因 UnicodeEncodeError: 'charmap' codec can't encode character… 而崩溃。

修复位于 kopi_cli/stdio.py::configure_windows_stdio(),它会在每个入口点(cli.py::main、kopi_cli/main.py::main、gateway/run.py::main)的早期被调用。它会:

  1. 通过 kernel32.SetConsoleCP / SetConsoleOutputCP 将控制台代码页切换为 CP_UTF8(65001)。
  2. 使用 errors='replace' 将 sys.stdout / sys.stderr / sys.stdin 重新配置为 UTF-8。
  3. 设置 PYTHONIOENCODING=utf-8 和 PYTHONUTF8=1(通过 setdefault,以便用户的显式设置优先生效),使子 Python 进程继承 UTF-8。
  4. 如果既未设置 EDITOR 也未设置 VISUAL,则设置 EDITOR=notepad(参见下文的编辑器一节)。

该操作是幂等的,在非 Windows 平台上不执行任何操作。

选择退出: 在环境中设置 KOPI_DISABLE_WINDOWS_UTF8=1 会回退到传统的 cp1252 stdio 路径。这在二分定位编码 bug 时很有用;在正常使用中通常不是正确的设置。

编辑器(Ctrl-X Ctrl-E、/edit)​

在 #21561 之前,在 Windows 上按 Ctrl-X Ctrl-E 或输入 /edit 会静默地毫无反应。prompt_toolkit 有一个硬编码的 POSIX 绝对路径回退列表(/usr/bin/nano、/usr/bin/pico、/usr/bin/vi 等),在 Windows 上永远无法解析 —— 即使安装了完整的 Git for Windows 也是如此。

Kopi Agent 的 Windows stdio shim 现在将 EDITOR=notepad 设为默认值。记事本随每个 Windows 安装附带,并且可以作为阻塞式编辑器工作 —— subprocess.call(["notepad", file]) 会阻塞直到窗口关闭。

用户覆盖仍然优先生效(在 setdefault 之前会先检查这些值):

编辑器PowerShell 命令
VS Code$env:EDITOR = "code --wait"
Notepad++$env:EDITOR = "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -nosession"
Neovim$env:EDITOR = "nvim"
Helix$env:EDITOR = "hx"

VS Code 上的 --wait 标志至关重要 —— 没有它,编辑器会立即返回,Kopi Agent 会得到一个空白缓冲区。

在你的 PowerShell profile 中永久设置它:

# In $PROFILE
$env:EDITOR = "code --wait"

或者在系统设置中将其设为用户环境变量,让每个新 shell 都能读取到。

在 CLI 中用 Ctrl+Enter 换行​

Windows Terminal 会把 Ctrl+Enter 作为专用按键序列传递。Kopi Agent 将其绑定为“插入换行符”,这样你可以在 CLI 中编写多行提示词,而无需退回到先 Esc 再 Enter 的方式。在 Windows Terminal、VS Code 集成终端以及任何遵循 VT 转义序列的现代 Windows 控制台宿主中都可以使用。

在传统的 cmd.exe 控制台上,Ctrl+Enter 会退化为普通的 Enter —— 这时请改用 Esc Enter,或者升级到 Windows Terminal(它免费,且在 Windows 11 上默认安装)。

在 Windows 登录时运行网关​

kopi gateway install 在 Windows 上使用**计划任务(Scheduled Tasks)**并以启动文件夹作为回退方案——无需管理员权限。

安装​

kopi gateway install

底层的实际执行过程:

  1. schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway — 注册一个在你登录时运行的任务,使用标准(非提权)权限。不会弹出 UAC 提示。
  2. 如果 schtasks 被组策略阻止,则回退为向 %APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup 写入一个 start /min cmd.exe /d /c <wrapper> 快捷方式。效果相同,只是略显粗糙。
  3. 通过 pythonw.exe 以分离方式派生网关——而不是 python.exe。pythonw.exe 没有关联的控制台,因此它可以免疫来自同级进程的 CTRL_C_EVENT 广播(这是一个真实存在过的问题:以前在同一进程组中按 Ctrl+C 时会误杀网关)。

派生时使用的标志:DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB。

管理​

kopi gateway status      # Merged view: schtasks + Startup folder + running PID
kopi gateway start # Starts the scheduled task now
kopi gateway stop # Graceful SIGTERM equivalent (TerminateProcess via psutil)
kopi gateway restart
kopi gateway uninstall # Removes schtasks entry, Startup shortcut, pid file

kopi gateway status 是幂等的——哪怕连续调用一千次,也绝不会意外杀掉网关。(在 PR #21561 之前它会悄悄地杀掉网关,原因是 os.kill(pid, 0) 在 C 层面与 CTRL_C_EVENT 冲突——如果你对这段历史感兴趣,可以参见下文的"进程管理内部机制"。)

为什么不用 Windows Service?​

Service 需要管理员权限来安装,并且会把网关的生命周期绑定到机器启动,而非用户登录。典型的 Kopi Agent 用户期望是:登录 → 网关可用,登出 → 网关消失。计划任务无需提权就能精确做到这一点。如果你确实需要一个 service,可以手动使用 nssm 或 sc create——但你大概率并不需要。

数据布局​

路径内容
%LOCALAPPDATA%\kopi\kopi-ai-agent\Git checkout + venv。venv\Scripts\kopi-agent.exe 是添加到用户 PATH 的命令。可以安全地 Remove-Item -Recurse 后重新安装。
%LOCALAPPDATA%\kopi\git\PortableGit(仅当安装器配置了它时才有)。
%LOCALAPPDATA%\kopi\node\Portable Node.js(仅当安装器配置了它时才有)。
%LOCALAPPDATA%\kopi\bin\Kopi Agent 托管的 uv.exe(它用于更新的 Python 管理器)。
%LOCALAPPDATA%\kopi\(根目录)你的配置、认证信息、skills、会话、日志(config.yaml、.env、skills\、sessions\、logs\ 等)。重装后仍会保留。

在原生 Windows 上,安装器会设置 KOPI_HOME=%LOCALAPPDATA%\kopi,因此你的数据与一次性安装内容位于同一个 %LOCALAPPDATA%\kopi 根目录下:安装/运行时内容位于 kopi-ai-agent\、git\、node\ 和 bin\ 子目录,而你的数据文件直接位于 %LOCALAPPDATA%\kopi 中。重装只会替换 kopi-ai-agent\ checkout,因此你的数据会保留——但由于两者共用同一个根目录,如果你想保留数据,就不要 Remove-Item -Recurse %LOCALAPPDATA%\kopi;而应删除 kopi-ai-agent\ 子目录。你的数据目录结构与 Linux 上的 ~/.kopi 完全一致,因此可以在多台机器之间镜像同步。

覆盖 KOPI_HOME: 设置该环境变量以指向不同的数据目录(例如 %USERPROFILE%\.kopi,以匹配 Linux/WSL 的布局)。其工作方式与 Linux 上完全相同。

浏览器工具​

浏览器工具使用 agent-browser(一个 Node 辅助程序)来驱动 Chromium。在 Windows 上:

  • 安装器通过 npm 将 agent-browser 加入 PATH。
  • shutil.which("agent-browser", path=...) 会自动识别 .cmd shim——CreateProcessW 无法执行没有扩展名的 shebang 脚本,因此 Kopi Agent 始终解析到 .CMD 包装器。不要手动调用 shebang 脚本;始终通过 .cmd 来使用。
  • Playwright Chromium 会在首次运行时自动安装(npx playwright install chromium)。如果安装失败,kopi doctor 会将其暴露出来并给出修复提示。

在 Windows 上运行 Kopi Agent——实用说明​

安装后的 PATH​

安装器通过 [Environment]::SetEnvironmentVariable 将 %LOCALAPPDATA%\kopi\kopi-ai-agent\venv\Scripts 添加到你的用户 PATH。已打开的终端不会感知到这一变化——安装后请打开一个新的 PowerShell 窗口(或 Windows Terminal 标签页)。请关闭后重新打开,除非你清楚自己在做什么,否则不要手动 $env:PATH += …。

验证:

Get-Command kopi        # should print C:\Users\<you>\AppData\Local\hermes\kopi-ai-agent\venv\Scripts\kopi-agent.exe
kopi --version

环境变量​

Kopi Agent 同时支持 $env:X(进程作用域)和用户环境变量(永久生效,在"系统属性 → 环境变量"中设置)。在 %LOCALAPPDATA%\kopi\.env(你的 KOPI_HOME)中设置 API key 是常规做法——与 Linux 上一致:

OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=...

除非你确实希望所有 Windows 进程都能看到这些密钥,否则不要把机密信息放在用户环境变量里(那通常并不是你想要的效果)。

Windows 专属环境变量​

以下变量只影响原生 Windows 安装:

变量作用
KOPI_GIT_BASH_PATH覆盖 bash.exe 的发现逻辑。可指向任意 bash——完整的 Git for Windows、通过符号链接指向的 WSL bash、MSYS2、Cygwin。安装器会自动设置此项。
KOPI_DISABLE_WINDOWS_UTF8设置为 1 可禁用 UTF-8 stdio shim,回退到区域设置代码页。在二分定位编码问题时很有用。
EDITOR / VISUAL用于 /edit 和 Ctrl-X Ctrl-E 的编辑器。如果两者都未设置,Kopi Agent 默认使用 notepad。

卸载​

在 PowerShell 中:

kopi uninstall

这是干净的卸载路径——移除 schtasks 条目、启动文件夹快捷方式、kopi-agent.cmd shim,删除 %LOCALAPPDATA%\kopi\kopi-ai-agent\,并清理用户 PATH。它会保留 %LOCALAPPDATA%\kopi\ 的其余内容(你的配置、认证信息、skills、会话、日志),以防你需要重新安装。

如果要彻底清除所有内容:

kopi uninstall
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"
# Also remove a legacy CLI/WSL data dir if you ever used one:
Remove-Item -Recurse -Force "$env:USERPROFILE\.kopi"

kopi uninstall CLI 子命令还能处理 schtasks 条目以不同任务名注册的情况(旧版安装)——它按安装路径而非硬编码的任务名进行搜索。

进程管理内部机制​

以下为背景资料——除非你正在排查"它自己把自己杀掉了"这类诡异问题,否则可跳过。

在 Linux 和 macOS 上,POSIX 惯用法 os.kill(pid, 0) 是一次空操作的权限检查:"这个 PID 是否存活、我能否向它发送信号?"在 Windows 上,Python 的 os.kill 将 sig=0 映射为 CTRL_C_EVENT——二者在整数值 0 上发生冲突——并通过 GenerateConsoleCtrlEvent(0, pid) 传递,后者会将 Ctrl+C 广播给包含目标 PID 的整个控制台进程组。这就是 bpo-14484,自 2012 年起一直悬而未决。它不会被修复,因为改动会破坏依赖当前行为的脚本。

后果是:在 Windows 上,任何通过 os.kill(pid, 0) 表示"检查该 PID 是否存活"的代码路径,实际上都在悄悄杀掉目标进程。Kopi Agent 已将所有此类调用点(分布在 11 个文件中共 14 处)迁移到 gateway.status._pid_exists(),后者使用 psutil.pid_exists()(而它在 Windows 上又使用 OpenProcess + GetExitCodeProcess——不发送信号)。如果你在编写插件或补丁,请直接使用 psutil.pid_exists() 或 gateway.status._pid_exists()——绝不要使用 os.kill(pid, 0)。

scripts/check-windows-footguns.py 在 CI 中强制执行这一规则:任何新增的 os.kill(pid, 0) 调用都会导致 Windows footguns (blocking) 检查失败,除非该行带有 # windows-footgun: ok — <reason> 标记。

常见问题​

安装后立即出现 hermes: command not found。 请打开一个新的 PowerShell 窗口。安装程序已将 %LOCALAPPDATA%\kopi\bin 添加到用户 PATH,但已有 shell 需要重启才能生效。在此之前,你可以运行 & "$env:LOCALAPPDATA\hermes\bin\kopi-agent.cmd"。

运行工具时出现 WinError 193: %1 is not a valid Win32 application。 你遇到的是一次绕过了 .cmd shim 的 shebang 脚本调用。Kopi Agent 通过 shutil.which(cmd, path=local_bin) 解析命令,从而让 PATHEXT 能够识别 .CMD——如果你是通过硬编码路径调用该工具,请改用 .cmd 形式(例如 npx.cmd,而非 npx)。

[scriptblock]::Create(...) 失败并报 The assignment expression is not valid。 你下载的 install.ps1 带有 UTF-8 BOM。irm | iex 形式会自动去除 BOM;[scriptblock]::Create((irm ...)) 则不会。请使用简单的 irm | iex 形式重新运行,或者手动下载脚本并通过 [IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false)) 保存为不含 BOM 的文件。

重启后 Gateway 无法保持运行。 请检查 kopi gateway status——它会合并 schtasks 条目、启动文件夹快捷方式(如果使用了的话)以及当前运行的 PID。如果 schtasks 已注册但未运行,可能是组策略阻止了 ONLOGON 触发器。运行 schtasks /Query /TN HermesGateway /V /FO LIST 查看任务失败原因,或者卸载后使用 KOPI_GATEWAY_FORCE_STARTUP=1 重新安装,以回退到启动文件夹方案。

设置 $env:EDITOR 后 /edit 仍然没有任何效果。 你只是在当前进程中设置了它;请关闭并重新打开 shell,或者在"系统属性 → 环境变量"中以用户作用域设置。可在新的 PowerShell 窗口中用 echo $env:EDITOR 验证。

浏览器工具能启动,但工具调用超时。 Chromium 会在首次运行时自动安装。如果安装失败(GitHub 限流、Playwright CDN 抖动),请运行 kopi doctor——它会提示缺失的 Chromium,并打印出用于修复的确切 npx playwright install chromium 命令。

agent-browser 失败,并出现奇怪的 Node 版本错误。 安装程序会将 Node 22 部署到 %LOCALAPPDATA%\kopi\node,但你的 PATH 中可能把较旧的系统 Node 18 排在前面。要么把 Kopi Agent 的 node 目录在 PATH 中前移,要么如果你在别处不使用 Node,就删除系统安装的版本。

中文 / 日文 / 阿拉伯文字符在 CLI 中显示为 ?。 UTF-8 stdio shim 没有激活。请确认 KOPI_DISABLE_WINDOWS_UTF8 未被设置(Get-ChildItem env:KOPI_DISABLE_WINDOWS_UTF8)。如果它为空而你仍看到 ?,则可能是控制台宿主(非常旧的 cmd.exe)完全不支持 UTF-8——请改用 Windows Terminal。

Gateway 无法发送 Telegram 图片——"BadRequest: payload contains invalid characters"。 这与 Windows 无关,但有时会最先在 Windows 上暴露出来。通常这意味着你的文件路径在 JSON 正文中包含未转义的反斜杠。Telegram 应该收到的是 Kopi Agent 归一化后的路径,而不是原始 Windows 路径——如果你在自定义插件中遇到此问题,请确保传入的是 Kopi Agent 提供的路径,而不是来自用户输入的 str(Path(...))。

git pull 之后出现"在我的另一台机器上是好的"这类编码怪异问题。 如果你在 Windows 上使用非 UTF-8 编辑器(旧版 Windows 的记事本、某些中文输入法)编辑过 Kopi Agent 配置或某个 skill,文件可能已带有 BOM 保存。Kopi Agent 在大多数配置读取中能容忍 utf-8-sig,但折叠 YAML 标量(description: >)内部的 BOM 会在不知不觉中破坏 YAML 解析。请将文件重新保存为不含 BOM 的纯 UTF-8 格式。

下一步阅读​

  • 安装 ——完整的安装页面,涵盖 Linux/macOS/WSL2/Termux。
  • Windows (WSL2) 指南 ——如果你需要 POSIX 语义或仪表盘的终端面板。
  • CLI 参考 ——所有 kopi 子命令。
  • FAQ ——常见的非 Windows 特有问题。
  • 消息网关 ——在 Windows 上运行 Telegram/Discord/Slack。