一、Codex 是什么？

Codex CLI 是 OpenAI 提供的一个终端编码助手。它可以运行在本地电脑或服务器终端中，读取当前目录下的项目代码，帮助我们分析项目结构、修改代码、执行命令、排查报错、生成脚本、做代码审查等。官方说明中提到，Codex CLI 可以在终端里读取、修改和运行当前目录中的代码，并且支持 Linux、macOS、Windows。(OpenAI开发者)

简单理解：

Codex CLI = 一个能在终端里帮你写代码、看代码、执行命令的 AI 编程助手

它不是把大模型部署到你的服务器上，大模型推理主要还是走 OpenAI 云端。你的服务器主要负责放代码、执行命令、运行项目、打包构建。

---

二、适合我的使用场景

我服务器是 Linux 系统，并且已经通过宝塔安装了 Docker。我的目标不是让 Codex 替代宝塔，也不是让 Codex 托管项目，而是让 Codex 在服务器上帮我做这些事情：

1. 阅读项目代码
2. 修改 Spring Boot 后端代码
3. 修改 Vue3 / uni-app 前端代码
4. 分析日志报错
5. 编写 SQL、脚本、docker-compose.yml
6. 执行 mvn package、npm run build、docker compose 等命令
7. 远程协助我开发项目

所以最适合的方式是：

Codex 安装在服务器宿主机
业务项目继续用 Docker 或宝塔部署
代码统一放到一个工作目录
通过 SSH 或宝塔终端进入目录后启动 Codex

---

三、服务器配置要求

Codex CLI 本身对服务器要求不高，因为它不是在服务器本地跑大模型。真正消耗服务器资源的是项目运行、Docker 容器、前端打包、Java 编译、数据库等。

建议配置：

轻量使用：2核4G
日常开发：4核8G
更舒服：4核16G 或以上

基础环境建议：

系统：Ubuntu / Debian / CentOS / Rocky Linux 等
Node.js：建议 22+
Git：建议安装
网络：服务器需要能访问 OpenAI 相关服务

官方 npm 安装方式是 npm i -g @openai/codex，首次运行 codex 后需要登录 ChatGPT 账号或配置 API Key。(OpenAI开发者)

---

四、安装前检查环境

先进入服务器：

ssh root@你的服务器IP

检查系统信息：

uname -a

检查 CPU：

lscpu

检查内存：

free -h

检查磁盘：

df -h

检查 Git：

git --version

检查 Node.js：

node -v
npm -v

如果没有 Node.js，建议先安装 Node.js 22。

---

五、安装 Node.js 22

方式一：宝塔面板安装

如果服务器有宝塔，可以在宝塔的软件商店里安装 Node.js 管理器，然后安装 Node.js 22。

安装完成后，在终端验证：

node -v
npm -v

方式二：终端安装 Node.js 22

Ubuntu / Debian 可以参考：

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs

验证：

node -v
npm -v

---

六、安装 Codex CLI

官方推荐的 npm 安装命令是：(OpenAI开发者)

npm i -g @openai/codex

安装完成后检查版本：

codex --version

查看帮助：

codex --help

升级 Codex：

npm i -g @openai/codex@latest

官方也说明 Codex CLI 会持续发布新版本，npm 安装的升级方式就是重新安装 latest 版本。(OpenAI开发者)

---

七、首次登录 Codex

执行：

codex

第一次运行时，会提示登录。官方说明 Codex 支持使用 ChatGPT 账号登录，也可以使用 API Key。(OpenAI开发者)

如果服务器没有浏览器界面，可能需要复制终端里显示的登录链接，到自己电脑浏览器打开完成授权。

登录完成后，Codex 会在服务器上保存认证信息。后续再次执行 codex 就可以直接进入交互界面。

---

八、推荐的代码目录结构

不建议直接让 Codex 在生产目录里乱改。推荐单独建一个工作区：

mkdir -p /www/codex-workspace
cd /www/codex-workspace

目录结构可以这样设计：

/www/codex-workspace
├── youtuantuan-api        # Spring Boot 后端
├── youtuantuan-admin      # Vue3 后台
├── youtuantuan-app        # uni-app 小程序
├── fastgpt-demo
└── test-project

拉取项目：

cd /www/codex-workspace
git clone 你的项目仓库地址
cd 你的项目目录

建议先创建一个测试分支：

git checkout -b dev_codex_test

然后启动 Codex：

codex

---

九、Codex 的基本使用方式

1. 进入当前目录启动 Codex

cd /www/codex-workspace/你的项目
codex

进入后可以直接输入：

先阅读这个项目结构，告诉我后端、前端分别怎么启动，不要修改代码。

2. 带提示词直接启动

官方支持在命令后面直接带初始提示词。(OpenAI开发者)

codex "解释一下这个项目的目录结构"

3. 指定工作目录启动

官方 --cd / -C 参数可以设置 Codex 的工作目录。(OpenAI开发者)

codex --cd /www/codex-workspace/你的项目

或者：

codex -C /www/codex-workspace/你的项目

4. 附带图片输入

官方支持通过 --image / -i 给 Codex 附加图片，比如截图、设计稿等。(OpenAI开发者)

codex -i ./error.png "根据这张截图帮我分析前端报错"

---

十、常用命令整理

1. 基础命令

命令	作用
codex	启动 Codex 终端交互界面
codex "提示词"	启动 Codex 并直接发送一个任务
codex --help	查看帮助
codex --version	查看版本
codex login	登录 Codex
codex logout	退出登录
codex resume	恢复之前的会话
codex exec	非交互模式执行任务
codex e	codex exec 的简写
codex completion	生成 Shell 自动补全脚本
codex mcp	管理 MCP 工具
codex features	查看或管理功能开关

官方命令总览中列出了 codex、codex app、codex app-server、codex apply、codex cloud、codex completion、codex exec、codex login、codex logout、codex mcp 等命令。(OpenAI开发者)

---

十一、Codex 常用参数

1. 指定目录

codex --cd /www/codex-workspace/项目名

或者：

codex -C /www/codex-workspace/项目名

作用：让 Codex 在指定目录中工作。官方说明 --cd / -C 可以在处理请求前设置工作目录。(OpenAI开发者)

---

2. 指定模型

codex --model gpt-5.4

或者：

codex -m gpt-5.4

作用：覆盖配置文件里的默认模型。官方参数说明中，--model / -m 用于指定模型。(OpenAI开发者)

---

3. 指定审批模式

codex --ask-for-approval on-request

常见值：

untrusted
on-request
never

作用：控制 Codex 执行命令或修改文件时是否需要人工确认。官方说明 --ask-for-approval / -a 用于控制 Codex 何时暂停并请求人工确认。(OpenAI开发者)

日常建议：

codex -a on-request

不要随便用：

codex -a never

因为这会让 Codex 更少请求确认，风险更高。

---

4. 指定沙箱权限

codex --sandbox workspace-write

常见值：

read-only
workspace-write
danger-full-access

作用：限制 Codex 生成的 shell 命令能访问和修改哪些范围。官方说明 --sandbox / -s 用于选择模型生成命令的沙箱策略。(OpenAI开发者)

建议：

codex --sandbox workspace-write

谨慎使用：

codex --sandbox danger-full-access

---

5. 允许额外目录写入

codex --add-dir /www/wwwroot

作用：默认情况下 Codex 主要操作当前工作目录，如果要让它额外访问或写入其他目录，可以使用 --add-dir。官方说明 --add-dir 可以给主工作区之外的目录授予写入访问权限。(OpenAI开发者)

例如：

codex \
  --cd /www/codex-workspace/youtuantuan-admin \
  --add-dir /www/wwwroot/youtuantuan-admin

---

6. 开启网页搜索

codex --search

作用：让 Codex 在任务中使用实时 Web 搜索。官方参数说明中，--search 用于启用 live web search。(OpenAI开发者)

---

7. 危险模式，不建议随便用

codex --dangerously-bypass-approvals-and-sandbox

或者：

codex --yolo

官方明确说明，这个参数会绕过审批和沙箱，只应该在外部已经加固的隔离环境中使用。(OpenAI开发者)

日常服务器不建议使用，尤其不要在生产服务器上随便开。

---

十二、交互模式中的斜杠命令

Codex 进入交互界面后，可以输入 / 打开斜杠命令菜单。官方说明斜杠命令可以用来切换模型、调整权限、总结长会话、查看状态等。(OpenAI开发者)

常用命令如下：

命令	作用
/status	查看当前模型、权限、上下文、工作目录等状态
/model	切换模型
/permissions	调整 Codex 可以自动做什么
/plan	进入计划模式，让 Codex 先出方案
/diff	查看当前 Git 变更
/review	让 Codex 审查当前改动
/init	生成 AGENTS.md 项目说明文件
/clear	清空当前会话并开始新对话
/compact	压缩总结当前长会话，节省上下文
/resume	恢复之前的会话
/mention	指定文件或目录给 Codex 查看
/mcp	查看 MCP 工具
/theme	切换终端主题
/copy	复制最新输出
/quit	退出 Codex
/exit	退出 Codex

官方斜杠命令文档中列出了 /permissions、/ide、/clear、/compact、/diff、/init、/logout、/mcp、/mention、/model、/plan、/review、/status、/theme、/quit、/exit 等命令。(OpenAI开发者)

---

十三、非交互模式：codex exec

如果不想进入完整交互界面，也可以使用非交互模式：

codex exec "帮我检查这个项目有没有明显的启动问题"

简写：

codex e "帮我检查这个项目有没有明显的启动问题"

官方说明 codex exec，也就是 codex e，适合脚本化或 CI 风格的任务，可以非交互运行。(OpenAI开发者)

指定目录执行：

codex exec --cd /www/codex-workspace/你的项目 "阅读项目结构并总结启动方式"

允许在非 Git 目录执行：

codex exec --skip-git-repo-check "分析当前目录文件"

输出 JSONL：

codex exec --json "检查项目问题"

恢复上次非交互任务：

codex exec resume --last "继续刚才的任务"

官方说明 codex exec resume 可以通过会话 ID 或 --last 恢复最近的非交互任务。(OpenAI开发者)

---

十四、服务器远程开发推荐流程

第一步：进入服务器

ssh root@你的服务器IP

第二步：进入项目目录

cd /www/codex-workspace/你的项目

第三步：创建开发分支

git checkout -b dev_codex_test

第四步：启动 Codex

codex

第五步：先让 Codex 只读分析

先阅读这个项目结构，告诉我后端、前端、部署脚本分别在哪里，不要修改任何代码。

第六步：让 Codex 制定修改方案

我要新增一个订单统计接口。先分析现有代码结构，给我一个修改方案，不要直接改代码。

第七步：确认后再让它改

按你刚才的方案修改代码，保持现有代码风格，改完后执行编译检查。

第八步：查看 Git diff

在 Codex 里面可以输入：

/diff

或者退出后手动查看：

git diff

第九步：测试和提交

mvn clean package -DskipTests
git status
git add .
git commit -m "feat: 新增订单统计接口"

---

十五、Java Spring Boot 项目怎么运行？

如果是 Spring Boot 项目：

cd /www/codex-workspace/youtuantuan-api
mvn clean package -DskipTests
java -jar target/xxx.jar --server.port=9090

如果项目本来就是 Docker 部署：

docker compose up -d --build

查看日志：

docker logs -f 容器名

或者：

tail -f logs/myapp.log

可以让 Codex 帮忙：

帮我执行 mvn clean package -DskipTests，如果编译失败，分析原因并修复。

---

十六、Vue3 项目怎么运行？

如果是 Vue3 后台项目：

cd /www/codex-workspace/youtuantuan-admin
npm install
npm run build

打包后一般生成：

dist/

部署到宝塔网站目录：

cp -r dist/* /www/wwwroot/admin.xxx.com/

可以让 Codex 帮忙：

这是 Vue3 项目，使用 script setup 写法。帮我优化这个页面样式，不要改接口字段，不要删除原有功能。

---

十七、uni-app 小程序项目怎么处理？

uni-app 项目可以让 Codex 帮忙改代码、改样式、改组件、改接口逻辑。

但是小程序上传体验版、提交审核，通常还是本地用 HBuilderX 或微信开发者工具更方便。

可以让 Codex 做：

这是 uni-app 小程序项目，帮我优化首页 UI，只改样式和布局，不改接口，不新增功能。

如果项目支持 CLI 打包，可以执行：

npm install
npm run build:mp-weixin

具体命令以 package.json 为准。

---

十八、建议写一个 AGENTS.md

Codex 支持通过 /init 生成 AGENTS.md 项目说明文件。官方斜杠命令说明中，/init 用于在当前目录生成 AGENTS.md 脚手架。(OpenAI开发者)

建议在项目根目录放一个 AGENTS.md，告诉 Codex 项目规则。

示例：

# 项目说明

这是一个 Spring Boot + Vue3 + uni-app 项目。

## 技术栈

- 后端：Java 17、Spring Boot、MyBatis-Plus、MySQL、Redis
- 前端后台：Vue3，使用 `<script setup>`
- 小程序：uni-app
- 部署：Linux 宝塔 + Docker

## 开发要求

1. 不要随意修改数据库表结构。
2. 不要删除已有接口字段。
3. 前端使用 Vue3 `<script setup>` 写法。
4. 后端保持现有 Controller、Service、Mapper 分层结构。
5. 修改前先说明方案。
6. 修改后执行编译检查。
7. 涉及生产配置时必须先提示风险。

以后 Codex 进入项目后，就能更好地遵守你的项目习惯。

---

十九、配合 tmux 防止断线

服务器 SSH 连接可能断开，建议用 tmux。

安装：

apt install -y tmux

创建会话：

tmux new -s codex

进入项目：

cd /www/codex-workspace/你的项目
codex

如果 SSH 断开，重新连接服务器后：

tmux attach -t codex

这样可以继续之前的 Codex 会话。

---

二十、安全注意事项

1. 不要直接在生产目录乱改

推荐：

开发目录：/www/codex-workspace
生产目录：/www/wwwroot 或 /www/dockers

先在开发目录改，测试通过后再部署。

2. 不要随便开危险模式

不要轻易使用：

codex --yolo

也不要轻易使用：

codex --dangerously-bypass-approvals-and-sandbox

官方说明这个参数会绕过审批和沙箱，只适合外部已经加固的隔离环境。(OpenAI开发者)

3. 重要操作先让 Codex 出方案

比如：

你先分析问题并给出方案，不要直接修改代码。

4. 让 Codex 改完后必须看 diff

git diff

或者在 Codex 中输入：

/diff

5. 不要把 Codex 服务端口暴露到公网

如果使用 codex app-server 或远程连接模式，要特别注意安全。官方文档中提到 app-server 可以通过 WebSocket 连接，并建议非本地客户端使用认证和 TLS。(OpenAI开发者)

---

二十一、我常用的 Codex 提示词模板

1. 只读分析项目

先阅读当前项目结构，告诉我这个项目的技术栈、启动方式、主要目录作用。不要修改任何代码。

2. 分析报错

我现在遇到这个报错，请结合当前项目代码分析原因。先不要修改代码，先告诉我可能原因和排查步骤。

3. 修改后端接口

这是 Spring Boot 项目。帮我新增一个接口，要求保持现有 Controller、Service、Mapper 风格。不要修改已有接口字段。改完后执行 mvn clean package -DskipTests 检查。

4. 修改 Vue3 页面

这是 Vue3 项目，使用 <script setup> 写法。帮我优化当前页面样式，不要改接口，不要删功能，不要改字段名。

5. 修改 uni-app 小程序

这是 uni-app 小程序项目。帮我优化这个页面的 UI，只调整布局和样式，不新增功能，不删除功能，不改变接口字段。

6. Docker 部署排查

帮我检查当前 docker-compose.yml 和容器日志，分析为什么服务启动失败。先给出原因，再给出修改方案。

7. 代码审查

请审查当前 Git 工作区改动，重点检查空指针、事务、并发、SQL 性能、接口兼容性问题。

---

二十二、常见问题

1. Codex 可以直接帮我写完整项目吗？

可以，但建议先限定范围，比如：

服务器配置是 2核4G，不要引入太多中间件。
后端用 Spring Boot + MySQL + Redis。
前端用 Vue3 script setup。
部署方式使用 Docker Compose。

这样 Codex 生成的项目更适合你的服务器。

2. Codex 写的代码一定能运行吗？

不一定。Codex 可以写代码、执行命令、修复错误，但最终还是要编译、测试、看日志。正确流程应该是：

写代码 -> 编译 -> 启动 -> 测试接口 -> 查看日志 -> 修复问题

3. Codex 可以操作 Docker 吗？

如果 Codex 安装在服务器宿主机，并且当前用户有 Docker 权限，就可以执行：

docker ps
docker logs
docker compose up -d

4. Codex 可以替代开发人员吗？

不能完全替代。它更像一个远程开发助手。它能大幅提高写代码、排查问题、生成脚本的效率，但关键设计、业务判断、上线确认仍然需要人来把关。

---

二十三、推荐配图和图片文案

配图 1：Codex 工作原理图

图片内容建议：

一台服务器，中间是 Codex CLI，左边是开发者通过 SSH 连接，右边是项目代码目录、Docker、宝塔、数据库。

图片标题：

图 1：Codex CLI 在服务器中的工作方式

图片说明：

Codex CLI 并不是替代服务器运行环境，而是在终端中读取项目代码、修改文件、执行命令，帮助开发者完成远程开发和排查。

---

配图 2：推荐目录结构图

图片内容建议：

展示 /www/codex-workspace、/www/wwwroot、/www/dockers 三个目录之间的关系。

图片标题：

图 2：Codex 开发目录与生产部署目录分离

图片说明：

建议将 Codex 的开发工作区和正式部署目录分开，避免 AI 修改代码时直接影响线上环境。

---

配图 3：远程开发流程图

图片内容建议：

SSH 登录服务器 -> 进入项目目录 -> 启动 Codex -> 分析项目 -> 修改代码 -> 编译测试 -> Git diff -> 部署上线。

图片标题：

图 3：使用 Codex 进行远程开发的推荐流程

图片说明：

使用 Codex 远程写项目时，建议先分析、再计划、再修改，最后通过编译测试和 Git diff 确认变更。

---

配图 4：Codex 权限安全图

图片内容建议：

三层权限：read-only、workspace-write、danger-full-access，从安全到危险逐级递增。

图片标题：

图 4：Codex 沙箱权限选择建议

图片说明：

日常开发建议使用 workspace-write，生产服务器上不要随意使用 danger-full-access 或 yolo 模式。

---

配图 5：Java / Vue / Docker 运行关系图

图片内容建议：

Codex 修改代码，Java 通过 mvn package 打包，Vue 通过 npm run build 打包，Docker 通过 docker compose 启动服务。

图片标题：

图 5：Codex 负责写代码，运行仍由项目环境完成

图片说明：

Codex 是开发助手，不是项目运行容器。Java、Vue、Docker、Nginx、MySQL 等仍然按照原来的方式运行。

---

二十四、总结

Codex CLI 很适合安装在服务器终端中，用来做远程开发、代码分析、问题排查和自动化修改。

我的推荐方案是：

1. Codex 直接安装在服务器宿主机
2. 代码统一放在 /www/codex-workspace
3. 项目继续用宝塔或 Docker 部署
4. SSH + tmux 远程使用 Codex
5. 修改前先让 Codex 出方案
6. 修改后必须看 git diff 和执行编译测试
7. 不要随便使用 yolo 或 danger-full-access

一句话理解：

Codex 负责帮我写代码和执行命令，服务器负责真正运行项目。

这样既能远程让 AI 帮我开发项目，又能尽量保证服务器和线上服务安全。