1. 装好它-四种环境

来源：CodeBuddy

这一章的目标只有一个：不管你用什么机器，走完这一章，codebuddy 这条命令能用。

先说清楚一件事：这一章看起来长，是因为我把 macOS、Linux、Windows PowerShell、WSL2 四种环境分开写了。你只需要看你那一段，别的一眼扫过就行。

先确认你在哪个环境

如果你分不清自己属于哪一类，先做这个判断：

macOS / Linux（bash、zsh）

uname -a

有输出（一串系统信息）→ 你在这两类里。再敲 sw_vers 有输出就是 macOS，没有就是 Linux。

Windows PowerShell

$PSVersionTable.PSVersion

能显示版本号 → 你在 PowerShell 里。

WSL2

在 Windows 上打开 Ubuntu（或你装的发行版）终端，敲：

uname -a

输出里带 microsoft 或 WSL 字样 → 你在 WSL2 里。

关键区别：WSL2 是 Windows 里跑的 Linux，它按 Linux 的方式装、按 Linux 的方式用。它和"Windows PowerShell 原生"是两套环境，可以各装一份，互不干扰，但坑不一样——后面单独讲。

三条安装路线，选一条

CodeBuddy Code 有三种装法，挑一种就行：

路线	命令	前提	适合谁
npm 系	npm install -g @tencent-ai/codebuddy-code	Node.js ≥ 18.20	机器上本来就有 Node 的开发者
Homebrew	brew install Tencent-CodeBuddy/tap/codebuddy-code	无（不用 Node）	macOS / Linux 用户，最省事
原生安装器（Beta）	一行脚本	无（不用 Node）	想要单文件、启动快、自动更新稳的人

我的建议：macOS 和 Linux 用 Homebrew，Windows 用原生安装器脚本。都不想折腾就直接用原生安装器，三种系统都能跑。

三条路最后得到的命令都是 codebuddy，功能没有区别。

---

macOS

第一步：装命令行工具（首次需要）

打开"终端"（Terminal），敲：

xcode-select --install

弹窗点"安装"，等它跑完。这一步是为了拿到 git 和基础编译工具，后面会用到。

第二步：选一条安装路线

路线 A：Homebrew（推荐）

没有 Homebrew 先装它：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

装完按提示把 brew 加进 PATH。注意 Apple 芯片（M1/M2/M3/M4）的 brew 在 /opt/homebrew，Intel 在 /usr/local，装完终端会告诉你该加哪一行。

然后装 CodeBuddy：

brew install Tencent-CodeBuddy/tap/codebuddy-code

路线 B：原生安装器（不用装 Node）

curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash

路线 C：npm（需要 Node ≥ 18.20）

npm install -g @tencent-ai/codebuddy-code

没有 Node 的话：brew install node。

第三步：如果命令找不到

原生安装器会把可执行文件放在 ~/.local/bin。如果敲 codebuddy 提示 command not found，手动加 PATH：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

macOS 从 Catalina 开始默认 shell 是 zsh，配置文件是 ~/.zshrc。如果你改过默认 shell 用 bash，那就是 ~/.bash_profile。不确定？敲 echo $SHELL，显示 /bin/zsh 就用 .zshrc，/bin/bash 就用 .bash_profile。

---

Linux

第一步：装依赖

Ubuntu / Debian

sudo apt update
sudo apt install -y curl git

CentOS / RHEL / Fedora

sudo dnf install -y curl git

（老版本 CentOS 用 yum 代替 dnf。）

第二步：选一条安装路线

路线 A：Homebrew（如果已装 brew）

brew install Tencent-CodeBuddy/tap/codebuddy-code

路线 B：原生安装器（推荐，不用 Node）

curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash

路线 C：npm

npm install -g @tencent-ai/codebuddy-code

注意：apt 源里的 Node 版本经常很旧（可能低于 18.20）。要用 npm 路线，建议先装 nvm 或按 NodeSource 的指引装 LTS 版本，别直接 apt install nodejs。

第三步：PATH

命令找不到就加：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

用 zsh 的话把 .bashrc 换成 .zshrc。

没有 sudo 权限怎么办

用原生安装器时它会装到你的家目录，不需要 sudo。如果还是报权限错误，可以先指定一个自己的安装目录（具体参数以官方安装脚本提示为准），或者直接用 npm 路线配 nvm（nvm 装在 ~/.nvm，也不需 sudo）。

---

Windows PowerShell（原生）

第一步：确认执行策略

PowerShell 默认可能禁止运行远程脚本。先看一下当前策略：

Get-ExecutionPolicy

如果显示 Restricted，改成允许本地用户运行签名脚本：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

提示确认时输入 Y 回车。这一条只改当前用户，不影响系统其他账户。

第二步：安装

路线 A：原生安装器（推荐）

irm https://www.codebuddy.cn/cli/install.ps1 | iex

（irm 是 Invoke-RestMethod 的简写，iex 是 Invoke-Expression 的简写，作用类似于 bash 里的 curl | bash。）

路线 B：npm

没有 Node 先装：

winget install OpenJS.NodeJS.LTS

装完关掉终端重开一次（让 PATH 生效），再：

npm install -g @tencent-ai/codebuddy-code

第三步：PATH

原生安装器装在 %USERPROFILE%\AppData\Local\codebuddy\bin。命令找不到就手动加进用户 PATH：

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\AppData\Local\codebuddy\bin",
  "User"
)

改完必须重开终端，新开的窗口才会生效。

建议：换个好点的终端

系统自带的 PowerShell 窗口体验一般，推荐装 Windows Terminal（微软商店里搜就有），它可以同时开 PowerShell、WSL、cmd 的标签页。

---

WSL2

WSL2 是在 Windows 里跑一个真正的 Linux。它按 Linux 的方式装 CodeBuddy，但有四个坑必须提前知道。

第一步：装 WSL2（如果还没装）

在 PowerShell（管理员身份）里敲：

wsl --install

它会自动装默认的 Ubuntu。想指定版本：

wsl --list --online
wsl --install -d Ubuntu-24.04

装完重启，开始菜单里会出现 Ubuntu，打开后设置用户名密码。

确认一下版本是 2：

wsl -l -v

VERSION 那一列应该是 2。如果是 1，执行 wsl --set-version Ubuntu-24.04 2。

第二步：在 WSL 里装 CodeBuddy

打开 Ubuntu 终端，按 Linux 的方式装：

sudo apt update && sudo apt install -y curl git
curl -fsSL https://www.codebuddy.cn/cli/install.sh | bash

装完如果需要：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

坑一：项目必须放在 WSL 的文件系统里

这是 WSL 性能问题里最大的一个。

# 对的：放在 WSL 自己的家目录
cd ~/projects/my-app

# 错的：放在 Windows 盘符映射过来的目录，会慢到怀疑人生
cd /mnt/c/Users/xxx/projects/my-app

/mnt/c/ 是跨文件系统的访问，读写速度差一个量级，尤其跑 npm install、git 操作的时候。代码放 WSL 里，需要用 Windows 工具编辑时再映射过去。

坑二：换行符

Windows 用 CRLF，Linux 用 LF。你在 WSL 里写代码、Windows 侧用编辑器打开，很容易搞出满屏 diff。

在 WSL 里设一次：

git config --global core.autocrlf input

含义是：提交时统一转成 LF，检出时不转换。这样仓库里永远是干净的 LF。

坑三：cron 不会自动启动

WSL 里 cron 服务默认不随系统启动。要用定时任务时：

sudo service cron start

想每次开机自动起，可以把这行加进 ~/.bashrc（或者配置 WSL 的 /etc/wsl.conf 开启 systemd）。

坑四：和 Windows 侧各装一套

你可以在 PowerShell 里装一份、在 WSL 里再装一份，两者独立，配置目录也不共享（Windows 是 %USERPROFILE%\.codebuddy，WSL 是 ~/.codebuddy）。

建议只在你主要干活的那一侧装，避免自己搞混"我刚才在哪边跑的"。

---

验证：确认装好了

不管哪个平台，都敲这一条：

codebuddy --version

显示版本号就是装好了。再进一次会话，敲 /doctor 让它自己体检一遍环境。

顺便认识一下它的短命令：

cbc --version

cbc 是 codebuddy 的简写，后面教程里两个都会出现，你习惯哪个用哪个。

登录

第一次启动：

codebuddy

会让你选登录方式：

Select login method:
› Log in via Chinese Site
  Log in via International Site
  Log in via Enterprise Domain
  Log in via iOA (Tencent only)

用 ↑↓ 选择，Enter 确认，然后浏览器会自动打开让你完成认证。

四个选项的区别：

• Chinese Site（国内站）：国内用户选这个，走腾讯云国内站
• International Site（国际站）：海外用户
• Enterprise Domain（企业域名）：公司自建或专享版，需要填企业给的服务地址
• iOA：腾讯内部员工专用

选错了没关系，随时可以 /logout 再 /login 换。

更新与卸载

更新

codebuddy update

它会自动检测你的安装方式并执行对应更新。默认也会自动更新，想关掉：

export DISABLE_AUTOUPDATER=1

从 npm 版迁移到原生版

codebuddy install

卸载

用哪条路装的就用哪条卸：brew uninstall codebuddy-code / npm uninstall -g @tencent-ai/codebuddy-code。原生安装器的话，删掉 ~/.local/bin/codebuddy（Windows 是 %USERPROFILE%\AppData\Local\codebuddy）即可。

四个平台的常见坑

症状	可能原因	怎么解决
command not found / 不是内部或外部命令	PATH 没配对	按上面各平台的 PATH 步骤加，且重开终端
装了一半卡住	网络问题	换网络，或改用国内镜像地址 https://copilot.tencent.com/cli/install.sh（PowerShell 是 install.ps1）
Node 版本报错	Node 低于 18.20	换 Homebrew 或原生安装器路线，绕开 Node
PowerShell 报"禁止运行脚本"	执行策略限制	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
WSL 里跑得极慢	项目放在 /mnt/c/	把代码挪到 WSL 家目录
git diff 全是改动其实没改	换行符不一致	WSL/Linux/macOS 设 core.autocrlf input
装完命令能跑但登录不了	网络或代理	检查代理环境变量，或换一种登录方式

小结

现在你手上有了一条能用的 codebuddy 命令。

下一章我们真的用它干活：建一个练习目录、跑第一次对话、把项目记忆建起来。那之后你才会发现，装好只是最简单的一步。