本文说明 IaC Code 的公共安装和配置流程,包括 Python 环境、Windows Git Bash、可选依赖、模型服务和阿里云身份。完成后,REPL、Headless、Web 和协议服务可以复用同一份配置。
前提条件
项目 | 要求 |
Python | 3.10 或更高版本。建议使用与项目隔离的虚拟环境。 |
操作系统 | macOS、Linux 或 Windows。 |
大模型服务 | 一个 IaC Code 支持的大模型服务及其访问凭据。 |
阿里云身份 | 本地方案设计或文件处理时可选;查询或管理云资源时需要。 |
Windows 附加要求 | Git for Windows 提供工具执行所需的 Git Bash。 |
安装软件包时不需要提供模型或阿里云凭据。示例中不要填写真实 API Key、AccessKey Secret 或访问令牌。
安装基础包
运行以下命令:
python -m pip install iac-code
验证命令和版本:
iac-code --help
iac-code --version
预期结果:终端显示 IaC Code 的命令帮助和当前版本号。基础包支持 REPL、Headless 和 ACP Stdio 等核心能力。
在 Windows 上安装 Git Bash
如果尚未安装 Git for Windows,请在 PowerShell 或命令提示符中运行:
iac-code install-git-bash
该命令仅在 Windows 上提供,会通过 npmmirror 下载安装程序。按界面提示完成安装并允许必要的用户账户控制(UAC)操作。安装完成后,命令会重新检测 bash.exe 并输出路径。
快捷安装受企业网络策略限制时,可以改用:
winget install --id Git.Git -e --source winget
也可以手动安装 Git for Windows。
安装可选能力
基础包之外的运行方式按需安装:
可选能力 | 安装命令 |
Web 版 |
|
A2A Server |
|
AG-UI Server |
|
Web、A2A 和 AG-UI |
|
如果在缺少可选依赖时启动对应命令,IaC Code 会提示需要安装的 Extra。
配置模型和阿里云身份
模型配置用于访问大模型服务。阿里云身份用于查询云产品、规格、资源栈和账号内资源, 以及执行部署、更新或删除。
选择配置入口
配置入口 | 操作方式 | 适用场景 |
REPL | 运行 | 已在终端工作,或准备使用 Headless、ACP、AG-UI、A2A |
Web | 打开“设置 > 模型”和“设置 > 云凭证” | 希望在浏览器中完成可视化配置 |
两种入口写入相同的配置目录,不需要重复设置。Web 表单的完整操作请参见 使用 Web 版,REPL 的认证流程请参见 使用 REPL 交互模式。
选择阿里云认证方式
根据运行环境选择最小权限的认证方式:
认证方式 | 适用场景 |
OAuth 浏览器登录 | 本地交互使用,希望避免手动管理长期 AccessKey。 |
ECS RAM Role | IaC Code 运行在 ECS 实例上。 |
STS Token | 自动化系统提供短期凭据。 |
RAM 角色 | 使用一个身份扮演目标 RAM 角色。 |
AccessKey | 其他方式不适用时使用最小权限 RAM 用户的 AccessKey。 |
不要使用主账号长期 AccessKey。创建、更新和删除云资源所需权限应与只读查询权限分开管理。
配置文件和安全
默认配置目录为:
~/.iac-code/
├── .credentials.yml # 大模型服务凭据
├── .cloud-credentials.yml # 阿里云身份凭据
└── settings.yml # 运行设置
通过环境变量 IAC_CODE_CONFIG_DIR 可以修改配置目录。其下的项目、会话、Skill、MCP、记忆和日志等运行数据也会随之迁移到新目录。
请遵循以下安全要求:
不把凭据文件提交到代码仓库,不在命令、提示词或日志中打印真实密钥。
限制配置目录和凭据文件的操作系统访问权限。
自动化环境通过 Secret 管理服务注入短期凭据,不把密钥写入脚本。
定期轮换凭据,并及时撤销不再使用的身份和权限。
升级和卸载
升级 IaC Code:
python -m pip install --upgrade iac-code
卸载 IaC Code:
python -m pip uninstall iac-code
卸载软件包不会主动删除 ~/.iac-code/ 下的配置和会话。清理目录前,请确认没有需要保留的凭据、会话或项目记录。
常见问题
找不到 iac-code 命令
确认安装命令使用的 Python 与当前终端环境一致,并检查 Python 脚本目录是否在 PATH 中。使用虚拟环境时,先激活环境,再运行 iac-code --help。
Windows 仍然提示找不到 Git Bash
先运行 iac-code install-git-bash。如果 Git for Windows 已安装但没有被识别,请在
PowerShell 中设置:
$env:IAC_CODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"
需要长期生效时,将相同配置保存为 Windows 用户环境变量。
模型认证失败
确认模型服务商、模型名、API Base URL 和 API Key 相互匹配,并检查企业代理和目标服务连通性。Web 用户还需确认已经将保存的配置设为当前模型。
阿里云操作提示无权限
确认认证方式、凭据有效期和地域正确,并为身份授予任务所需的最小 RAM 权限。不要通过硬编码主账号 AccessKey 绕过权限问题。