把 AI 装进终端：火山引擎 veCLI 超细图解指南

从 0 到 1 完成安装、登录、换模型、跑代码、搭博客、配主题，一篇就够

1. 先回答你最关心的 6 个问题

疑问	一句话答案
veCLI 到底是什么？	火山引擎出的“命令行版 AI 助手”，敲一行字就能让大模型帮你写代码、查文档、搭系统。
必须付费吗？	只用火山引擎在线模型才按 token 计费，软件本身免费。
没有 GPU 能跑吗？	完全在线推理，本地只需 Node.js 环境。
和 GitHub Copilot 有啥区别？	工作在终端，不依赖 IDE；可自由切换火山方舟、DeepSeek、Kimi 等模型；还能调用 MCP 服务器操作云资源。
会偷代码吗？	官方默认不记录文件内容，企业版可彻底关闭遥测，详见 §9。
最简安装几步？	① `npm i -g @volcengine/vecli` ② 配 AK/SK ③ `vecli` 回车即可对话。

2. 安装：两条命令搞定

2.1 前置检查

Node.js ≥ 18（node -v 看版本）
能访问 npm 官方源或公司内网镜像

2.2 全局安装

npm install -g @volcengine/vecli@latest

不想全局？用 npx 零安装：

npx @volcengine/vecli@latest

2.3 验证

vecli --version

出现 veCLI vx.x.x 即成功。

3. 第一次登录：AK/SK 图文流

适用于 99% 的个人与服务器场景

步骤	动图级文字指引
① 拿钥匙	打开火山引擎控制台 → 右上角「访问控制」→「访问密钥」→「新建」→ 弹出 AK/SK 对话框，立刻保存，关闭后不可再见。
② 配变量	把下面两行写进 `~/.bashrc` 或 `.zshrc`，`source` 生效： `export VOLCENGINE_ACCESS_KEY="你的 AK"` `export VOLCENGINE_SECRET_KEY="你的 SK"`
③ 验证	运行： `vecli auth status` 提示 `Logged in via AK/SK` 即通过。

4. 30 秒跑通第一个任务

# 非交互模式：直接问
echo "用 Python 写一个斐波那契函数" | vecli

# 或交互模式
vecli
> 写一个斐波那契函数并保存为 fib.py

模型返回代码后，会给出 write_file 操作确认，输入 y 即落盘。

5. 换模型、换主题、加目录：常用 3 招

需求	命令 / 配置
即时换模型	`vecli --model deepseek-v3-1`
永久换模型	在 `~/.ve/settings.json` 写： `{"model": {"name": "deepseek-v3-1"}}`
改主题	在 veCLI 里敲 `/theme` → 选 `Dracula Dark` 即可；自定义色盘见 §8。
一次加多个工作目录	启动时加旗标： `vecli --include-directories ./backend,./frontend`

6. 让 AI 帮你“动手”——文件与 Shell 指令

veCLI 内置工具已覆盖日常高频动作，用法极简单：

自然语言示例	实际会调用的工具
“把 fib.py 改名为 fibonacci.py”	`move_file`
“查看当前 git 状态”	`run_shell_command(git status)`
“在 README.md 末尾加一行 ## License”	`replace_file`（定位插入）

安全提示：
默认每次写文件或执行 shell 前都会弹确认。加 --yolo 可自动通过，但建议只在 CI 场景使用。

7. 搭博客实战：一句话生成可运行代码

vecli -p "用 Express + EJS 搭一个博客，首页列出文章，点击标题进详情，把代码写到 ~/my-blog 目录"

veCLI 会：

创建 app.js、视图、路由；
给你 npm install 命令；
告诉你 node app.js 即可启动。

本地访问 http://localhost:3000，一篇空博客 2 分钟上线。

8. 深度定制：自定义主题 & 自定义命令

8.1 自定义主题（保留自用，可共享）

在 ~/.ve/settings.json 里加：

"ui": {
  "customThemes": {
    "CorpGreen": {
      "name": "CorpGreen",
      "type": "custom",
      "Background": "#002b36",
      "Foreground": "#eee8d5",
      "AccentGreen": "#859900",
      "Comment": "#586e75",
      "Gray": "#839496"
    }
  }
}

保存后 /theme 里就能选到。

8.2 自定义命令：把常用提示存成“快捷键”

场景：每天让 AI 给代码生成单测。

建文件
mkdir -p ~/.ve/commands/test && nano ~/.ve/commands/test/unit.toml
写配置

description = "为当前文件生成 Jest 单元测试"
prompt = """
请读取 @{file} 的内容，并为所有导出函数编写 Jest 测试用例。
要求：
- 使用 TypeScript
- 每个用例至少 2 个断言
- 把测试写到 @{file}.test.ts
"""

使用
在 veCLI 里：

> @src/utils.ts
> /test:unit

AI 会读源码、写测试、落盘，一步到位。

9. 企业管理员必读：集中管控 5 件套

（以下配置全部写在 /etc/vecli/settings.json，权限 644，仅 root 可改）

管控点	示例片段	效果
强制沙盒	`"tools": {"sandbox": "docker"}`	所有 shell、文件操作都在容器，宿主机零写入。
工具白名单	`"tools": {"core": ["ReadFileTool", "ShellTool(ls)"]}`	除列表外任何工具都不可调用。
关闭遥测	`"privacy": {"usageStatisticsEnabled": false}`	任何用户无法上报使用数据。
统一认证	`"security": {"auth": {"enforcedType": "aksk"}}`	禁止 OAuth，强制 AK/SK。
自定义 MCP 目录	`"mcp": {"allowed": ["corp-tools"]}, "mcpServers": {"corp-tools": {...}}`	用户无法追加第三方 MCP。

合并优先级：
系统 override > 项目 > 用户 > 系统 default；数组（如 includeDirectories）做加法，同名单值以最高级为准。

10. 常见问题 FAQ

Q1. 公司内网无法拉取 npm 包怎么办？
A: 先把 @volcengine/vecli 拉到私有 Nexus，再 npm i -g @volcengine/vecli --registry=https://your-npm-mirror。

Q2. 想同时用多个火山引擎子账号？
A: 建不同目录，各自写 .ve/.env 放对应 AK/SK，启动时加 --project-dir。

Q3. 模型返回乱码或卡死？
A: 检查终端 UTF-8 编码：export LANG=en_US.UTF-8；仍卡死加 --debug 看日志，多数是代理超时。

Q4. 如何让 CI 自动批准工具？
A: 启动参数加 --approval-mode yolo，或把命令写进允许列表 "tools": {"allowed": ["write_file", "run_shell_command(npm test)"]}。

Q5. 能离线运行吗？
A: 推理依赖火山引擎在线 API，完全离线需本地部署大模型，veCLI 目前不提供私有模型接口。

11. 检查清单：安装完必做的 7 件事

vecli auth status 确认登录成功
vecli test-connection 看网络延迟
vecli --model 换到你预算最合适的模型
写第一个 VE.md 放项目根目录，告诉 AI 你的编码规范
把常用提示封装成 .toml 丢进 ~/.ve/commands
公司电脑加 --sandbox 防止误操作
把 .ve/ 写进 .gitignore，避免密钥上传

12. 下一步还能玩什么？

把 GitHub MCP 接进来，直接让 AI 帮你建 issue、审 PR
写 sandbox.Dockerfile 预装内部工具链，团队一键共享环境
用 /memory refresh 动态更新上下文，实现“多租户”提示
开 --telemetry 接自家 OTLP，大盘实时看哪个模型最省 token

终端不再是黑框，而是你随叫随到的 AI 同事。
装好 veCLI，今天就把重复劳动交给它，留点时间给真正的创造。

从0到1保姆级教程！火山引擎veCLI安装使用指南+代码生成实测