CodeBuddy终端命令行模式配置与使用教程

如果你已经安装了CodeBuddy CLI工具，但在终端里敲命令却毫无反应，或者总是报错，先别急着卸载。这通常不是什么大问题，多半是环境没配好、权限没放开，或者关键的配置文件缺失了。下面这几个步骤，能帮你一步步排查，让命令行模式真正“活”起来。

一、验证并修复 Node.js 与 npm 环境

CodeBuddy CLI 本质上是一个Node.js应用，所以它的“地基”必须稳固。如果Node.js版本低于v18，或者npm压根没被系统识别，那后续所有操作都是空中楼阁。

首先，打开你的终端，分别输入 node --version 和 npm --version 看看。理想情况下，版本号应该分别不低于 v18.0 和 v8.0。

如果终端直接回复你“command not found”（找不到命令），那就说明环境变量没配好。这时候，你需要重新安装Node.js。安装时，务必勾选那个“Add to PATH”（添加到系统路径）的选项（Windows用户尤其要注意）。如果是手动配置，记得把Node.js的安装目录（比如macOS/Linux下的 /usr/local/bin，或者Windows下的 C:\Program Files\nodejs）添加到系统的环境变量里。

完成之后，关掉终端再重新打开，再次验证命令是否可用。这是让系统加载新环境变量的关键一步。

二、全局安装 CodeBuddy CLI 包

环境没问题了，下一步就是确保CLI工具本身被正确安装到了全局。这个过程需要npm有写入全局目录的权限。

直接运行安装命令：npm install -g @tencent-ai/codebuddy-code。

这里有个Windows用户常踩的坑：如果你用的是PowerShell，可能会遇到一个脚本执行策略的报错，提示“cannot be loaded because running scripts is disabled”。别慌，这是系统的安全限制。你只需要以管理员身份打开PowerShell，运行命令：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后输入“Y”确认即可。这个操作是放宽当前用户的脚本执行权限，让安装得以继续。

安装完成后，敲入 codebuddy --version。如果能顺利显示出版本号，恭喜你，CLI工具已经成功入驻你的终端了。

三、完成用户级登录与模型授权

工具装好了，但还没“认主”。首次使用必须完成身份认证，否则你发出的任何自然语言指令都会被拒绝，AI模型也无法调用。

在终端任意路径下，输入：codebuddy login。

接下来会弹出登录引导。通常，国内用户直接扫码用微信登录最方便，国际用户则可以选择GitHub或Google账号授权。

登录成功的那一刻，你的认证信息就已经被安全地保存在本地了（位置在 ~/.codebuddy/auth.json）。以后使用就不再需要重复登录，非常省心。

四、配置本地 settings.json 文件

如果说登录是拿到了“入场券”，那么配置文件就是你的“个性化设置中心”。没有这个文件，CLI会使用一套非常宽松的默认策略，可能导致一些非预期的行为，比如模型降级或者功能受限。

首先，创建专用的配置目录：mkdir -p ~/.codebuddy。

然后，在里面新建一个配置文件：touch ~/.codebuddy/settings.json（Windows用户可以用其他方式创建空文件）。

接下来，用你喜欢的文本编辑器打开这个文件，写入最基础的配置。比如，指定使用中文界面和DeepSeek模型：
{"language": "简体中文", "model": "deepseek-v3"}

保存文件。之后每次启动CodeBuddy CLI，它都会自动读取这份配置，按你的偏好来工作。

五、启用权限白名单与安全策略

这是高级但至关重要的一步，关乎到“安全边界”。你肯定不希望AI助手在未经你明确同意的情况下，就去执行git push、或者向不明地址发送网络请求吧？

通过权限配置，你可以精确划定CLI能做什么、不能做什么。编辑刚才的 ~/.codebuddy/settings.json 文件，我们需要在其中加入 permissions 字段。

举个例子，你可以明确允许它运行项目里的代码检查和测试脚本：
"allow": ["bash(npm run lint)", "bash(npm run test:*)"]

同时，也可以明确禁止它读取某些敏感文件，比如环境变量配置文件或密钥目录：
"deny": ["read(./.env)", "read(./secrets/**)"]

配置保存后，建议重启CLI终端，或者执行 codebuddy config --reload 命令，让新的安全策略立刻生效。这样一来，你既享受了AI助手的强大自动化能力，又把风险控制在了自己手中。