企业官网建设流程全解析

1. 为什么要在本地跑一个 AI 编程助手

1.1 从“云端对话”到“本地常驻”的转变

我最早用 AI 辅助写代码，就是开个网页，把报错贴进去，等它吐一段代码出来，再手动复制回编辑器。这个流程用久了会发现两个问题：一是上下文割裂，它不知道我整个项目的结构，给的代码经常“看着对、跑起来错”；二是网络一波动，思路就断了，尤其是改一个复杂函数改到一半的时候，那种等待的焦躁感非常影响状态。

后来我开始琢磨把 AI 编程助手搬到本地来跑。所谓“本地部署”，说白了就是把模型或者模型的前端服务装在自己的机器上，通过命令行或者本地端口来调用，不再依赖浏览器里那个对话框。这样做的好处很直接：项目文件就在手边，助手可以直接读你的目录、理解你的代码结构；响应走的是本机回环，不受外网波动影响；数据不出本机，处理公司内部代码时心里也踏实。

Codex 这类工具的核心定位，就是“住在你终端里的编程搭子”。它不是一个孤立的模型，而是一套命令行交互层，负责把你的自然语言指令翻译成对代码库的操作，再把结果反馈给你。你要做的，是给它准备好运行环境，让它能稳定地启动、登录、读取项目、执行任务。

1.2 本地部署到底解决了哪些实际痛点

我把本地部署的价值归纳成三条，都是我自己踩过坑之后才真正体会到的。

第一是上下文连续性。云端对话每次都要重新描述项目背景，而本地助手可以直接索引你当前工作目录下的文件。你让它“把 utils 里的日期格式化函数改成支持时区”，它能直接定位到那个文件，而不是让你把代码贴过去。

第二是响应稳定性。这一点在赶进度的时候特别明显。本地服务一旦跑起来，调用走的是本机端口，不会因为外部服务的限流或者网络抖动而中断。对于需要反复试错的重构任务，这种稳定性直接决定了你能否保持心流。

第三是环境可控。你可以决定用哪个模型、走哪个接口、日志打到哪里。比如你想让它接入某个兼容接口的模型服务，只需要改一个配置文件，不用等官方支持。这种自由度是云端产品给不了的。

1.3 这篇文章适合谁来读

如果你满足下面任意一条，这篇内容就是写给你的：

• 写过代码，但对命令行工具链不太熟，想一步步把 AI 助手跑起来；
• 用过云端 AI 编程工具，但被上下文限制或网络问题折腾过；
• 手里有一台配置还行的开发机，想把它变成常驻的编程辅助环境；
• 对 Docker 有耳闻但没实际用过，想借这个机会把容器化部署的流程走一遍。

我会从环境准备讲起，把 Docker 的安装、Codex 的获取、配置文件的写法、常见报错的排查都拆开说。每一步我都会解释“为什么要这么做”，而不是只给命令。你跟着走一遍，应该能得到一个可用的本地 AI 编程助手。

2. 环境准备：Docker 与基础依赖的安装思路

2.1 为什么用 Docker 而不是直接装

很多人第一反应是“我直接下载安装包双击不就行了”，为什么非要绕一层 Docker？我一开始也这么想，直到有一次把本机的依赖版本搞乱了，卸载重装折腾了一下午。Docker 的核心价值在于环境隔离：它把 Codex 运行需要的依赖、库版本、系统工具全部打包在一个容器里，跟你本机的其他环境互不干扰。

打个比方，直接安装就像把新家具直接搬进客厅，跟原有家具挤在一起，风格不搭就全乱套；Docker 相当于在客厅里放了一个独立的玻璃房，家具都摆在玻璃房里，外面该什么样还什么样。哪天不想要了，把玻璃房整个搬走就行，不留痕迹。

对于 Codex 这种需要特定运行时版本的工具，Docker 还有一个好处：跨平台一致性。你在 Windows 上跑通的配置，换到 Linux 服务器上基本能直接复用，不用重新折腾依赖。

2.2 Docker Desktop 的安装与首次启动

Windows 和 macOS 用户装 Docker Desktop 是最省事的路径。去官网下载对应系统的安装包，双击运行，一路下一步。安装完成后启动 Docker Desktop，你会看到右下角托盘区出现一个小鲸鱼图标，等它变成稳定的运行状态，说明 Docker 引擎已经起来了。

这里有个新手最容易卡住的点：Windows 上需要开启虚拟化支持。如果你启动 Docker Desktop 时报了类似“virtualization support not detected”的错，说明主板的虚拟化功能没开。解决办法是进 BIOS，找到 Intel VT-x 或者 AMD-V 选项，设为 Enabled。不同主板菜单名字不一样，一般在 Advanced 或者 CPU Configuration 里面。改完保存重启，再启动 Docker Desktop 就正常了。

macOS 用户相对省心，Apple Silicon 芯片的机器直接装对应版本即可，Docker Desktop 会自动处理架构适配。不过要注意，如果你用的是 M 系列芯片，拉取镜像时尽量选支持 arm64 的版本，否则会走模拟层，性能打折扣。

Linux 用户可以不装 Desktop，直接用命令行安装 Docker Engine。以 Ubuntu 为例，大致流程是更新包索引、安装依赖、添加官方源、安装 docker-ce，然后把当前用户加入 docker 组，避免每次都要 sudo。这套流程网上教程很多，核心是确保docker run hello-world能跑通，说明引擎和权限都没问题。

2.3 验证 Docker 是否可用

装完之后别急着往下走，先做三个检查，确认环境是干净的。

第一个检查是版本。在终端里执行：

docker --version docker compose version

两条命令都应该返回版本号。如果docker compose报错，说明 Compose 插件没装上，需要单独补装。

第二个检查是引擎状态。执行：

docker info

如果能看到 Server 段的详细信息，说明引擎在正常运行。如果报“Cannot connect to the Docker daemon”，说明 Docker 服务没启动，Windows/macOS 上把 Docker Desktop 打开，Linux 上执行sudo systemctl start docker。

第三个检查是网络。执行：

docker pull hello-world docker run hello-world

能拉下来并打印出欢迎信息，说明镜像仓库访问正常。这一步很关键，因为后面拉取 Codex 镜像时如果网络不通，会卡很久。如果你所在的环境访问默认镜像源比较慢，可以配置国内加速地址，在 Docker Desktop 的设置里找到 Docker Engine，往 JSON 配置里加 registry-mirrors 字段即可。

提示：配置镜像加速后记得点 Apply & Restart，让配置生效。改完再用docker info确认一下 Registry Mirrors 里出现了你配置的地址。

3. Codex 的获取与本地部署实操

3.1 获取 Codex 的几种途径

Codex 的获取方式取决于你用的是哪个发行版本。目前常见的有两条路：一条是从官方渠道获取命令行工具，另一条是通过容器镜像的方式运行。我建议优先走容器镜像，因为依赖都被打包好了，省去手动配环境的麻烦。

如果你选择命令行工具的方式，通常是通过包管理器安装。比如 Node 生态下可以用 npm 全局安装，Python 生态下可以用 pip。安装完之后在终端输入对应的命令，能看到帮助信息就说明装上了。这种方式的好处是轻量，坏处是依赖你本机的运行时版本，版本不匹配时容易出各种奇怪的错。

容器方式则是一步到位。你只需要写好一个 compose 文件，把镜像、端口、挂载目录、环境变量配好，一条命令就能起来。我后面会重点讲这种方式，因为它可复现性最强，也最符合“本地部署”的定位。

3.2 用 Docker Compose 编排服务

Docker Compose 的作用是用一个 YAML 文件描述整个服务，包括用哪个镜像、映射哪些端口、挂载哪些目录、传哪些环境变量。相比一长串docker run参数，compose 文件更易读、易改、易版本管理。

下面是我实际用的一份 compose 配置模板，你可以根据自己的情况调整：

services: codex: image: codex-local:latest container_name: codex-assistant restart: unless-stopped ports: - "8787:8787" volumes: - ./workspace:/workspace - ./config:/root/.config/codex environment: - CODEX_API_BASE=http://host.docker.internal:11434/v1 - CODEX_MODEL=local-model - CODEX_LOG_LEVEL=info extra_hosts: - "host.docker.internal:host-gateway"

逐项解释一下。image指定镜像名，如果你是从仓库拉取就写完整的仓库地址。ports把容器内的端口映射到本机，左边是本机端口，右边是容器端口，格式是“本机:容器”。volumes做目录挂载，把本机的 workspace 目录挂进容器，这样助手读写的文件你在本机也能看到；config 目录用来持久化配置和登录状态，容器重启后不用重新登录。

environment里最关键的是 API 地址。如果你在本机另跑了一个模型服务，容器内访问本机需要用host.docker.internal这个特殊域名，Linux 上还要配合extra_hosts把host-gateway映射进去。这一点很多人会忽略，导致容器里连不上本机的模型服务，报连接拒绝。

restart: unless-stopped让容器在异常退出时自动重启，除非你手动停掉它。对于常驻服务来说这个配置很实用，机器重启后容器也会跟着起来。

3.3 启动、登录与首次对话

配置文件写好之后，在同一个目录下执行：

docker compose up -d

-d表示后台运行。执行完用docker compose ps看一下状态，显示 Up 就说明起来了。如果显示 Restarting 或者 Exited，用docker compose logs -f看日志，报错信息一般会直接告诉你缺什么。

接下来是登录。Codex 这类工具通常需要绑定一个账号或者配置一个 API Key。如果是账号登录，容器里会输出一个设备码或者一个本地回调地址，你按提示在浏览器里完成授权即可。如果是 API Key 方式，把 Key 写进环境变量或者配置文件里，重启容器生效。

登录状态会保存在你挂载出来的 config 目录里，所以下次重启容器不用重新登录。这一点在调试阶段特别重要，否则每次改配置都要重新走一遍授权流程，非常折磨人。

首次对话建议从简单任务开始，比如让它读一下 workspace 里的某个文件，总结一下内容。确认它能正常读取文件、正常返回结果，再逐步上强度，让它做代码修改、跑测试之类的操作。

3.4 接入本地模型服务的配置要点

如果你不想依赖外部接口，想完全本地化，可以在本机跑一个模型服务，然后让 Codex 指向它。常见的做法是用兼容 OpenAI 接口格式的服务框架，把模型加载起来，暴露一个/v1的接口。

配置的时候注意三点。第一是接口地址，容器内访问本机要用host.docker.internal，端口要跟你模型服务监听的端口一致。第二是模型名称，要跟你加载的模型标识对上，写错了会报模型不存在。第三是上下文长度，本地模型的上下文窗口通常比云端小，如果 Codex 默认请求的上下文超了，会被截断或者报错，需要在配置里调小最大 token 数。

我实测下来，本地模型在代码补全和简单重构上表现够用，但涉及跨文件的大范围改动时，还是需要更大的上下文窗口。所以如果你的机器内存有限，建议把 Codex 的任务拆小，一次只让它处理一个文件或者一个函数，效果反而更稳。

4. 常见报错与排查技巧实录

4.1 容器起不来：从日志里找线索

容器启动失败是最常见的问题，表现是docker compose ps显示 Exited 或者一直 Restarting。这时候别慌，第一步永远是看日志：

docker compose logs --tail=100 codex

日志会告诉你具体卡在哪。我遇到过几类典型情况。一类是端口被占用，报“address already in use”，解决办法是改本机映射端口，比如把 8787 改成 8788。另一类是挂载目录权限不对，容器内进程没有写权限，报“permission denied”，解决办法是调整本机目录权限，或者在 compose 里指定 user。

还有一类是镜像拉取失败，报“manifest unknown”或者超时。前者通常是镜像名写错了，检查一下仓库地址和标签；后者是网络问题，配置镜像加速或者换个时间段重试。

4.2 登录失败与配置不生效

登录环节的坑主要集中在配置读取上。如果你改了环境变量但行为没变化，很可能是配置没被正确加载。Codex 一般会按优先级读取配置：命令行参数高于环境变量，环境变量高于配置文件。所以如果你在 compose 里写了环境变量，但配置文件里也有同名字段，最终生效的可能是环境变量。

排查方法是进容器里看一眼实际生效的配置：

docker compose exec codex env | grep CODEX docker compose exec codex cat /root/.config/codex/config.json

两边对一下，看哪个值跟你预期不符。另外，登录状态如果存在但提示失效，可能是 config 目录挂载有问题，容器重启后状态丢了。确认一下挂载路径是否正确，以及本机对应目录里有没有生成凭证文件。

4.3 网络不通：容器访问本机服务的排查

容器里访问本机服务失败，报“connection refused”或者超时，这是本地部署里最高频的问题之一。根本原因是容器有自己的网络命名空间，localhost在容器里指的是容器自己，不是你的本机。

解决办法就是用host.docker.internal这个域名。Windows 和 macOS 的 Docker Desktop 默认支持，Linux 上需要在 compose 里加extra_hosts映射。加完之后进容器测试一下：

docker compose exec codex curl http://host.docker.internal:11434/v1/models

能返回模型列表就说明通了。如果还是不通，检查本机模型服务是不是只监听了127.0.0.1，这种情况下容器访问不到，需要让它监听0.0.0.0。

4.4 常见问题速查表

这张表建议存下来，遇到问题先对号入座，能省不少时间。

4.5 几个我踩过的坑

第一个坑是挂载路径写相对路径。compose 文件里的相对路径是相对于 compose 文件所在目录的，如果你在别的目录执行docker compose up，挂载就会指到错误的位置。我的习惯是统一用绝对路径，或者确保每次都在 compose 文件所在目录执行命令。

第二个坑是改了配置没重启。环境变量是在容器启动时注入的，改完 compose 文件必须docker compose up -d重建容器才生效，光restart是不够的。这一点我吃过好几次亏，改完配置发现没变化，折腾半天才想起来要重建。

第三个坑是日志级别设太高。默认 info 级别够用，但排查问题时可以临时调到 debug，能看到更详细的请求和响应。不过 debug 日志量很大，问题解决后记得调回去，否则磁盘很快被日志占满。

第四个坑是同时跑多个模型服务抢显存。如果你本机还跑着别的推理服务，Codex 再加载一个模型，显存可能不够，表现是模型加载失败或者推理极慢。部署前先确认显存占用，必要时错峰运行。

5. 让助手真正好用的几个配置技巧

5.1 工作目录的组织方式

Codex 读取项目文件的效果，跟你工作目录的组织方式关系很大。我的做法是在 workspace 下按项目分目录，每个项目保持标准的代码结构，不要把所有文件平铺在一层。这样助手在索引和定位文件时更准确，不会因为文件太多而抓错重点。

另外，建议在项目根目录放一个简短的说明文件，写清楚这个项目是做什么的、主要模块有哪些、用什么命令跑测试。助手读到这个文件后，对你项目的理解会明显提升，给出的建议也更贴合实际。

5.2 提示词的写法

跟本地助手打交道，提示词要具体。不要说“帮我优化一下代码”，而要说“把src/utils/date.js里的formatDate函数改成支持传入时区参数，默认用本地时区，改完跑一下npm test确认没破坏现有用例”。任务越具体，它执行得越准。

如果任务比较大，拆成几步。先让它读文件、给出修改方案，你确认后再让它动手改。这样你能控制节奏，避免它一次性改一堆文件，最后你都不知道改了哪里。

5.3 日志与审计

本地部署的一个优势是日志都在你手里。建议把日志目录也挂载出来，定期看一眼。一方面能发现异常请求，另一方面能回顾自己都让助手做了哪些操作。对于团队使用场景，日志还能作为操作记录留存。

日志轮转也要配一下，避免单个文件无限增长。Docker 层面可以在 compose 里配置 logging 选项，限制单个日志文件大小和保留数量。这个配置不起眼，但长期跑下来能省不少磁盘空间。

5.4 资源占用的观察与调优

跑起来之后，用docker stats看一下容器的 CPU 和内存占用。如果内存一直涨，可能是模型加载或者缓存没释放，需要限制容器内存上限，让它在超限时重启而不是拖垮整机。

CPU 占用高但响应慢，通常是模型推理本身的计算量，这种情况只能靠换更小的模型或者加硬件来解决。我个人的经验是，本地部署的体验瓶颈往往不在 Codex 这层，而在底层模型的推理速度。所以选模型时要在效果和速度之间做权衡，别一味追求大参数。

6. 关于本地 AI 编程助手的一些个人体会

我把这套环境跑通之后，最大的感受是“顺手”两个字值千金。以前用云端工具，每次都要切换窗口、复制粘贴，现在助手就在终端里，跟 git、npm 这些命令混着用，工作流是连贯的。改代码的时候让它跑个测试，测试挂了直接把报错丢给它，它读完日志给出修复建议，整个过程不用离开命令行。

另一个体会是，本地部署不是一劳永逸的事。模型会更新，配置会过时，依赖会冲突，隔一段时间就得维护一下。所以我在 compose 文件里把版本号都写死，不轻易用 latest 标签，避免某天拉了个新版本把环境搞崩。升级的时候先在一个临时目录里试，确认没问题再替换正式环境。

最后分享一个小技巧：把常用的几条命令写成 shell 别名，比如cx-up对应docker compose up -d，cx-logs对应docker compose logs -f，cx-shell对应进容器。每天都要敲的命令，能省一次是一次。这些别名放在你的 shell 配置文件里，换机器的时候一起带走，环境迁移的成本会低很多。