Plandex 快速上手指南从零安装、托管选型到 REPL 实战【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandexPlandex 是一款面向大型项目与真实任务设计的开源 AI 编码代理AI coding agent采用终端 CLI REPL 的交互方式能够在多步骤、跨数十个文件的任务中完成规划、实现、执行命令与自动调试。本文基于官方快速入门文档展开结合本仓库的实际安装脚本、REPL 实现与本地部署配置手把手带你完成从安装、托管方式选型、模型 API Key 配置到在项目目录中启动 REPL 并开始 chat / tell 双模式协作的完整流程读完即可上手第一个真实任务。一、安装 PlandexPlandex CLI 提供一行命令的零依赖安装方式。在终端中执行curl -sL https://plandex.ai/install.sh | bash这条命令会下载并执行仓库中的 安装脚本。从脚本源码可以看到它主要做了以下几件事平台与架构识别根据uname -s判断darwin、linux、freebsd等平台根据uname -m识别amd64/arm64架构版本拉取默认从https://plandex.ai/v2/cli-version.txt获取最新 CLI 版本号也可以通过环境变量PLANDEX_VERSION指定安装特定版本下载与落盘从发布包下载plandex_version_platform_arch.tar.gz并解压安装到/usr/local/bin必要时自动借助sudo创建pdx快捷命令脚本会为plandex二进制创建一个符号链接pdx仅当系统上不存在同名命令时因此安装完成后plandex与pdx等价均可启动 CLI旧版本迁移若检测到已安装 v1.x 版本会将其重命名为plandex1/pdx1后再安装 v2避免相互覆盖。脚本执行成功后即可在任何项目目录中运行plandex或pdx。其他安装方式也可以从 release 页面下载对应平台的二进制并放入PATH手动安装或通过git clone后进入app/cli目录执行go build从源码构建。更多安装选项参见 安装指南。Windows 支持说明Windows 用户需要通过 WSL 使用 Plandex。安装脚本中对CYGWIN*|MINGW*|MSYS*平台会直接提示并退出明确要求使用 WSL 环境Plandex only works correctly in the WSL shell. It doesnt work in the Windows CMD prompt or PowerShell.即Plandex 只在 WSL shell 中正常工作在 Windows CMD 或 PowerShell 中无法运行。请先在 Windows 中安装 WSL再在 WSL 终端中执行上面的安装命令。二、托管方式选型Cloud 与 Self-hosted / Local ModePlandex 采用客户端-服务器架构CLI 需要连接一个后端服务来运行。官方提供了两种托管选项选项说明Plandex Cloud自 2025 年 10 月 3 日起逐步停止服务不再接受新用户。Self-hosted / Local Mode通过 Docker 在本地运行 Plandex 服务端或托管在自己的服务器上使用你自己的 OpenRouter 或其它模型提供商的账号与 API Key按本地模式快速上手文档启动。如果你选择 BYO API Key自带 API Key路线无论 Cloud 还是自托管下一步就是确定要使用的模型提供商。最快的方式是使用 OpenRouter.ai它可以让你用一个账号、一把 API Key 访问包括 Plandex 默认使用的所有模型在内的大量模型当然你也可以选择仓库文档中列出的众多其他提供商例如 OpenAI、Anthropic、Google AI Studio / Vertex AI、Azure、AWS Bedrock、DeepSeek、Perplexity 等。本地模式快速启动自托管本地模式的快速启动步骤详见 本地模式快速上手git clone 仓库地址 cd plandex/app ./start_local.sh启动脚本 会先检查git、docker、docker-compose依赖然后拉取最新服务端镜像并通过 Docker Compose 启动。从 docker-compose.yml 可以看到本地模式会拉起两个容器plandex-postgresPostgreSQL 数据库用于持久化计划、对话、账户等数据数据卷plandex-dbplandex-serverPlandex 服务端监听8099端口并通过LOCAL_MODE1等环境变量启用本地模式。服务端起来后在新终端安装 CLI然后执行plandex sign-in在提示 Use Plandex Cloud or another host? 时选择Local mode host并确认默认主机地址http://localhost:8099。之后在项目目录中运行plandex即可开始使用。升级时只需ctrl-c停止服务端再重新执行./start_local.sh脚本会先拉取最新镜像再启动。三、配置模型 API Key在自托管或 BYO API Key 模式下模型调用凭据通过环境变量注入到 CLI 进程中。官方快速入门推荐优先使用 OpenRouterexport OPENROUTER_API_KEY...你需要先在 OpenRouter 注册账号并生成 API Key然后设置上述环境变量。同样支持其它提供商例如export OPENAI_API_KEY... export ANTHROPIC_API_KEY... export GEMINI_API_KEY...从模型提供商文档还可以了解到几点重要的选择规则直接提供商优先当同一模型可由多个提供商提供时如 OpenAI 模型可通过 OpenAI、Azure、OpenRouter 获取如果同时设置了多个提供商的环境变量Plandex 会优先使用直接提供商。例如同时设置ANTHROPIC_API_KEY与OPENROUTER_API_KEY时Anthropic 模型走 Anthropic 直连 APIOpenRouter 兜底若设置了OPENROUTER_API_KEY且同时使用其他提供商当其他提供商报错时Plandex 会自动**故障转移fail over**到 OpenRouterOpenRouter 自身又会把请求路由到多个上游提供商提供了一层很强的冗余检查可用提供商在 REPL 中执行\providers或在 CLI 中执行plandex providers即可查看当前支持的提供商清单。此外如果你拥有 Claude Pro 或 Max 订阅Plandex 在调用 Anthropic 模型时可以直接使用该订阅首次运行 Plandex 时会询问是否连接订阅详细说明见 Claude 订阅文档该文档位于 docs/docs/models 目录。四、在项目目录中启动 REPL准备项目目录如果你是全新项目先创建一个目录mkdir your-project-dir然后进入项目目录cd your-project-dirPlandex 以当前目录为工作项目所有计划、上下文加载与文件改动都围绕这个目录展开。官方也建议对新项目执行git init初始化仓库——Plandex 不强制要求项目在 git 仓库中但如果使用 git它可以与版本控制很好地集成如自动生成 commit message、可选自动提交等。启动 REPL在项目目录下直接运行plandex或使用简写pdx从 CLI 入口 main.go 可以看到启动时会先检查--help等根级参数并调用checkForUpgrade()进行版本升级检查随后进入命令分发cmd.Execute()日志则会写入~/.plandex/plandex.log使用 lumberjack 滚动日志单文件 10MB、保留 3 份备份、28 天。而 REPL 命令实现 在启动时会依次完成解析认证与组织信息auth.MustResolveAuthWithOrg解析或创建项目lib.MustResolveOrCreateProject加载本地状态lib.LoadState包括当前计划、分支、REPL 模式与历史若当前没有活动计划会自动引导创建新计划支持--no-auto、--basic、--plus、--semi、--full等自动模式参数以及--oss、--strong、--cheap等模型包参数打印欢迎信息包括当前计划表、上下文加载方式、自动模式、模型包等进入交互式提示符基于 go-prompt 实现支持命令与文件路径的模糊补全。REPL 默认的 chat 模式与 tell 模式切换REPL 默认从chat 模式启动——这一点在源码中有明确体现lib/repl.go 中CurrentReplState初始化为Mode: ReplModeChat。chat 模式适合在动手实现之前打磨想法、提问与了解代码库不会改动代码tell 模式⚡️进入详细规划并开始写代码、执行命令的实施模式。官方建议的典型工作流是先用 chat 模式把任务讨论清楚一旦任务明确Plandex 会提示你切换到 tell 模式来制定详细计划并开始编写代码。REPL 内可用\tell简写\t切换到 tell 模式用\chat简写\ch切回 chat 模式。从 repl.go 的executor实现看chat 模式的回复还会被正则匹配扫描一旦检测到模型输出包含切换到 tell 模式 / 开始实现之类的语义如switch to tell mode、start implementation等REPL 会弹出确认提示确认后自动切换并让你选择立即基于当前对话开始实现或再发送一条补充提示后开始。这正好对应官方文档描述的Plandex 会提示你切换到 tell 模式。阅读 REPL 帮助与常用操作进入 REPL 后官方建议先快速浏览一下帮助文本。常用操作包括\help\h查看帮助与全部命令列表\quit\q退出 REPL\multi\m切换多行编辑模式配合\send/\s发送多行提示\run\r按当前模式运行文件前缀加载文件到上下文如src/main.go目录支持-r递归加载以及--map/--tree生成项目地图以\开头的所有 CLI 命令如\load、\models、\set-model、\set-auto、\config等均可在 REPL 内直接使用并支持模糊补全——直接输入命令前缀即可看到候选。欢迎界面还会提示当前上下文模式auto 自动加载 / manual 手动加载、自动模式\set-auto调整以及当前模型包\models查看、\set-model更换。五、从 chat 到 tell 的完整上手路径综合官方文档与源码一次典型的 Plandex 首次使用流程如下安装curl -sL https://plandex.ai/install.sh | bashWSL 用户请先在 WSL shell 中执行选托管新用户使用 Self-hosted / Local ModeDocker 本地运行服务端或自行托管Cloud 已停止接纳新用户配 Keyexport OPENROUTER_API_KEY...或其它提供商的 API Key然后启动 REPL进项目cd your-project-dir必要时git init启动plandex或pdx阅读帮助文本对话澄清在默认的 chat 模式下描述想法、向代码库提问切换实施任务明确后按提示或手动\tell切换到 tell 模式让 Plandex 制定计划并开始编写代码、执行命令、自动调试。Plandex 面向的是跨多步骤、触及数十个文件的大型真实任务基于本项目仓库服务端在 app/serverCLI 在 app/cli共享类型定义在 app/shared你可以继续深入阅读 REPL 参考文档、核心概念-计划、自动模式与自主性 等官方文档逐步掌握从上下文管理、分支版本控制到完全自主执行的高级用法。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plandex 快速上手指南：从零安装、托管选型到 REPL 实战
Plandex 快速上手指南从零安装、托管选型到 REPL 实战【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandexPlandex 是一款面向大型项目与真实任务设计的开源 AI 编码代理AI coding agent采用终端 CLI REPL 的交互方式能够在多步骤、跨数十个文件的任务中完成规划、实现、执行命令与自动调试。本文基于官方快速入门文档展开结合本仓库的实际安装脚本、REPL 实现与本地部署配置手把手带你完成从安装、托管方式选型、模型 API Key 配置到在项目目录中启动 REPL 并开始 chat / tell 双模式协作的完整流程读完即可上手第一个真实任务。一、安装 PlandexPlandex CLI 提供一行命令的零依赖安装方式。在终端中执行curl -sL https://plandex.ai/install.sh | bash这条命令会下载并执行仓库中的 安装脚本。从脚本源码可以看到它主要做了以下几件事平台与架构识别根据uname -s判断darwin、linux、freebsd等平台根据uname -m识别amd64/arm64架构版本拉取默认从https://plandex.ai/v2/cli-version.txt获取最新 CLI 版本号也可以通过环境变量PLANDEX_VERSION指定安装特定版本下载与落盘从发布包下载plandex_version_platform_arch.tar.gz并解压安装到/usr/local/bin必要时自动借助sudo创建pdx快捷命令脚本会为plandex二进制创建一个符号链接pdx仅当系统上不存在同名命令时因此安装完成后plandex与pdx等价均可启动 CLI旧版本迁移若检测到已安装 v1.x 版本会将其重命名为plandex1/pdx1后再安装 v2避免相互覆盖。脚本执行成功后即可在任何项目目录中运行plandex或pdx。其他安装方式也可以从 release 页面下载对应平台的二进制并放入PATH手动安装或通过git clone后进入app/cli目录执行go build从源码构建。更多安装选项参见 安装指南。Windows 支持说明Windows 用户需要通过 WSL 使用 Plandex。安装脚本中对CYGWIN*|MINGW*|MSYS*平台会直接提示并退出明确要求使用 WSL 环境Plandex only works correctly in the WSL shell. It doesnt work in the Windows CMD prompt or PowerShell.即Plandex 只在 WSL shell 中正常工作在 Windows CMD 或 PowerShell 中无法运行。请先在 Windows 中安装 WSL再在 WSL 终端中执行上面的安装命令。二、托管方式选型Cloud 与 Self-hosted / Local ModePlandex 采用客户端-服务器架构CLI 需要连接一个后端服务来运行。官方提供了两种托管选项选项说明Plandex Cloud自 2025 年 10 月 3 日起逐步停止服务不再接受新用户。Self-hosted / Local Mode通过 Docker 在本地运行 Plandex 服务端或托管在自己的服务器上使用你自己的 OpenRouter 或其它模型提供商的账号与 API Key按本地模式快速上手文档启动。如果你选择 BYO API Key自带 API Key路线无论 Cloud 还是自托管下一步就是确定要使用的模型提供商。最快的方式是使用 OpenRouter.ai它可以让你用一个账号、一把 API Key 访问包括 Plandex 默认使用的所有模型在内的大量模型当然你也可以选择仓库文档中列出的众多其他提供商例如 OpenAI、Anthropic、Google AI Studio / Vertex AI、Azure、AWS Bedrock、DeepSeek、Perplexity 等。本地模式快速启动自托管本地模式的快速启动步骤详见 本地模式快速上手git clone 仓库地址 cd plandex/app ./start_local.sh启动脚本 会先检查git、docker、docker-compose依赖然后拉取最新服务端镜像并通过 Docker Compose 启动。从 docker-compose.yml 可以看到本地模式会拉起两个容器plandex-postgresPostgreSQL 数据库用于持久化计划、对话、账户等数据数据卷plandex-dbplandex-serverPlandex 服务端监听8099端口并通过LOCAL_MODE1等环境变量启用本地模式。服务端起来后在新终端安装 CLI然后执行plandex sign-in在提示 Use Plandex Cloud or another host? 时选择Local mode host并确认默认主机地址http://localhost:8099。之后在项目目录中运行plandex即可开始使用。升级时只需ctrl-c停止服务端再重新执行./start_local.sh脚本会先拉取最新镜像再启动。三、配置模型 API Key在自托管或 BYO API Key 模式下模型调用凭据通过环境变量注入到 CLI 进程中。官方快速入门推荐优先使用 OpenRouterexport OPENROUTER_API_KEY...你需要先在 OpenRouter 注册账号并生成 API Key然后设置上述环境变量。同样支持其它提供商例如export OPENAI_API_KEY... export ANTHROPIC_API_KEY... export GEMINI_API_KEY...从模型提供商文档还可以了解到几点重要的选择规则直接提供商优先当同一模型可由多个提供商提供时如 OpenAI 模型可通过 OpenAI、Azure、OpenRouter 获取如果同时设置了多个提供商的环境变量Plandex 会优先使用直接提供商。例如同时设置ANTHROPIC_API_KEY与OPENROUTER_API_KEY时Anthropic 模型走 Anthropic 直连 APIOpenRouter 兜底若设置了OPENROUTER_API_KEY且同时使用其他提供商当其他提供商报错时Plandex 会自动**故障转移fail over**到 OpenRouterOpenRouter 自身又会把请求路由到多个上游提供商提供了一层很强的冗余检查可用提供商在 REPL 中执行\providers或在 CLI 中执行plandex providers即可查看当前支持的提供商清单。此外如果你拥有 Claude Pro 或 Max 订阅Plandex 在调用 Anthropic 模型时可以直接使用该订阅首次运行 Plandex 时会询问是否连接订阅详细说明见 Claude 订阅文档该文档位于 docs/docs/models 目录。四、在项目目录中启动 REPL准备项目目录如果你是全新项目先创建一个目录mkdir your-project-dir然后进入项目目录cd your-project-dirPlandex 以当前目录为工作项目所有计划、上下文加载与文件改动都围绕这个目录展开。官方也建议对新项目执行git init初始化仓库——Plandex 不强制要求项目在 git 仓库中但如果使用 git它可以与版本控制很好地集成如自动生成 commit message、可选自动提交等。启动 REPL在项目目录下直接运行plandex或使用简写pdx从 CLI 入口 main.go 可以看到启动时会先检查--help等根级参数并调用checkForUpgrade()进行版本升级检查随后进入命令分发cmd.Execute()日志则会写入~/.plandex/plandex.log使用 lumberjack 滚动日志单文件 10MB、保留 3 份备份、28 天。而 REPL 命令实现 在启动时会依次完成解析认证与组织信息auth.MustResolveAuthWithOrg解析或创建项目lib.MustResolveOrCreateProject加载本地状态lib.LoadState包括当前计划、分支、REPL 模式与历史若当前没有活动计划会自动引导创建新计划支持--no-auto、--basic、--plus、--semi、--full等自动模式参数以及--oss、--strong、--cheap等模型包参数打印欢迎信息包括当前计划表、上下文加载方式、自动模式、模型包等进入交互式提示符基于 go-prompt 实现支持命令与文件路径的模糊补全。REPL 默认的 chat 模式与 tell 模式切换REPL 默认从chat 模式启动——这一点在源码中有明确体现lib/repl.go 中CurrentReplState初始化为Mode: ReplModeChat。chat 模式适合在动手实现之前打磨想法、提问与了解代码库不会改动代码tell 模式⚡️进入详细规划并开始写代码、执行命令的实施模式。官方建议的典型工作流是先用 chat 模式把任务讨论清楚一旦任务明确Plandex 会提示你切换到 tell 模式来制定详细计划并开始编写代码。REPL 内可用\tell简写\t切换到 tell 模式用\chat简写\ch切回 chat 模式。从 repl.go 的executor实现看chat 模式的回复还会被正则匹配扫描一旦检测到模型输出包含切换到 tell 模式 / 开始实现之类的语义如switch to tell mode、start implementation等REPL 会弹出确认提示确认后自动切换并让你选择立即基于当前对话开始实现或再发送一条补充提示后开始。这正好对应官方文档描述的Plandex 会提示你切换到 tell 模式。阅读 REPL 帮助与常用操作进入 REPL 后官方建议先快速浏览一下帮助文本。常用操作包括\help\h查看帮助与全部命令列表\quit\q退出 REPL\multi\m切换多行编辑模式配合\send/\s发送多行提示\run\r按当前模式运行文件前缀加载文件到上下文如src/main.go目录支持-r递归加载以及--map/--tree生成项目地图以\开头的所有 CLI 命令如\load、\models、\set-model、\set-auto、\config等均可在 REPL 内直接使用并支持模糊补全——直接输入命令前缀即可看到候选。欢迎界面还会提示当前上下文模式auto 自动加载 / manual 手动加载、自动模式\set-auto调整以及当前模型包\models查看、\set-model更换。五、从 chat 到 tell 的完整上手路径综合官方文档与源码一次典型的 Plandex 首次使用流程如下安装curl -sL https://plandex.ai/install.sh | bashWSL 用户请先在 WSL shell 中执行选托管新用户使用 Self-hosted / Local ModeDocker 本地运行服务端或自行托管Cloud 已停止接纳新用户配 Keyexport OPENROUTER_API_KEY...或其它提供商的 API Key然后启动 REPL进项目cd your-project-dir必要时git init启动plandex或pdx阅读帮助文本对话澄清在默认的 chat 模式下描述想法、向代码库提问切换实施任务明确后按提示或手动\tell切换到 tell 模式让 Plandex 制定计划并开始编写代码、执行命令、自动调试。Plandex 面向的是跨多步骤、触及数十个文件的大型真实任务基于本项目仓库服务端在 app/serverCLI 在 app/cli共享类型定义在 app/shared你可以继续深入阅读 REPL 参考文档、核心概念-计划、自动模式与自主性 等官方文档逐步掌握从上下文管理、分支版本控制到完全自主执行的高级用法。【免费下载链接】plandexOpen source AI coding agent. Designed for large projects and real world tasks.项目地址: https://gitcode.com/GitHub_Trending/pl/plandex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考