安装和登录

系统要求

Node.js：版本 18.20 或更高

操作系统: macOS、Linux 或 Windows

验证环境

# 检查 Node.js 版本
node --version  # 应显示 v18.0.0 或更高

# 检查 npm 版本
npm --version

安装方式

使用包管理器安装

Node.js 包管理器

选择本机可用的包管理器执行以下命令:

npm

pnpm

yarn

bun

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

Homebrew (macOS/Linux)

无需 Node.js，直接安装:

两步安装

单命令安装

Brewfile

# 添加 tap
brew tap Tencent-CodeBuddy/tap

# 安装工具
brew install codebuddy-code

使用原生二进制安装（Beta）

说明：

Beta 功能：原生二进制安装目前处于 Beta 测试阶段，功能仍在完善中。 如遇到任何问题，请联系技术支持（codebuddy@tencent.com）。

原生安装器提供独立的 CodeBuddy 安装，无需 Node.js 环境。

下载并安装：

# macOS/Linuxcurl -fsSL https://copilot.tencent.com/cli/install.sh | bash

# Windowsirm https://copilot.tencent.com/cli/install.ps1 | iex

特性说明

原生二进制安装相比 npm 版本提供以下特性：

单一可执行文件，无需额外依赖

无需 Node.js 运行时

改进的自动更新机制

支持平台

macOS (Apple Silicon M1/M2/M3 或 Intel x86_64)

Linux (arm64 或 x86_64)

Windows (x86_64)

从 npm 版本迁移

如果您已经通过 npm 安装了 CodeBuddy Code，可以使用以下命令迁移到原生二进制版本：

codebuddy install

全新安装

macOS / Linux

Windows

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

验证安装

安装脚本会自动下载最新版本并配置环境变量。安装完成后，运行以下命令验证：

codebuddy --version

如果命令不可用，请手动将安装路径添加到环境变量 PATH:

macOS / Linux

Windows

export PATH="$HOME/.local/bin:$PATH"

# 为了永久生效,建议添加到 shell 配置文件:
# Bash: ~/.bashrc 或 ~/.bash_profile
# Zsh: ~/.zshrc

配置目录

CodeBuddy Code 默认将配置文件存储在以下目录:

配置目录内容

~/.codebuddy/├── settings.json      # 用户设置├── .mcp.json          # MCP 服务器配置└── skills/            # 用户自定义 Skills

自定义配置目录

通过设置环境变量 CODEBUDDY_CONFIG_DIR 可以自定义配置目录位置:

export CODEBUDDY_CONFIG_DIR="$HOME/.my-codebuddy-config"

这在以下场景中非常有用:

多个 CodeBuddy 实例需要独立配置

企业环境中需要统一管理配置位置

与其他使用 CodeBuddy 引擎的应用（如 WorkBuddy）共存时避免配置冲突

更新

自动更新

CodeBuddy Code 默认会自动保持最新状态，以确保您拥有最新的功能和安全修复。

关闭自动更新

如需关闭自动更新，可设置环境变量：

export DISABLE_AUTOUPDATER=1

手动更新

使用以下命令手动更新到最新版本：

codebuddy update

update 命令会自动检测您的安装方式并执行相应的更新操作。

使用包管理器更新

如果 codebuddy update 命令未能成功更新，您也可以使用包管理器重新安装：

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

或使用其他包管理器（pnpm、yarn、bun）执行相应的安装命令。

卸载

包管理器版本卸载

Homebrew

npm

pnpm

yarn

bun

# 卸载工具
brew uninstall codebuddy-code

# 移除 tap (可选)
brew untap Tencent-CodeBuddy/tap

原生二进制版本卸载

macOS / Linux

删除可执行文件:

rm -f ~/.local/bin/codebuddy

清理配置文件(可选)

如需完全清理,可删除配置目录:

macOS / Linux:

rm -rf ~/.codebuddyrm -rf ~/.local/share/codebuddy

提示：

如果您使用了 CODEBUDDY_CONFIG_DIR 环境变量自定义了配置目录，请删除对应的目录。

登录认证

首次使用 CodeBuddy Code 时，您需要完成登录认证。启动后会显示登录方式选择界面：

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 确认后会自动打开浏览器完成认证。

常见问题

命令不可用

问题： 安装后提示 codebuddy: command not found

解决方案：

检查安装路径是否在 PATH 环境变量中：

echo $PATH

将 CodeBuddy 安装路径添加到 PATH（参考上方验证安装部分）

重启终端或重新加载配置文件：

source ~/.bashrc  # 或 ~/.zshrc

更新后仍是旧版本

问题： npm install -g 显示安装成功，但 codebuddy --version 仍为旧版本

这通常是系统中存在多个 codebuddy 可执行文件（如同时通过 npm 和 Homebrew 安装、nvm 切换了 Node 版本等）导致。

网络问题

问题： 安装或更新时网络连接失败

解决方案：

检查网络连接

配置 npm 镜像源（如果使用 npm 安装）：

npm config set registry https://registry.npmmirror.com