vinhnx/VTCode · 上手攻略
- 仓库：vinhnx/VTCode
- 链接：https://github.com/vinhnx/VTCode
- 分类：终端编程 Agent（Rust）
- 作者：Tom
- 更新：2026-10-07
一、是什么
VTCode 是一个用 Rust 编写的开源终端编程 Agent（coding agent），运行在交互式 TUI 中，允许用户在终端里完成代码探索、任务规划、工具执行和变更审查。它与 OpenAI Codex CLI、GitHub Copilot CLI 等工具属于同一品类，但核心差异在于：完全开源（23 个 crates 的完整 Rust 代码）、可审计的安全沙箱、以及多模型/多集成支持。
官方自称 "VT Code is an open-source Rust terminal coding agent"。
二、解决什么问题
大多数编程 Agent（如 Claude Code、Copilot CLI）以黑盒形式交付，用户无法审计工具调用策略和沙箱边界。VTCode 针对这个问题做了以下设计：
- Planning-first 工作流：先用只读 planning agent 调查代码库、形成计划，用户审批后才执行写操作，避免 Agent 盲目修改。
- 可审计的命令策略（Command Policy）：沙箱规则写死在配置中，用户可以 review，而不是靠隐式限制。
- 安全执行（full_auto 信任分级）：VTCODE_TRUST_WORKSPACE 环境变量控制自动化权限，非 TTY 环境默认拒绝 autonomous exec。
- 会话持久化与恢复：任务中断后可
vtcode continue恢复，vtcode trajectory查看执行轨迹。 - Headless 执行：
vtcode exec支持完全无 TUI 的批量任务，配合 cron schedule 实现定期自动化。
三、快速安装
官方安装脚本（推荐）
curl -fsSL https://raw.githubusercontent.com/vinhnx/VTCode/main/scripts/install.sh | bash
该脚本会自动安装 ripgrep 和 ast-grep（macOS/Linux）。安装完成后验证：
vtcode --version
Homebrew（macOS/Linux）
brew tap vinhnx/tap
brew install vinhnx/tap/vtcode
Rust/Cargo（需 Rust 1.98.1+，edition 2024）
cargo install vtcode
⚠️ Windows artifact 为尽力而为，可能落后于 macOS/Linux 版本。
四、核心配置与首次运行
初始化项目
cd your/project
vtcode init # 脚手架：生成 vtcode.toml + AGENTS.md，建议 commit 前 review
添加模型 Provider 凭证
vtcode secret add openai # 存到 OS keychain
# 支持：openai / anthropic / gemini / ollama / local 等，详见 Provider guides
凭证也可来自环境变量或 .env 文件。严禁把 API key 写入 vtcode.toml。
# 使用环境变量时，确保 .env 包含：
# OPENAI_API_KEY=sk-...
OAuth 认证（可选）
- ChatGPT OAuth：复用 Codex CLI 的公开客户端身份（非官方兼容流程），建议优先使用自己的 OpenAI API key。
- GitHub Copilot：使用官方 copilot CLI。
五、核心用法
交互式 TUI（最常用）
vtcode # 在当前项目目录打开交互式 TUI
进入后输入任务，例如：
Explain how this project handles authentication
Agent 会调用只读工具调查，完成后展示 diff 和测试结果，用户 review 后决定是否 commit。
交互模式控制命令：
| 命令 | 说明 |
|---|---|
/plan |
切换到只读 planning 模式，先讨论再动手 |
/mode build |
切换到写模式（plan 审批后的下一步） |
/mode auto |
完全自动化，无需每次确认 |
/explain |
查看任务结果、变更、决策记录 |
/explain --details |
添加详细证据 |
/explain diagram |
显示执行关系图 |
/explain --export html |
导出独立 HTML 报告 |
/continue |
恢复上一个会话 |
/exit |
退出 TUI |
Headless 执行（无 TUI）
# 一次性提问，无需会话
vtcode ask "explain Rc vs Arc"
# 执行完整任务（需 full_auto 权限）
vtcode exec "refactor main.rs"
# 继续上一个 headless 任务
vtcode exec resume --last "continue the refactor"
# Agent review 未提交的变更
vtcode review
⚠️
exec模式需要automation.full_auto配置 +VTCODE_TRUST_WORKSPACE=full-auto环境变量。非 TTY 运行默认拒绝 autonomous exec。
定期任务（Scheduled Tasks）
# 每周一 09:00 依赖审计
vtcode schedule create --name "weekly-dep-audit" \
--cron "0 9 * * 1" \
--prompt "Check for outdated dependencies and report known vulnerabilities"
# 继续最近的会话
vtcode continue
# 按 session ID 恢复
vtcode continue --session-id <id>
# 查看执行轨迹
vtcode trajectory
MCP 集成
VTCode 支持连接外部 MCP 服务器，扩展工具集。在 vtcode.toml 中配置：
[mcp]
enabled = true
servers = ["filesystem", "memory"]
# 或指定 MCP 服务器路径
[[mcp.servers]]
name = "my-server"
command = ["npx", "-y", "@my/mcp-server"]
Skills（可复用 Prompt 包）
# 查看可用 Skills
vtcode skills list
# 加载指定 Skill
vtcode skill load <skill-name>
与 Zed 编辑器集成（ACP）
# 从 Zed 编辑器驱动 VT Code
vtcode acp --zed
WebMCP（浏览器编辑器桥接）
# 配对 TUI 和浏览器编辑器
/webmcp pair <origin>
# 托管地址：https://vtcode.vinhnx.chatgpt.site/
六、Planning 工作流详解（重点推荐）
VTCode 区别于其他 Agent 的核心特性之一是 Planning-first：
- Plan Mode 是只读的：planning agent 只能调用 read-only 工具（grep、cat、cargo check 等），无法写入文件或运行 cargo build。即使你在配置里给了
bash权限，mutating 工具也会被 dispatch gate 硬拦截。 - Shell 命令白名单：允许
rg、cargo check、git diff等只读命令；拒绝sed -i、重定向>、动态 find predicate 等。 - 产出
<proposed_plan>：Agent 讨论完成后输出结构化计划，用户审批后 runtime 自动创建task_tracker并交给 build agent 执行。 - Blocked Call 恢复：连续被拦截的工具调用有上限（cap=3 时 Plan Mode 允许 12 次非连续拦截），超时后强制 checkpoint，用户可
vtcode --resume <archive-id>恢复。
用户输入 → Plan Agent（只读调查）→ 产出 proposed_plan → 用户审批
→ Build Agent（可写）→ 执行 + task_tracker → Review
七、典型适用场景
| 场景 | 推荐用法 |
|---|---|
| 快速了解陌生代码库 | vtcode ask "how does auth work?" |
| 重构大任务 | 先 /plan，审批后再 /mode build |
| 定期代码审查 | vtcode schedule create --cron "..." + review |
| Headless 批量任务 | CI/CD 中 vtcode exec "run tests" |
| 连接 MCP 工具（数据库、API） | 配置 vtcode.toml 的 [[mcp.servers]] |
| 多会话追踪 | vtcode continue --session-id <id> |
| 与 Zed 编辑器协作 | ACP bridge |
八、坑与注意
- API Key 安全：永远不要把 key 写入
vtcode.toml；用vtcode secret add或环境变量。 - Windows 支持：官方说 best-effort，生产环境建议用 macOS/Linux。
- full_auto 权限风险：
VTCODE_TRUST_WORKSPACE=full-auto允许 Agent 执行任意命令，仅限可信代码库。 - Rust 1.98.1+ 要求：使用 Cargo 安装需要 Rust edition 2024，旧版本不兼容。
- Plan Mode 不是完全隔离：Shell 权限给的是
bash但 dispatch gate 会硬拦截 mutating 工具；不要误以为给了 bash 就等于有写权限。 - session archive 依赖：resume 功能依赖 session archive 持久化，禁用 history 时 resume 命令不出现。
- OAuth 非官方：ChatGPT OAuth 复用 Codex CLI 身份，属于非官方兼容流，稳定性不确定。
- compaction 机制：长任务会自动 compaction 以节省 context，compaction 日志在
.vtcode/目录可查。 - MCP 服务器版本：VTCode 配置格式与 MCP spec 对齐，但 MCP 生态工具版本各异，建议用 MCP Inspector 先验证连通性。
九、与同类对比
| 工具 | 语言 | 闭源/开源 | Planning | MCP | Headless | 特色 |
|---|---|---|---|---|---|---|
| VTCode | Rust | 开源 | ✅ 只读 Plan-first | ✅ | ✅ | 完全可审计的沙箱 |
| Codex CLI | Go | 闭源 | ❌ | ❌ | 有限 | OpenAI 官方 |
| Copilot CLI | TypeScript | 闭源 | ❌ | ❌ | ❌ | GitHub 官方集成 |
| Claude Code | Node | 闭源 | ❌ | ❌ | ✅ | Anthropic 官方 |
| Open Hands | Python | 开源 | ✅ | ✅ | ✅ | Agent 记忆更强 |
| SWE-agent | Python | 开源 | ❌ | ✅ | ✅ | 学术 benchmark 导向 |
VTCode 的核心优势：开源 + Rust 性能 + Planning-first 安全模型 + MCP 生态集成，适合对工具可审计性有要求的生产级用户。
十、一句话推荐结论
VTCode 是目前最值得关注的开源终端编程 Agent——Rust 实现保证了性能上限，Planning-first 设计从源头减少 Agent 乱改代码的风险，加上 MCP 集成和完整的可审计安全模型，适合追求"安全 + 高效 + 开源"平衡的工程师。