开始
安装与首次启动
一条命令装好 heng-agent，配一个模型服务，然后在项目目录里启动它。第一次运行会自动找你电脑上现成的密钥，找到了一键就能用。
- 预计用时
- 约 5 分钟
- 适用版本
- v0.5.0 及以上
- 需要准备
- 一个服务商的 API 密钥
一条命令安装
打开终端，按你的系统运行下面这条命令。没有 uv（Python 的包管理工具）会先自动装；pypi.org 连不上会自动改用清华镜像；已经装过就升级到最新版。
PS> irm https://gitee.com/bkywksj/heng-agent/raw/master/install.ps1 | iex在项目目录里启动
进到你要干活的项目目录，直接运行 heng-agent。它能读写的文件只限这个目录，越界一律拒绝。
$ cd D:\code\my-app $ heng-agent
不想先 cd，也可以用 heng-agent --workdir 目录 指定工作目录。
第一次运行：配一个模型服务
还没有配置时，heng-agent 会先带你配一个模型服务，大约 1 分钟。它会自动找电脑上现成的配置：环境变量里各家的密钥（如 DEEPSEEK_API_KEY）、Claude Code 里配过的中转站、Codex 的 ~/.codex/config.toml 里用 API key 的服务商与 codex login --api-key 存的密钥。找到了选一下就能用。
╭──────────────────────────────────────────────────────────────╮ │ 第一次使用 heng-agent：先配一个模型服务（大约 1 分钟），配好就能开始干活。 │ 方向键选、Enter 确定；任何一步按 ESC 跳过，之后随时输入 /config provider 再配 ╰──────────────────────────────────────────────────────────────╯ 在你的电脑上找到了现成的配置，可以直接用： 怎么配置模型服务？ ❯ DeepSeek（Anthropic 兼容接口） 环境变量 DEEPSEEK_API_KEY 手动配置 选服务商（DeepSeek、Kimi、通义、GLM、Claude……）、填密钥 以后再说 之后随时输入 /config provider ✓ 已保存并设为默认：deepseek 测试一下连接…… ✓ 连接成功 模型回复：好的
没有找到现成配置就选「手动配置」：选服务商、粘贴密钥（输入时不显示），它会向服务商取模型列表让你挑。连接测试失败会说清楚原因：密钥不对、余额不足，还是连不上。暂时不想配就按 ESC 跳过，之后随时输入 /config provider。
看懂欢迎页
配好后每次启动都会先显示欢迎页。动手之前看一眼这三处，确认它在对的地方、用对的模型：
- 目录：它只能读写这个目录里的文件。不对就退出（Ctrl+D 或
/exit），换到项目目录再启动，或用--workdir指定。 - 模型：服务商 · 模型名，下一行是地址与协议。随时
/provider 名字切服务商、/model选模型。 - 权限：默认「手动确认」（
ask），改文件、跑命令前都会问你。Shift+Tab 切换模式，输入框边框颜色跟着变。
派第一个任务
直接用中文说要做什么，Enter 发送。@文件名 附上文件内容，!命令 直接执行命令；换行用 Shift+Enter（其他终端里用 Ctrl+J）。
- 你的提问：左侧一根青色竖条，和回复分得开。
- 它做了什么：每一步一行「● 动作 参数」，下一行是结果摘要；读文件、找文件这类只读操作直接做。
- 回复：顶格显示，拖选复制不会带上缩进；
/copy复制整条，回复里有代码块时可以只复制其中一段。 - 这一问的小结：几点提的、用了多久、几轮、输入输出多少 token。
读文件、搜代码不会打扰你；第一次要运行 pytest 时会弹出确认框，选「这次允许」就行。确认框的四个选项见 权限模式与规则，一次完整的任务怎么走见 派第一个任务。
做完是这样
终端里能看到欢迎页、底部状态栏显示权限模式与服务商、模型，问一句话有回复。之后升级运行 heng-agent upgrade（Windows 上它会开个新窗口，等 heng-agent 退出后再升级）；有新版本时欢迎页会提示。