FORGEAX CLI · INSTALLATION

安装指南

选择适合你的安装方式，配置模型凭证，并用一份明确的验收清单确认 CLI 已准备就绪。

环境要求

项	要求
Node.js	≥ 18（发布产物跑 Node；开发仓可用 Bun）
操作系统	macOS / Linux / Windows（WSL 推荐）
网络	访问你的模型 API 端点
可选	sandbox-exec（macOS）或 bwrap（Linux）以启用 --sandbox

安装方式

全局安装（推荐）

npm install -g @forgeax/cli

验证：

which forgeax
forgeax --version
forgeax --help

包名 ≠ 命令名：安装的是 @forgeax/cli，命令是 forgeax。不要用 npm i -g forgeax（该包名未作为本产品入口）。

用 npx 临时跑

npx @forgeax/cli --demo -p "hi"
npx @forgeax/cli -p "列出当前目录的 TypeScript 入口"

从源码 / 公开镜像

git clone --recurse-submodules https://github.com/ForgeaX-Games/forgeax-cli.git
cd forgeax-cli
# 按仓库 README 安装依赖并 build dist 后：
# npm link   # 或 npm pack && npm i -g ./forgeax-cli-*.tgz

公开镜像组织：ForgeaX-Games。

配置凭证

至少配置一组与所选协议匹配的凭证：

# Anthropic Messages 族（默认）
export ANTHROPIC_API_KEY=...
export ANTHROPIC_BASE_URL=...          # 可选

# 或 OpenAI 兼容族
export FORGEAX_PROVIDER_API=openai-compat
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=...

常用模型覆盖：

export FORGEAX_MODEL=claude-opus-4-8   # 或你的部署名
# 等价：forgeax --model <id>

写入用户 settings 亦可（见配置）：

{
  "model": "claude-opus-4-8"
}

路径：~/.forgeax/settings.json。

安装验收清单

在干净环境确认：

# 1) 二进制与 help
forgeax -v
forgeax -h

# 2) 无网络冒烟（不需要 API key）
forgeax --demo -p "hi"

# 3) 真实一轮（需要 key）
forgeax -p "用一句话介绍当前工作目录里有什么"

若第 2 步失败，见故障排除。

升级与卸载

npm update -g @forgeax/cli
npm uninstall -g @forgeax/cli

与 ForgeaX Studio 的关系

	CLI	Studio
入口	forgeax 终端	浏览器 / 桌面 app
内核	本包即运行时	可经 --serve sidecar 接入同一内核
文档	本站 /docs/cli/	Studio 文档

内部内核 id 在 Studio 注册表中可能仍显示为 forgeax-core——这是 KernelId，与 npm 包名 @forgeax/cli 独立，不影响你安装与使用 CLI。