INSTALL GUIDE / STABLE CHANNEL

ByteGo CLI 安装指南

适用于 Windows、macOS 和 Linux。请先连接 VPN，再完成安装。安装完成后，在新的终端窗口或 VSCode 集成终端输入 bytego 即可启动；也可以在工作区代码中导入已发布的 CLI 模块。

ByteGo CLI

PS C:\> bytego --version
4.3.4
PS C:\> bytego
BYTEGO CLI | V4 | STABLE

01 / INSTALL

一键安装

先连接 VPN，再使用下方对应系统的命令。安装器会下载、校验并配置启动命令；默认不修改 macOS/Linux 系统软件包。

Windows PowerShell

在 PowerShell 中运行。不要把命令粘贴到旧版 CMD。

irm https://hk.bytegoclaw.icu/claw/install.php | iex

macOS

在 Terminal 中运行。命令兼容旧版 macOS curl，可规避部分网关 HTTP 400 与 TLS 握手异常；脚本只会在下载成功后执行，并自动写入常用 Shell 的 PATH 配置。

tmp="$(mktemp)" || exit 1; bytego_exit=0; if curl --disable --http1.1 --tlsv1.2 --retry 3 --retry-delay 1 --connect-timeout 15 -fsSL -A 'Mozilla/5.0 AppleWebKit/537.36 Chrome/131.0.0.0 Safari/537.36' -H 'Accept: */*' -H 'Cache-Control: no-cache' -o "$tmp" https://hk.bytegoclaw.icu/claw/install.sh; then sh "$tmp" || bytego_exit=$?; else bytego_exit=$?; fi; rm -f "$tmp"; [ "$bytego_exit" -eq 0 ] || exit "$bytego_exit"; exec "$HOME/.local/bin/bytego"

Linux

在终端中运行。命令会以浏览器兼容请求头下载，规避部分网关 HTTP 400 与 TLS 握手异常；仅在下载成功后执行，并支持常用发行版的软件包管理器。

tmp="$(mktemp)" || exit 1; bytego_exit=0; if curl --disable --http1.1 --tlsv1.2 --retry 3 --retry-delay 1 --connect-timeout 15 -fsSL -A 'Mozilla/5.0 AppleWebKit/537.36 Chrome/131.0.0.0 Safari/537.36' -H 'Accept: */*' -H 'Cache-Control: no-cache' -o "$tmp" https://hk.bytegoclaw.icu/claw/install.sh; then sh "$tmp" || bytego_exit=$?; else bytego_exit=$?; fi; rm -f "$tmp"; [ "$bytego_exit" -eq 0 ] || exit "$bytego_exit"; exec "$HOME/.local/bin/bytego"

系统组件：Windows 安装器会准备 ByteGo 所需的私有运行时。macOS/Linux 默认不会安装 Homebrew、Python 或系统软件包；请先提供 Python 3.8+，或明确用 BYTEGO_INSTALL_PYTHON=1 sh install.sh 授权现有包管理器安装 Python。

高级安装可用 BYTEGO_INSTALL_DIR、BYTEGO_BIN_DIR 自定义目录；容器或 CI 环境设置 BYTEGO_SKIP_PATH=1 可跳过 Shell/PATH 修改，现有配置不会被覆盖。

01 / UNINSTALL

卸载但保留设置

默认只移除程序文件、私有运行时、启动器和安装器写入的 PATH 行，API Key、模型分组与其他设置会保留，之后可直接重新安装。

Windows

irm https://hk.bytegoclaw.icu/claw/uninstall.php | iex

发布包用户可运行 uninstall.cmd。远程脚本默认保留配置；清空配置需显式执行 $s = irm https://hk.bytegoclaw.icu/claw/uninstall.php; & ([scriptblock]::Create($s)) -Purge -Yes。

macOS / Linux

tmp="$(mktemp)" && curl --disable --http1.1 --tlsv1.2 -fsSL -o "$tmp" https://hk.bytegoclaw.icu/claw/uninstall.sh && sh "$tmp"; status=$?; rm -f "$tmp"; exit "$status"

发布包用户可运行 sh uninstall.sh。先用 --dry-run 预览，清空配置时才使用 --purge。

02 / NETWORK

使用前先连接 VPN

ByteGo 需要访问模型服务和更新服务器。请先连接能正常访问 hk.bytegoclaw.icu 与 hk.bytegoclaw.icu 的 VPN，再打开新的终端窗口。

连接 VPN

确认 VPN 客户端显示已连接，并选择可访问目标站点的节点。

打开新终端

连接或切换节点后，重新打开 CMD、PowerShell、Terminal 或 Shell，让网络和 PATH 状态刷新。

检查后启动

bytego --version

进入程序后可输入 /doctor 检查网络、模型和工作目录。

02 / PATH

验证命令已加入 PATH

关闭当前终端并重新打开

环境变量变更通常只会由新启动的 PowerShell、CMD 或终端应用读取。

确认启动器位置

Get-Command bytego -ErrorAction Stop

CMD 可运行 where bytego；macOS/Linux 可运行 command -v bytego。

启动并检查版本

bytego --version

当前稳定版应显示 4.3.4。进入程序后也可输入 /version。

03 / CONNECTION

ByteGo 服务地址与 SOCKS5 代理

模型请求默认统一使用 ByteGo 的 OpenAI 兼容端点。需要代理时，可以在 ByteGo CLI 内使用 /connect 设置本机 SOCKS5。

ByteGo 默认端点

使用 https://www.bytego.team/v1，Claude、GPT、Gemini、Grok 和国模均走 OpenAI 兼容请求。

/connect domestic

选择更新节点

更新文件使用香港 https://hk.bytegoclaw.icu/claw/ 或东京 https://jp.bytegoclaw.icu/claw/，不会改变模型端点。

/connect international

查看状态

确认当前预设、实际 Base URL 和脱敏后的代理地址。

/connect status

SOCKS5 代理

菜单中选择“自定义 SOCKS5 节点”，依次填写 IP/域名、端口、可选用户名和可选密码；密码输入不会回显。

/connect socks5

/connect proxy socks5://127.0.0.1:1080

/connect proxy off

环境变量优先：BYTEGO_BASE_URL 和 BYTEGO_SOCKS5_PROXY 会覆盖本地设置。PowerShell 使用 Remove-Item Env:BYTEGO_BASE_URL、Remove-Item Env:BYTEGO_SOCKS5_PROXY 清除；macOS/Linux 使用 unset BYTEGO_BASE_URL BYTEGO_SOCKS5_PROXY，再重新启动 CLI。

代理地址也可直接输入 /connect socks5://127.0.0.1:1080，或使用 /connect proxy <主机> <端口> [用户名] [密码]；认证代理格式为 socks5://用户:密码@主机:端口。CLI 会统一转换为 socks5h://，使域名解析也经过代理。切换到国内直连会关闭本地保存的代理。需要使用其他兼容网关时，仍可输入 /endpoint <地址>；预设线路可用 domestic/cn 和 international/intl 别名。

04 / FREE MODELS

使用服务端托管的免费模型

免费模型由 ByteGo 服务端代理提供。CLI 只会看到并保存模型 ID；上游地址、接口类型和 API Key 不会显示在客户端，也不会写入本机配置。

查看目录

进入 ByteGo 后读取当前公开可用的模型。目录中只显示 modelid，短时间内会复用缓存。

/free

选择并使用

TTY 中可用方向键选择，也可用编号或模型 ID；目录变化时先刷新。

/free <modelid>

/free search <关键词>

恢复常规模型

退出免费模式后，恢复已配置的模型和本地分组。

/free off

完整能力：免费模型支持普通聊天、/agent <任务>、/agent on 自动 Agent 和 /skill <名称> <任务>。请求仍由服务端代理转发，本地工具权限、工作区边界和写入确认与常规模型一致。/fewtokens on 是纯聊天模式，会固定关闭 Agent 与 Skills。输入 /free status 可查看状态，使用 /model 选择常规模型会退出免费模式。

站点管理员：如何上架免费模型

将发布包中的 claw/manage.php、claw/free-models.php 和 claw/update-notice.json 放到 https://hk.bytegoclaw.icu/claw/。PHP cURL 已启用，PHP 进程需要能写入该目录或由 BYTEGO_FREE_MODEL_STORE 指向的私有存储文件。管理页是 /claw/manage.php，使用内置密码 917813 登录。请将管理页限制在受控运维访问范围内。

登录后为每个 modelid 在“上游节点与 API Key”中按空行填写分组：每组第一行是 HTTPS URL，后续每行是一条该 URL 的 API Key，至少一条 Key。

https://api-one.example/v1
key-one
key-two

https://api-two.example/v1
key-three

接口当前固定为 OpenAI-compatible Chat Completions SSE，可通过“上架并允许客户端使用”控制目录可见性。服务端会随机选择 URL 与同组 Key 的组合；若连接、鉴权、限流或 5xx 错误发生在上游 SSE 流开始前，会继续尝试其它组合，流开始后不会切换。

客户端使用 https://hk.bytegoclaw.icu/claw/free-models.php，公开 GET 只返回 modelid；不要把 URL、密钥或接口类型写入公开目录、安装页或 CLI 配置。

05 / VSCODE

在 VSCode 集成终端和工作区使用

ByteGo CLI 可以直接在 VSCode 的集成终端运行，不需要额外的 VSCode 扩展。安装或切换 PATH 后请重启 VSCode。

打开集成终端

选择“终端 → 新建终端”（Windows/Linux 可按 Ctrl+`，macOS 可按 Control+`），确认终端位于当前工作区。

启动 CLI

bytego

CLI 会以当前 VSCode 工作区作为工作目录。可用 /pwd 查看、/cd <路径> 切换，/doctor 检查网络和接口。

在项目代码中导入

开发或自动化场景可以导入发布包源码的 bytego_cli 模块。将源码目录的 src 加入 VSCode 当前解释器的 PYTHONPATH，再执行：

# PowerShell
$env:PYTHONPATH = "C:\path\to\bytego-cli\src"
python -c "import bytego_cli; print(bytego_cli.__version__)"

# macOS / Linux
PYTHONPATH="/path/to/bytego-cli/src" python -c 'import bytego_cli; print(bytego_cli.__version__)'

命令行入口也可从 bytego_cli.cli 导入 main()。普通使用直接运行 bytego 即可；模块导入属于可选开发用法。

解释器提示：一键安装不要求提前安装开发环境；只有在 VSCode 项目中直接导入源码模块时，才需要选择可用的 Python 3.8+ 解释器。

06 / INSTALL COMPONENTS

安装器无法准备组件时

Windows 使用私有运行时；macOS/Linux 使用系统已有 Python 3.8+，默认不会修改系统软件包。若缺少 Python，请按下方平台方式手动安装，或显式授权安装器使用现有包管理器。

Windows

确认 PowerShell 可运行、系统时间正确，并重新连接 VPN。Windows 安装器会准备私有运行时；失败时可先安装 Python 3.8+，然后重新运行。

winget install -e --id Python.Python.3.12

Windows 7 没有 winget 时，请使用 Python 官方历史安装包中的兼容 Python 3.8，并在安装时勾选 “Add Python to PATH”。

macOS

确认 VPN 已连接、系统时间正确；请先安装 Python 3.8+ 后重新运行一键安装。安装器默认不会自动安装 Homebrew。

brew install python@3.12

没有 Homebrew 时可使用 Python 官方 macOS 安装包。

Ubuntu / Debian

确认 VPN 已连接并允许系统软件源访问网络；请先安装系统的 Python 3.8+ 后重新运行一键安装。只有设置 BYTEGO_INSTALL_PYTHON=1 才会调用包管理器。

sudo apt update && sudo apt install -y python3

确认版本：打开新的终端，运行 python --version（Windows）或 python3 --version（macOS/Linux）；结果应为 3.8 或更高。随后重新运行上方的一键安装命令。

07 / UPDATE

更新到最新稳定版

启动 ByteGo 后，输入下面的命令。建议全程保持 VPN 连接；更新器会先下载并校验新文件，再替换旧版本。

/update

稳定通道	https://hk.bytegoclaw.icu/claw/
当前发行版	ByteGo CLI `4.3.4` V4
xhigh 效果	切换到 `/effort xhigh` 会播放一次全屏彩色雷霆场景；设置 `BYTEGO_EFFECTS=0` 或 `NO_COLOR=1` 可关闭。
低深度提示	确认切换到 `off`、`low` 或 `medium` 会播放短暂的全屏“没实力啊牢底”提示；传统终端会自动降级为纯文本。
FewTokens	`/fewtokens on` 是纯聊天模式：只发送当前消息，固定关闭推理、Agent 和 Skill 执行。

08 / TROUBLESHOOTING

故障排除

/free 没有模型或提示服务不可用

先确认 VPN 和网络可访问 hk.bytegoclaw.icu，再输入 /free 重试。免费模型目录由服务端管理，客户端不需要填入该模型的 API Key。若只有部分用户异常，请让站点管理员检查 /claw/free-models.php 是否能返回只含 modelid 的 JSON 目录。

irm ... | iex 提示 Null 值表达式

请使用 install.php，不要使用服务器可能以空响应或错误 MIME 类型返回的 install.ps1。

irm https://hk.bytegoclaw.icu/claw/install.php | iex

bytego 显示找不到路径或不是内部命令

先关闭并重新打开终端。Windows 可直接运行启动器确认安装内容是否存在：

& "$env:LOCALAPPDATA\ByteGoCLI\bin\bytego.cmd" --version

若该文件不存在，请重新运行 Windows 安装命令；若文件存在但 bytego 不可用，请重启终端应用或注销后再登录。

macOS 或 Linux 显示 TLS 握手失败 / EOF

安装器和更新器会自动改用系统 curl 重试，且不会关闭 HTTPS 证书校验。确认系统时间正确、curl --version 可运行，并重新执行安装命令。企业网络需要允许访问 hk.bytegoclaw.icu 与 hk.bytegoclaw.icu。

Windows 7 无法自动准备组件

请确认系统为 Windows 7 SP1，并安装 PowerShell 3.0+ 与 .NET Framework 4.5+。同时确认 VPN 已连接、系统时间正确；若下载被网络策略阻止，请换用可访问目标站点的网络后重新运行安装命令。

没有管理员权限

Windows 安装到当前用户的 %LOCALAPPDATA%\ByteGoCLI，macOS/Linux 安装到用户目录，通常不需要以管理员身份运行。Linux 若系统要求安装组件，可能会请求 sudo 权限。

为什么必须使用 VPN？

模型请求、版本检查和更新都需要访问外部服务。请连接能访问 hk.bytegoclaw.icu 与 hk.bytegoclaw.icu 的 VPN，再启动 ByteGo。VPN 只负责网络连通，不会读取或保存你的 API Key。

连接 VPN 后仍然出现 HTTP 400、403、EOF 或 TLS 错误

先退出 ByteGo，确认系统时间正确，切换一个可用 VPN 节点，然后打开新的终端重试。macOS/Linux 安装器和更新器会自动使用系统 curl 重试，并保持证书校验；不要使用 -k。如果企业网络有域名白名单，请放行 hk.bytegoclaw.icu、hk.bytegoclaw.icu 以及系统软件源。

安装成功但输入 bytego 找不到命令

关闭当前窗口并重新打开，让 PATH 重新加载。Windows 使用 where bytego，macOS/Linux 使用 command -v bytego。如果仍找不到，请重新运行对应系统安装命令；不要把安装目录手动改名。

如何选择国内、国际直连或 SOCKS5 代理

输入 /connect international 恢复 ByteGo 默认端点 https://www.bytego.team/v1。通过代理访问使用 /connect proxy socks5://127.0.0.1:1080，关闭代理使用 /connect proxy off，状态使用 /connect status。若设置了 BYTEGO_BASE_URL 或 BYTEGO_SOCKS5_PROXY，请先清除对应环境变量。

可以导入到 VSCode 项目吗

可以在 VSCode 集成终端直接运行 bytego，也可以把发布包源码的 src 加入 PYTHONPATH 后导入 bytego_cli，或调用 bytego_cli.cli.main()。这属于开发用模块导入，不需要额外的 VSCode 扩展；直接导入源码时请选择 Python 3.8+ 解释器。

启动后提示没有配置 Key

首次启动按提示输入所需分组的 Key，不使用的分组直接回车跳过。也可以在程序内使用 /setup 或 /group key <分组>。Key 会保存在当前用户配置目录，不会显示在状态面板中。

如何检查当前版本和网络状态？

在终端运行 bytego --version 查看版本；进入程序后运行 /version 和 /doctor。升级前请保持 VPN 连接，在程序内输入 /update。

如何卸载？

先退出 ByteGo。Windows 删除当前用户的 %LOCALAPPDATA%\ByteGoCLI 并从用户 PATH 删除对应的 bin 目录；macOS 删除 ~/Library/Application Support/ByteGoCLI 和 ~/.local/bin/bytego；Linux 删除 ~/.local/share/bytego-cli 和 ~/.local/bin/bytego。如需保留 Key，请先备份配置目录。