企业官网建设流程全解析

Codex 和 Claude Code 这两款命令行 AI 编程工具，现在越来越多人拿来写代码、跑自动化任务。但真要落地到自己的项目里，绕不开一个问题：怎么接上兼容 API，同时又不把 Key 弄丢、弄漏、弄进 Git 历史里。我见过太多人把 Key 直接写在命令行参数里，或者随手粘贴到bash_history，等回过神来已经泄露了。这篇文章就把我实际配置过的一套方案完整写出来，从环境准备、Key 托管、Codex 接入、Claude Code 接入，到常见报错排查，一步步拆开讲。

这套配置思路不限具体厂商，DeepSeek、智谱、本地模型、各类 OpenAI 兼容网关都可以套用。核心原则只有三条：第一，Key 不落盘不进历史；第二，能用环境变量就不用配置文件明文；第三，凡是接近生产环境的项目，一定要走本地代理网关或者受限 token 方案。下面从工具链搭建开始。

1. 环境准备：先把 Codex 和 Claude Code 跑起来

1.1 安装 Node.js 与 CLI 工具

Codex 和 Claude Code 的 CLI 都依赖 Node.js 运行时，所以第一步先装 Node.js。版本建议装 18 以上，我实测在 Node 20 LTS 上两个工具都跑得很稳；Node 16 下部分依赖会有兼容性问题，尤其是 Claude Code 的现代端点和流式输出处理。

Windows 用户直接去官网下载 MSI 安装包，安装过程勾选“Add to PATH”，装完开一个新的 PowerShell 窗口验证：

node -v npm -v

macOS 用户我建议用 Homebrew：

brew install node@20

装完如果node命令找不到，多半是 PATH 没配好。macOS 上 Homebrew 的 Node 路径在/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel），手动加进 shell 配置文件即可。

然后安装两个 CLI 工具：

npm install -g @openai/codex npm install -g @anthropic-ai/claude-code

安装完成后检查版本：

codex --version claude --version

1.2 初始化工作目录

我习惯把所有 AI 工具相关的配置、脚本、日志放一个独立目录，不散落在各个项目里。这样既方便排查，也方便设置统一的权限。比如：

mkdir -p ~/ai-toolkit mkdir -p ~/ai-toolkit/keys mkdir -p ~/ai-toolkit/logs

然后给keys目录加白名单与严格权限：

chmod 700 ~/ai-toolkit/keys

这一步很重要。你的 Key 文件、.env文件全部塞进这个目录，目录权限只对当前用户开放。后续所有配置都以这个目录为基点，不会在各个项目目录里到处散落敏感文件。

1.3 验证 CLI 能否正常启动

在还没有配置任何 Key 之前，先跑一次帮助命令，确保 CLI 没有因为缺少环境变量直接崩溃：

codex --help claude --help

如果这里正常输出帮助信息，说明 Node 环境没问题。接下来进入配置阶段。

2. Key 安全骨架：三层隔离方案

2.1 为什么不能把 Key 直接写在配置文件里

先说一个很多人踩过的坑。Codex 的配置文件支持把 API Key 直接写在config.toml里，Claude Code 也支持在环境变量里直接写明ANTHROPIC_API_KEY=sk-xxx。本地单机用一次两次问题不大，但只要项目文件被同步到网盘、提交到 Git 仓库、或者别人借用你的电脑，Key 就等于裸奔了。

更隐蔽的风险是 shell 历史记录。你如果执行过export ANTHROPIC_API_KEY=sk-xxx，这个 Key 会出现在~/.zsh_history或~/.bash_history里。很多所谓的“泄露”，根本不是被攻击，而是历史记录被脚本扫描、浏览器插件读取、或者终端同步工具上传。

还有一类问题出在 CI/CD 和协作场景：团队里一把共享 Key 放在文档里，大家复制来复制去，最终总有人贴错位置或者误发到群里。

所以安全方案的第一原则：不要让 Key 以明文形式出现在可被他人读取的文件中。

2.2 第一层：环境变量与严格 .env 文件

我推荐的基线方案是把 Key 放在~/ai-toolkit/keys/local.env，这个文件只允许当前用户读写，然后用 shell 的set -a导入。

先创建文件：

touch ~/ai-toolkit/keys/local.env chmod 600 ~/ai-toolkit/keys/local.env

内容大概是这样的格式：

# Codex 兼容 API CODEX_API_KEY=你的密钥 CODEX_BASE_URL=https://api.deepseek.com # Claude Code 兼容 API ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic ANTHROPIC_AUTH_TOKEN=你的密钥 # 本地模型可选 LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1

然后在使用的时候，不要手动 source，而是写一个统一加载脚本~/ai-toolkit/load-env.sh：

#!/bin/bash set -a # shellcheck disable=SC1091 source "$HOME/ai-toolkit/keys/local.env" set +a

使用方式：

source ~/ai-toolkit/load-env.sh codex

注意：set -a的作用是让后续 source 进来的变量自动导出到子进程环境，不加这一句，有些 CLI 读不到变量。

2.3 第二层：会话级临时 Key 与最小权限令牌

如果只是个人电脑上写点小脚本，环境变量方案足够。但如果是公司项目、多人协作用同一套后端服务，我更建议采用“会话级临时 Key”方案，而不是让每个人持有长期有效的总 Key。

具体做法是搭一个轻量的本地 API 网关（比如用 Node.js 写一个 30 行的代理服务），这个网关持有真正的上游 Key，下游工具只访问本地网关的临时 token。网关启动时从环境变量里读取上游 Key，然后为每个会话签发一个几分钟内过期的临时 token。这样即使用电脑被别人碰了一下，临时 Key 泄露了，几分钟后也就失效了。

网关还可以做一层模型权限控制。比如只允许特定模型、限制每分钟请求数、限制单次上下文长度。这个价值在团队场景里非常明显：你不需要告诉成员“这把 Key 是公司的”，只需要告诉他们“访问这个本地地址”。

最小权限令牌的思路同样适用于云平台的 API Key 管理。DeepSeek、智谱这些平台的控制台里，都支持创建多个 Key，建议为不同用途单独建 Key，例如codex-local、claude-prod、ci-runner，一旦某个 Key 泄露，直接吊销对应那一把，不影响其他任务。

2.4 第三层：Git 防泄露与仓库扫描

配置系统里还有一个高频事故点：.env文件被提交进 Git。

我强烈建议在任何项目落地之前，先编辑全局 Git 配置，把 Key 目录挡在提交范围之外：

git config --global core.excludesfile ~/.gitignore_global

然后在~/.gitignore_global里写：

.env .env.* *.pem *key*.json credentials.json

另外配一条提交前检查命令，防止误提交：

git config --global init.templatedir ~/.git-templates

其实最有效的是在团队仓库根目录的.gitignore里写明规则，并让 CI 跑一个密钥扫描工具。个人项目的话，推荐装一个 gitleaks 之类的本地扫描器，提交前扫描一下 staging 区域：

gitleaks protect --staged --verbose

千万别觉得“我就一个人写，不会提交 Key”。我见过不止一次，有人在项目里调试完忘了删local.env，结果git add .的时候把 Key 一起带上去了。等到推 GitHub 再想起来，已经晚了，因为远程历史里已经存了一份。

3. Codex 接入兼容 API：模型路由与多供应商配置

3.1 Codex 配置体系解析

Codex CLI 的配置主要分布在两个位置：

• ~/.codex/config.toml：全局配置，包括模型选择、模型供应商、行为开关。
• ~/.codex/auth.json：认证信息存储，老版本会直接在这里存 Key。

在接入兼容 API 时，我们要做的是在config.toml里声明model_providers，然后在环境变量里注入对应的 Key。这样auth.json里甚至不需要出现任何真实密钥。

先看一下典型结构：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "CODEX_API_KEY"

这里base_url指向兼容 OpenAI 接口的服务地址，env_key指定从哪个环境变量读取 Key。Codex 在发起请求时，会读取CODEX_API_KEY并加到 Authorization 请求头。可以理解为：Codex 只负责把模型输入送到指定的 base_url，至于 Key 怎么管理，完全由你决定。

3.2 以 DeepSeek 为例的接入步骤

先确保环境变量已经加载：

source ~/ai-toolkit/load-env.sh echo $CODEX_API_KEY

然后编辑~/.codex/config.toml：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "CODEX_API_KEY" wire_api = "responses"

这里有个关键参数wire_api。Codex 默认走的是 OpenAI 的 Responses API（也就是/responses端点），而 DeepSeek 官方的是 Chat Completions 风格接口。根据你用的网关类型，可能需要切换wire_api的取值：

wire_api = "chat" # 走 /chat/completions wire_api = "responses" # 走 /responses

实测经验：如果你接的是直接厂商的 API，多半要选chat；如果是自定义网关或者某些服务器托管平台，要确认网关到底兼容哪个端点。选错了典型报错就是“404 endpoint not found”或者“unsupported request”。

配置完成后，直接在任意目录运行：

codex "用 Python 写一个读取 CSV 并统计每列空值数量的脚本"

如果运行正常，你会看到模型开始输出代码。此时打开终端里的第二个窗口，执行：

env | grep -i codex

你应当能看到CODEX_API_KEY已经被传入子进程，但不会出现在命令行参数中，也不会出现在ps输出里。

3.3 配置多供应商路由

有些人会在 Codex 里同时接两三个模型服务：日常写代码用快速便宜的模型，复杂代码审查用更大上下文的高端模型。这时候model_providers就派上用场了。

示例：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek 官方" base_url = "https://api.deepseek.com" env_key = "CODEX_API_KEY" wire_api = "chat" [model_providers.zhipu] name = "智谱 GLM" base_url = "https://open.bigmodel.cn/api/paas/v4" env_key = "ZHIPU_API_KEY" wire_api = "chat"

切换模型时，直接改model和model_provider两个字段，或者运行时用参数覆盖：

codex --config model_provider=zhipu --config model=glm-4-plus "分析这段代码的时间复杂度"

这种配置方式的优势是 Key 隔离。每个供应商的 Key 都独立存放、独立吊销，不会出现一把 Key 通吃所有服务的情况。

3.4 接入本地模型的特殊处理

本地模型方案适合完全离线的场景，比如 LLaMA.cpp 或者 LM Studio 起一个本地 OpenAI 兼容服务。Codex 接入本地模型时，base_url指向本机端口即可：

model = "local-model" model_provider = "local" [model_providers.local] name = "LM Studio Local" base_url = "http://127.0.0.1:1234/v1" env_key = "CODEX_API_KEY" wire_api = "chat"

需要留意的是，很多本地模型的上下文窗口比较小，Codex 默认会给模型发送系统提示、工具定义、文件列表等元信息。这些内容会占据大量 context，本地小模型往往直接提示超限。解决办法是在config.toml里关闭部分自动行为，并且手动控制输入规模：

model_context_window = 32768

把窗口值限制在模型实际支持的范围内，避免请求超出模型规格导致 400 错误。本地模型接入还有一个比较容易忽略的点：流式输出。有些本地推理引擎对"stream": true支持不完善，如果发现输出断断续续或者卡死，可以把流式关闭，但这通常需要在网关侧设置，Codex 本身没有直接暴露开关，所以建议优先选对 OpenAI 兼容性较好的推理引擎。

4. Claude Code 接入兼容 API：环境变量与本地代理模式

4.1 核心环境变量说明

Claude Code 跟 Codex 的配置思路不太一样，它更依赖环境变量。最关键的两个变量是：

• ANTHROPIC_BASE_URL：API 请求的基地址。
• ANTHROPIC_AUTH_TOKEN：认证令牌，直接作为请求头里的 Bearer Token。

有很多兼容 Anthropic API 格式的服务端，比如 DeepSeek 提供了一个/anthropic入口，可以让 Claude Code 直接使用 Anthropic 风格的请求格式。配置如下：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的密钥"

然后启动：

claude

为了不让环境变量散落在各个 shell 会话中，还是统一放到~/ai-toolkit/keys/local.env：

ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic ANTHROPIC_AUTH_TOKEN=你的密钥

修改之后重新加载：

source ~/ai-toolkit/load-env.sh claude

4.2 通过 claude-code-router 做模型中转

Claude Code 的社区里有个非常常用的工具叫claude-code-router，也就是安装命令为cc的那个路由工具。它的作用是在 Claude Code 和真实 Anthropic API 之间插入一个本地代理层，由这个代理层把请求分发到不同的模型服务商。

安装：

npm install -g claude-code-router cc setup

cc setup会引导你编辑路由配置文件，典型内容大概是：

{ "Providers": [ { "name": "deepseek", "api_base_url": "https://api.deepseek.com/anthropic", "api_key": "env:DEEPSEEK_KEY" }, { "name": "zhipu", "api_base_url": "https://open.bigmodel.cn/api/paas/v4", "api_key": "env:ZHIPU_KEY" } ], "Router": { "default": "deepseek" } }

注意api_key写的是env:DEEPSEEK_KEY，意思是让路由器从环境变量里读取，而不是把明文 Key 写进路由配置。这是我在实际项目里一直强调的点：哪怕路由工具允许你直接写 Key，也不要写。

配置完成后，把 Claude Code 的请求指向本地路由：

export ANTHROPIC_BASE_URL="http://127.0.0.1:3456" export ANTHROPIC_AUTH_TOKEN="local-router-token" claude

这里的 Auth Token 是路由器发给 Claude Code 的本地令牌，不涉及上游真实 Key。真实 Key 只存在于路由器的进程内存里，这样你的 shell 环境、Git 历史、截图工具里都不会出现敏感凭证。

4.3 组织订阅策略与 API Key 模式的选择

使用 Claude Code 时有两条路径：一是登录 Claude 账号，走订阅模式；二是使用 API Key，走按量计费模式。

如果你的账号收到类似 “your organization has disabled claude subscription access for claude code” 的提示，说明当前组织关闭了 Claude Code 的订阅访问权限。这个提示跟你的 Key 本身没关系，是组织层面的策略。解决办法有两个：

• 找组织管理员在 Claude 控制台里开启 Claude Code 访问权限。
• 或者在当前环境改用 API Key 模式，也就是设置ANTHROPIC_AUTH_TOKEN，绕开订阅登录。

我的建议是：凡是接入兼容 API 和第三方网关，一律使用 API Key 模式。因为订阅模式的认证链路比较长，中间经过路由器时经常会因为认证方式不匹配而失败，而 API Key 模式本质上只是设置 HTTP 请求头，干净利落。

一个小细节：有些版本里，如果你之前登录过 Claude 账号，它会优先走订阅认证。此时需要确保环境变量已经正确传入，必要时执行：

claude /logout

或者直接在当前目录放一个空的.claude/settings.json，避免加载旧配置。

4.4 Claude Code 子模型与微调

Claude Code 还支持配置子模型（处理工具调用、提取摘要的模型）。在兼容 API 场景下，如果主模型可用但子模型不可用，功能会异常。建议在~/.claude/settings.json里显式配置：

{ "env": { "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-chat" } }

如果服务商只支持一个模型，就把主模型和子模型都指向同一个。很多兼容端点会忽略模型名，统一映射到固定的模型，所以这个设置视服务商情况而定。遇到实际报错时再调整，不需要一开始就纠结。

5. 报错日志速查：我遇到过的 5 类高频问题

5.1 401 Unauthorized / Incorrect API Key

这是接入兼容 API 最常见的错误，日志格式为：

unexpected status 401 unauthorized: incorrect api key provided: sk-svcac...

排查步骤：

1. 先确认环境变量有没有正确加载。在终端里运行env | grep -i api_key，看看值是否完整。
2. 检查变量名是否和 CLI 要求一致。Codex 读的是env_key指定的变量名，Claude Code 读的是ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY。
3. 检查 Key 前后有没有空格或者换行符。从网页复制 Key 时经常带入隐藏换行，导致整个 Key 拼入失败。
4. 检查 Key 是否配置了错误的权限范围。有些平台创建 Key 时可以选择读写范围，如果只允许读不允许写，调用生成接口一样可能报 401。

经验：我通常把 Key 在终端里打印前几位和后几位：

echo ${CODEX_API_KEY:0:6}...${CODEX_API_KEY: -4}

这样能判断 Key 是否被截断，又不泄露完整内容。

5.2 cc switch local proxy failed while handling codex endpoint /responses

这个报错出现在使用 claude-code-router 时。意思是本地代理在处理 Codex 的/responses请求时失败了。

大多数人第一反应是觉得 Key 错了，其实这个报错多数是路由器的协议转换问题。Codex 默认用/responses端点，而部分服务商只实现了/chat/completions。解决思路：

• 确认 Codex 侧的wire_api设置正确。
• 如果使用 claude-code-router 作为统一入口，要检查它的配置里是否把 Codex 请求转发到支持/responses的 provider。
• 有些路由器版本还不支持 Responses API 与 Chat Completions API 之间的自动转换，需要你手动指定目标 provider 的类型。

最简单的排查方法是开启路由器日志，看看请求实际发到了哪个 URL：

cc doctor

5.3 400 context length 超限

错误示例：

api error: 400 this model's maximum context length is 1048576 tokens

有些模型上下文窗口很大（比如一百万 token），但你的请求依然会触发这个错误。原因往往不是单次对话太长，而是 Codex 会自动把项目文件读进上下文。你只问了“读一下 README”，但它可能顺手把整个目录的代码片段都打包发给模型了。

处理思路：

• 在启动 Codex 之前，先用cd进入一个不包含大文件目录的临时工作区。
• 在配置里降低model_context_window，让 Codex 更保守地管理文件加载。
• 检查是否误把日志文件、后端依赖目录、构建产物放进了项目上下文里。

5.4 Organization disabled 提示

这个我在 4.3 已经提过。再补一个细节场景：如果你用的是第三方 API 服务商，而不是 Anthropic 官方，偶尔也会返回 “this organization has been disabled” 之类的 400 错误。这时候往往是服务商后台对账号的状态问题，比如余额不足、月额度耗尽、组织被风控。跟你的本地配置无关，直接登录服务商控制台查看账户状态即可。

5.5 public key retrieval is not allowed

这个报错在 SSH 场景比较常见，但如果你在配置某些使用公钥交换的服务时也会遇到。含义是：服务器禁止你通过未授权的方式检索公钥。处理办法是确认环境变量里的 Key 格式正确，不要用 HTTP(S) 代理层的公钥替代 API Key。如果你没有主动配置 SSH 类的东西，那这个报错更可能是“环境变量被误设导致认证方式错乱”，清空多余的SSH_AUTH_SOCK和代理变量再试。

6. 实战配置模板：从零到跑通

6.1 Codex + DeepSeek 完整模板

如果你想照着抄，下面这份以 DeepSeek 为案例的 Codex 配置可以直接用。

~/.codex/config.toml：

model = "deepseek-chat" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" env_key = "CODEX_API_KEY" wire_api = "chat"

~/ai-toolkit/keys/local.env：

CODEX_API_KEY=sk-你的key

然后启动：

source ~/ai-toolkit/load-env.sh codex "帮我写一个冒泡排序"

6.2 Claude Code + 兼容端点完整模板

~/ai-toolkit/keys/local.env：

ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic ANTHROPIC_AUTH_TOKEN=sk-你的key

启动：

source ~/ai-toolkit/load-env.sh claude

如果是通过 claude-code-router：

~/.claude-code-router/config.json：

{ "Providers": [ { "name": "deepseek", "api_base_url": "https://api.deepseek.com/anthropic", "api_key": "env:ANTHROPIC_AUTH_TOKEN" } ], "Router": { "default": "deepseek" } }

启动：

cc export ANTHROPIC_BASE_URL="http://127.0.0.1:3456" export ANTHROPIC_AUTH_TOKEN="local-router-token" claude

6.3 配置完成后的验证清单

每次配置完，我习惯按顺序跑一遍这五条验证：

1. 环境变量加载确认：env | grep -i key，确认 Key 存在。
2. 网络连通性：curl -I $ANTHROPIC_BASE_URL，确认端点可达。
3. 最小请求测试：用codex或claude发一句“hi”，确认能拿到回复。
4. ps aux | grep codex或者ps aux | grep claude，确认命令行参数里没有任何 Key 痕迹。
5. git status确认.env、local.env、config.json没有被误判为待提交文件。

这五条大约两分钟跑完，但能拦住绝大多数低级事故。

7. 关于 Key 安全的最后几句话

我把 Key 安全这件事摆在最后说，不是因为它不重要，恰恰是因为它太容易被忽略，又太容易出现不可逆的后果。我自己经历过一次把公司 Key 误推到远程仓库，当时以为是小事，结果 20 分钟后收到平台的告警邮件，那个 Key 已经被人拿去调用了。从那以后，我的所有 AI 工具配置都强制走环境变量，界线上没有任何退让。

再分享一个小技巧：给每个服务商单独建一个 Key，名字标明用途，比如deepseek-codex-dev、deepseek-claude-prod。万一出现异常，你能立刻知道是哪个场景泄露的，然后在控制台点一下吊销，五分钟内解决问题。不要高估自己的记忆力，也不要低估日志扫描脚本的覆盖率。

配置兼容 API 这件事本身并不复杂，复杂的是让这个配置在三天后、三周后、换了一台电脑后依然安全可靠。把 Key 收进环境变量，把敏感文件关进chmod 600的目录，把工作流的每一步都变成肌肉记忆。剩下的，就是放心让 Codex 和 Claude Code 替你干活了。