1. 先搞清楚 Codex 自定义宠物到底能做什么如果你在找“AI Agent 小宠物”的教程大概率是想做一个能放在桌面上、有互动能力、还能帮你干点活的智能助手。Codex 这个平台简单说它提供了一个框架让你能像“组装”一样把不同的 AI 能力比如对话、查资料、执行命令打包成一个独立的、可交互的 Agent智能体。这个 Agent 可以是一个命令行工具也可以是一个有界面的“桌面宠物”。所以这个教程的核心不是教你从零写几万行代码而是教你如何利用 Codex 的生态通过配置、安装技能和定义交互逻辑快速“组装”出一个属于你自己的 AI 小助手。它解决的实际问题是让不具备深厚 AI 模型开发能力的人也能快速创建功能定制的 AI 应用原型或工具。最适合看这篇教程的人有两类一是对 AI 应用开发感兴趣想快速上手体验的开发者或爱好者二是已经有一些 Python 基础想了解如何将大模型能力工程化、产品化的学习者。最关键的价值在于你能跳过复杂的模型训练和底层架构直接进入“应用层”看到 AI 能力如何被组织成一个可用的“智能体”。2. 动手前的环境与概念准备在开始“组装”宠物之前你得先把工作台搭好并理解几个关键概念。这不是简单的点几下鼠标需要一些基础的开发环境。2.1 核心环境Python 与 GitCodex 及其相关的技能生态目前主要围绕 Python 和 Git 构建。所以你的电脑上需要准备好这两样。Python 环境这是重中之重。建议使用 Python 3.8 到 3.11 之间的版本稳定性更好。不要用系统自带的 Python容易引起权限和依赖冲突。安装去 Python 官网下载安装包安装时务必勾选 “Add Python to PATH”。安装后打开终端Windows 是 CMD 或 PowerShellmacOS/Linux 是 Terminal输入python --version或python3 --version检查是否安装成功。虚拟环境我强烈建议使用venv或conda创建独立的虚拟环境。这能避免不同项目间的包版本冲突。命令很简单# 使用 venv python -m venv codex_env # 激活环境 (Windows) codex_env\Scripts\activate # 激活环境 (macOS/Linux) source codex_env/bin/activate激活后你的命令行提示符前会出现(codex_env)表示你在这个独立环境里操作。Git很多 Codex 的技能包Skill托管在 GitHub 上你需要 Git 来克隆代码。同样去 Git 官网下载安装一路默认即可。安装后在终端输入git --version验证。2.2 理解 Codex 的核心组件Agent 与 Skill这是理解整个教程的基石务必弄清楚Agent智能体这就是你要制作的“宠物”。它是一个具备特定目标、能感知环境、做出决策并执行动作的 AI 程序。在 Codex 里一个 Agent 由“大脑”通常是 LLM如 GPT和“技能”组成。Skill技能这是 Agent 的“手脚”和“工具箱”。一个 Skill 就是一个封装好的功能模块比如“查询天气”、“发送邮件”、“读写文件”、“控制智能家居”。Agent 通过调用不同的 Skill 来完成复杂任务。关系你可以把 Agent 想象成一个“项目经理”它负责理解你的指令比如“帮我查下天气然后写个邮件提醒”然后拆解任务调用“查天气 Skill”和“发邮件 Skill”这两个“专员”来具体执行。所以制作自定义宠物的过程本质上就是1) 创建一个 Agent2) 为它安装你需要的 Skills3) 定义它如何与你交互命令行、Web界面、桌面窗口。3. 从零启动你的第一个 Codex Agent理论说再多不如跑一遍。我们从一个最简化的流程开始目标是创建一个能进行基础对话并执行简单命令比如报时的 Agent。3.1 安装 Codex CLI 工具Codex 通常提供一个命令行工具CLI来管理 Agent 和 Skill。这是最常用的交互方式。假设它的安装包是通过 pip 发布的具体名称请以官方文档为准这里用codex-cli作为示例。在你的虚拟环境(codex_env)中运行pip install codex-cli安装完成后运行codex --version或codex --help检查是否安装成功并查看支持的命令。注意如果安装失败最常见的原因是网络问题pip 源或 Python 环境问题。先确保你的虚拟环境已激活并尝试使用国内镜像源安装pip install codex-cli -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 初始化一个 Agent 项目使用 CLI 创建一个新的 Agent 项目目录。codex init my_ai_pet cd my_ai_pet这个命令会生成一个项目文件夹里面通常包含config.yaml或agent.yamlAgent 的核心配置文件定义名称、使用的模型、技能列表等。skills/目录存放已安装技能的文件夹。requirements.txtPython 依赖列表。其他如logs/,data/等目录。3.3 配置 Agent 的“大脑” (LLM)Agent 需要一个大语言模型作为推理核心。Codex 通常支持接入 OpenAI API、Azure OpenAI 或本地部署的模型。打开config.yaml你需要配置类似以下内容具体字段名请参照官方文档agent: name: MyDesktopPet llm: provider: openai # 或 azure, local model: gpt-3.5-turbo # 根据你的选择调整 api_key: ${OPENAI_API_KEY} # 建议使用环境变量不要硬编码在文件里关键点API Key 安全绝对不要直接把 API Key 写在配置文件里提交到 Git。应该使用环境变量。在终端中设置# Windows (PowerShell) $env:OPENAI_API_KEYyour-api-key-here # macOS/Linux export OPENAI_API_KEYyour-api-key-here模型选择gpt-3.5-turbo成本较低适合学习和测试。如果你有权限可以尝试gpt-4系列能力更强但更贵。如果配置本地模型则需要额外设置base_url等参数。3.4 安装第一个 Skill让宠物能“看时间”一个只会聊天的 Agent 没什么意思。我们给它加个“报时”技能。假设有一个叫datetime_skill的官方技能。在项目目录下使用 CLI 安装codex skill install datetime_skill这个命令可能会从 GitHub 仓库拉取代码到skills/目录并自动安装其 Python 依赖。安装后你需要在config.yaml的skills部分启用它skills: - name: datetime_skill enabled: true现在你的 Agent 就具备了查询当前时间的能力。当它收到“现在几点”的指令时就会调用这个技能。3.5 运行并测试你的 Agent启动你的 Agentcodex run如果一切正常CLI 会启动一个交互式会话。你可以尝试输入“你好你是谁” 测试基础对话“现在是什么时间” 测试 datetime_skill“你能做什么” Agent 可能会列出已安装的技能如果遇到类似“detail”“the ‘gpt-5.6-sol’ model is not supported...”的错误这明确说明你在配置中指定的模型名称不被支持。请返回config.yaml将model字段修改为正确的、你拥有权限的模型名称如gpt-3.5-turbo。4. 实现“桌面宠物”功能从 CLI 到图形界面一个运行在命令行的 Agent 还算不上“桌面宠物”。我们需要给它一个图形界面GUI。这里有几个常见的实现方向。4.1 方案一使用系统托盘图标 (Tray Icon)这是实现“宠物”感的经典方式。宠物常驻在桌面任务栏的通知区域点击可以弹出交互窗口。选择 GUI 库Python 有很多选择如PyQt5、PySide6、Tkinter。对于宠物类应用PyQt5功能强大Tkinter更轻量但原生界面较丑。这里以PyQt5为例。安装依赖在虚拟环境中安装。pip install pyqt5创建宠物窗口你需要编写一个 Python 脚本创建一个无边框、可拖动、带有透明背景的窗口并加载一个宠物动画GIF 或序列帧。集成 Agent在 GUI 程序中启动一个子进程或线程来运行你的 Codex Agent即codex run的后端服务。GUI 负责捕获用户的输入如双击宠物、右键菜单命令并通过网络请求如 HTTP API或进程间通信IPC发送给 Agent再将 Agent 的回复显示在 GUI 上。核心难点如何让 GUI 前端与 Codex Agent 后端通信。一个简单的做法是在初始化 Agent 时将其配置为提供 HTTP API 服务如果 Codex 支持此模式。这样GUI 只需发送 HTTP POST 请求到http://localhost:8000/chat这样的端点即可。4.2 方案二使用 Web 界面 本地服务器对于不熟悉原生 GUI 开发的开发者这可能更简单。构建 Web 后端使用 FastAPI 或 Flask 创建一个简单的 Web 服务器。这个服务器的核心功能是“转发”接收前端发来的用户消息调用本地的 Codex Agent CLI通过subprocess模块或 SDK 来获取回复再返回给前端。# FastAPI 示例片段 from fastapi import FastAPI, HTTPException from pydantic import BaseModel import subprocess import json app FastAPI() class Message(BaseModel): content: str app.post(/chat) async def chat_with_agent(message: Message): # 这里需要根据 Codex CLI 的实际调用方式调整 # 例如通过 subprocess 与一个持续运行的 agent 进程交互 # 或者使用 Codex 提供的 Python SDK result subprocess.run([codex, chat, --message, message.content], capture_outputTrue, textTrue) if result.returncode ! 0: raise HTTPException(status_code500, detailresult.stderr) return {response: result.stdout}构建 Web 前端使用 HTML/CSS/JavaScript 创建一个简单的聊天界面。你可以把它做得像一个宠物对话框。前端通过 Fetch API 与上述后端通信。打包为桌面应用使用PyInstaller或electron将整个 Web 应用Python 后端 前端资源打包成一个独立的桌面可执行文件。这样用户无需安装 Python 环境即可运行。4.3 方案三利用现有的桌面集成工具有些开源项目专门为 CLI 工具提供图形化外壳。你可以探索是否有人为 Codex 开发了类似的桌面插件或包装器。但这通常可定制性较低。我的建议如果你是初学者想快速看到“宠物”效果可以从方案二Web界面入手技术栈更通用调试方便。如果你追求更好的原生体验和性能并且有 GUI 开发经验方案一是更专业的选择。5. 安装与管理更多高级技能一个只会报时的宠物显然不够酷。Codex 生态的魅力在于丰富的技能库。安装技能通常是这样的流程发现技能在 Codex 社区或 GitHub 上搜索你需要的技能例如weather_skill天气、news_skill新闻、file_ops_skill文件操作、web_search_skill网络搜索。安装技能codex skill install skill-git-url # 例如codex skill install https://github.com/codex-community/weather_skill.git配置技能许多技能需要额外的配置比如天气技能需要天气 API 的密钥。安装后仔细阅读技能目录下的README.md按照说明在config.yaml或单独的技能配置文件中设置。skills: - name: weather_skill enabled: true config: api_key: ${WEATHER_API_KEY} # 同样使用环境变量 default_city: Beijing - name: web_search_skill enabled: true config: search_api_key: ${SEARCH_API_KEY} search_engine_id: ${SEARCH_ENGINE_ID}测试技能启动 Agent 后尝试发出相关指令如“上海今天天气怎么样”或“搜索一下最新的 AI 新闻”。避坑点依赖冲突不同技能可能依赖同一库的不同版本。如果安装后 Agent 启动报错首先检查pip list看是否有版本冲突或在虚拟环境中逐一安装测试。技能失效如果某个技能调用总是失败先别急着怀疑 Agent。打开技能的日志通常位于项目logs/目录下看是否是 API 密钥无效、网络请求超时或技能内部逻辑错误。权限问题涉及文件操作、系统命令的技能需要谨慎授权。最好在沙箱环境或明确知晓其行为后再在生产环境中使用。6. 深度自定义从使用技能到编写技能当你不再满足于安装现有技能想让你宠物拥有独一无二的能力时你就需要学习编写自己的 Skill。6.1 Skill 的基本结构一个 Codex Skill 通常是一个 Python 包目录结构如下my_custom_skill/ ├── __init__.py ├── skill.yaml # 技能元数据名称、描述、版本、输入输出格式 ├── requirements.txt # 技能独有的依赖 └── skill.py # 技能的主要实现逻辑6.2 编写一个简单的技能例如我们编写一个joke_skill讲笑话技能。创建skill.yaml:name: joke_skill version: 0.1.0 description: “A skill that tells a random joke.” author: YourName inputs: - name: category type: string required: false description: “Category of joke, e.g., ‘programming‘, ‘dad‘.” outputs: - name: joke type: string description: “The joke text.”编写skill.py:import random from typing import Dict, Any class JokeSkill: def __init__(self, config: Dict[str, Any]): # 可以在这里初始化比如读取配置 self.jokes { “programming“: [“Why do programmers prefer dark mode? Because light attracts bugs.“], “dad“: [“I‘m reading a book on anti-gravity. It‘s impossible to put down!“], “general“: [“What do you call a fake noodle? An impasta!“] } def execute(self, inputs: Dict[str, Any]) - Dict[str, Any]: category inputs.get(“category“, “general“) joke_list self.jokes.get(category, self.jokes[“general“]) selected_joke random.choice(joke_list) return {“joke“: selected_joke}在 Agent 中安装本地技能在你的 Agent 项目目录下可以将my_custom_skill文件夹链接或复制到skills/目录下然后在config.yaml中启用它。skills: - name: “joke_skill“ enabled: true path: “./skills/my_custom_skill“ # 指向本地路径现在你的宠物就能响应“讲个笑话”或“讲个编程笑话”的指令了。6.3 让技能更实用连接真实服务真正的技能需要与外部世界交互。例如一个“订咖啡”技能需要调用咖啡店的 API。你需要在skill.yaml中定义清晰的输入咖啡类型、数量、配送地址。在skill.py的execute方法中使用requests库调用第三方 API。妥善处理 API 密钥通过配置传入、网络异常和返回结果解析。将处理结果格式化为 Agent 能理解的输出字典。7. 生产化部署与长期维护思考当你做出了一个满意的宠物 Agent可能会想让它持续运行或者分享给别人用。这时需要考虑更多。持续运行在个人电脑上你可以将启动 Agent 的命令如codex run设置为开机自启动通过系统服务或启动项。但更稳定的做法是在一台云服务器上部署让它 7x24 小时运行并通过 Telegram Bot、Discord Bot 或 Webhook 与你交互。配置管理将所有敏感信息API Keys、数据库密码移出代码使用环境变量或专门的配置管理工具如dotenv读取.env文件。日志与监控确保 Agent 和技能的日志被妥善记录Codex 通常有日志配置。对于重要技能可以增加简单的健康检查比如定期调用一次确保 API 未失效。技能更新关注你所用技能的 GitHub 仓库及时更新以获取新功能和安全补丁。更新后务必在你的测试环境中充分验证再更新到生产环境。成本控制如果你的 Agent 频繁调用 GPT 等付费 API需要关注使用量和成本。可以在代码中增加使用量统计和限流逻辑。从零制作一个 AI Agent 桌面宠物最关键的步骤不是编码而是理解“组装”的逻辑配置大脑LLM、安装技能功能模块、设计交互前端。先用一个最简单的技能跑通整个流程再逐步添加复杂功能这样能有效避开初期环境配置和概念混淆的坑。当你的宠物能稳定响应指令后再深入去研究如何编写自定义技能、优化交互界面这条路会清晰很多。