X-Code CLI

不绑定模型、兼容 Claude Code 扩展生态的开源编程 Agent CLI。

使用 Claude、GPT、Gemini、DeepSeek、Qwen、Kimi 或任意 OpenAI 兼容接口，复用同一套 Skills、Plugins、MCP 和 Agent 工作流。

English · 简体中文

为什么选 X-Code CLI？

不绑定模型 — 通过 /model 随时切换提供商，也可以接入任意 OpenAI 兼容接口。同一套工作流，任意模型。

兼容 Claude Code 扩展生态 — 直接复用为 Claude Code 构建的插件、Skills、子 Agent、MCP 服务器和 Hooks。插件加载器同时识别 .x-code-plugin/ 和 .claude-plugin/ 格式。

开源可控 — 开源、BYOK、本地执行、三级权限模型可配置。你决定 Agent 能做什么。

完整的 Agent 运行时 — 不只是对话封装，而是覆盖规划、执行、记忆、上下文管理和任务验证的完整开发工作流。

X-Code CLI 是独立的开源项目，与 Anthropic 无关。

安装

需要 Node.js >= 22（不支持 Node 20）。

npm install -g @x-code-cli/cli

# 或
pnpm add -g @x-code-cli/cli

安装完成后，使用 xc 或 x-code 命令启动。

配置模型访问方式

使用 OpenAI 模型时，可以登录 ChatGPT 使用订阅权益：

xc login                    # 浏览器登录，成功后直接进入交互产品
xc login --device-auth      # 设备码登录，成功后直接进入交互产品
xc login status             # 查看当前 OpenAI 认证方式
xc logout                   # 退出并删除本地 ChatGPT 凭据

在交互式终端中，xc login（包括 --device-auth）登录成功后会直接进入 X-Code CLI，无需再次执行 xc。进入产品后，也可以使用 /login、/login --device-auth、/login status 和 /logout 完成同一套认证操作。

对于 openai provider，ChatGPT 登录和 OPENAI_API_KEY 严格互斥。ChatGPT 已登录时，请求使用 ChatGPT 订阅权益，API key 处于停用状态，认证失败也不会回退到 API key；执行 xc logout 后，已有的 OPENAI_API_KEY 才会恢复生效，其请求按 OpenAI Platform 账户用量计费。其他 provider 的 API key 不受影响。

当前版本将 ChatGPT token 以明文凭据文件保存在 ~/.x-code/auth/（或 X_CODE_HOME）下。请像保护密码一样保护该文件：保持目录私有，不要提交到版本库、分享给他人或同步到不可信位置。当前尚未实现系统凭据库（keyring）存储。

也可以配置至少一个厂商的 API Key：

推荐 DeepSeek：价格低、国内访问稳定，适合首次试用。赠送额度与价格可能变化，请以官方控制台为准。

| 环境变量 | 厂商 | 注册地址 | | ------------------------------ | ------------------- | --------------------------------------------------------------------------- | | ANTHROPIC_API_KEY | Anthropic（Claude） | console.anthropic.com | | OPENAI_API_KEY | OpenAI（GPT） | platform.openai.com/api-keys | | DEEPSEEK_API_KEY | DeepSeek | platform.deepseek.com/api_keys | | GOOGLE_GENERATIVE_AI_API_KEY | Google（Gemini） | aistudio.google.com/apikey | | ALIBABA_API_KEY | 阿里通义（Qwen） | dashscope.console.aliyun.com | | XAI_API_KEY | xAI（Grok） | console.x.ai | | ZHIPU_API_KEY | 智谱（GLM） | open.bigmodel.cn | | MOONSHOT_API_KEY | Moonshot（Kimi） | 按服务选择 |

OpenAI 兼容接入（vLLM / OpenRouter / 代理网关等）：同时设置 OPENAI_COMPATIBLE_API_KEY 与 OPENAI_COMPATIBLE_BASE_URL，模型 ID 写成 custom:<your-model-id>。

以下示例使用 DEEPSEEK_API_KEY，请替换为实际厂商变量名。

bash（Linux / Git Bash / WSL）

echo 'export DEEPSEEK_API_KEY=sk-...' >> ~/.bashrc
source ~/.bashrc

zsh（macOS 默认）

echo 'export DEEPSEEK_API_KEY=sk-...' >> ~/.zshrc
source ~/.zshrc

fish

set -Ux DEEPSEEK_API_KEY sk-...

Windows PowerShell（用户级，永久生效）

[Environment]::SetEnvironmentVariable('DEEPSEEK_API_KEY', 'sk-...', 'User')
# 重启 PowerShell 后生效

Windows CMD（用户级，永久生效）

setx DEEPSEEK_API_KEY "sk-..."
:: 重启 CMD 后生效

临时使用：export X=...（bash）或 $env:X = '...'（PowerShell），终端关闭后失效。

项目级配置：放置 .env 文件后，xc 会从当前目录向上查找并只加载找到的第一个文件。

启用 webSearch 工具需任选一项配置：

| 环境变量 | 提供方 | 当前免费额度 | 注册门槛 | | -------------------- | ---------------------------------------------------------- | ---------------------- | ---------------- | | TAVILY_API_KEY | Tavily | 每月 1,000 API credits | 邮箱，无需信用卡 | | BRAVE_API_KEY | Brave Search | —（付费） | 需绑定信用卡 | | EXA_API_KEY | Exa | 每月 1,000 次请求 | 邮箱，无需信用卡 | | PERPLEXITY_API_KEY | Perplexity Sonar | —（付费） | 需绑定信用卡 | | FIRECRAWL_API_KEY | Firecrawl | 免费 credits 额度 | 邮箱，无需信用卡 |

推荐首次配 Tavily：注册简便，返回格式针对 LLM 优化。配置多个 key 时按上表顺序取第一个；也可通过 X_CODE_WEB_SEARCH_PROVIDER 显式指定（可选值：tavily、brave、exa、perplexity、firecrawl、deepseek）。

DeepSeek 用户无需额外 key：当前模型为 DeepSeek 且已配置 DEEPSEEK_API_KEY 时，webSearch 自动使用 DeepSeek 内置的服务端联网搜索。注意每次搜索按一次模型调用计费（默认 deepseek-v4-flash），而非按搜索次数计费。

Moonshot/Kimi 提供三套独立的凭证与端点，API Key 只能用于签发它的服务：

• Kimi Code 订阅计划：Kimi Code 控制台 → https://api.kimi.com/coding/v1
• 国内开放平台：platform.kimi.com → https://api.moonshot.cn/v1
• 国际开放平台：platform.kimi.ai → https://api.moonshot.ai/v1

通过 /model 选择 Kimi 模型后，X-Code CLI 会自动显示端点选择器。

快速上手

cd your-project

xc                                   # 启动交互式会话
xc "解释项目的整体架构"                # 带提示词运行
xc -m sonnet "重构 formatDate 函数"    # 指定模型

核心功能

智能开发

• 内置工具 — 文件读写、Shell 执行、代码搜索（Grep / Glob）、网页抓取、子 Agent 委派、Todo 追踪等
• 子 Agent — 内置 5 个（explore / general-purpose / plan / code-reviewer / goal-verifier），支持自定义
• Plan 模式 — --plan 或 /plan 进入只读探索，Agent 先制定方案、批准后再执行
• 持续目标循环 — /goal 自动执行→验证→修复，直到验证通过或触发停止条件
• 模型自主 Git worktree — 当仓库状态和验证风险确有需要时，Agent 可自主使用普通 Git 命令创建并清理临时 worktree，避免冒险改动当前工作区
• 跨会话消息 — 命名后的本机 Session 可以互相发现，并在权限边界内移交工作（macOS / Linux / Windows x64；Windows arm64 artifact 已随包提供，但在完成 arm64 真机验收前属于预览支持；详见文档）
• 文件附件 — @path 或裸绝对路径引用文件，自动识别 text / code / PDF / Office 文档（docx / xlsx / pptx / odt / ods / odp）/ 图片 / 音频
• 本地 PDF 处理 — 按页提取可选文本；扫描页或视觉页交给当前视觉模型，纯文本模型则使用本地 OCR。大型视觉 PDF 通过 readFile 页范围渐进读取，原始 PDF 字节不会上传
• 本地音频转写 — MP3 / WAV / FLAC / OGG Vorbis 附件（最大 25 MiB、20 分钟）始终由隔离进程中的 Whisper（whisper.cpp）在本地转写，只有带时间戳的文字会交给模型。模型下载前会探测 native runtime，并由隔离进程中的流式解码器按实际 PCM 帧执行硬上限；排队等待与转写共用总超时。首次模型下载固定 revision 并通过 SHA-256 校验后才缓存于 ~/.x-code/whisper-models/（默认 tiny，可通过 X_CODE_WHISPER_MODEL 换成其他型号，如 base）
• 图片附件隐私回退 — 本地图片附件只会交给当前视觉模型；纯文本模型使用本地 OCR，不会自动把附件转发给另一个已配置厂商

上下文管理

• 知识库系统 — 分层加载 AGENTS.md（兼容 CLAUDE.md），子包可覆盖根级约定
• 自动记忆 — 每次根 Agent 完整结束后提取长期事实，并在相关请求中按需召回
• 会话恢复 — --continue 恢复最近会话，--resume 打开选择器或按 ID / 分叉名称直达
• 会话分叉 — /fork [名称] 把已完成的上下文复制成独立对话，当前请求运行中也可执行；分叉后仍共享同一个工作区
• 上下文压缩 — 长对话自动压缩；loop-guard 检测循环调用；prompt cache 复用前缀
• 三级权限模型 — 默认安全，按工具与命令风险请求确认；--trust 跳过普通工具确认，也适用于 Peer 触发的工作

扩展生态

• MCP 集成 — 支持 stdio + HTTP（含 OAuth），/mcp 管理，服务器工具自动并入 Agent 工具集
• 插件系统 — skill / sub-agent / 命令 / MCP / hooks 打包分发；与 Claude Code 插件格式兼容
• Skills — SKILL.md 描述可复用工作流模板，/<skill-name> 触发
• 自定义斜杠命令 — markdown 文件放进 ~/.x-code/commands/ 或项目级目录，/<name> 直接使用
• Hooks — 10 个生命周期事件回调，用 shell 命令拦截/改写 Agent 行为
• 浏览器自动化 — 默认可对本地 UI 做一次性截图检查（/browser check-off 可关闭）；/browser on 另行开启交互式浏览器子 Agent

终端体验

• 流式输出 — 边生成边显示
• 主题切换 — /theme 控制 diff 配色和语法高亮风格
• 统一思考模式 — /thinking on|off 将各厂商的 thinking 参数统一为单一开关
• 多行输入 — Alt+Enter 或行尾 \ 插入换行
• 历史回溯 — 空输入框时 ↑/↓ 召回已提交的提示词
• 中途转向（steering） — Agent 运行中也能继续输入：消息先排队显示在 spinner 上方，在下一个工具边界自动注入
• 实时页脚 — 输入框下方常驻当前模型与上下文用量（如 Kimi K3 · 6.6k / 200k · 3%）
• 后台终端 — 长命令自动转为可管理的 Shell Session；/ps 查看，/stop [shell-id] 停止（详见文档）
• 跨平台 — Windows、macOS、Linux

命令行参数

xc [options] [prompt]

--model, -m <id>      指定模型（如 sonnet、deepseek、openai:gpt-5.6-sol）
--trust, -t           信任模式：跳过普通工具确认（含 Peer 触发的工作）
--print, -p           非交互模式：输出结果后退出
--plan                Plan 模式（只读探索，批准后才执行）
--name <名称>         为交互式 Session 命名并启用本机跨会话消息
--continue, -c        恢复最近一次会话
--resume, -r [id|名称] 恢复会话：无参数打开选择器，指定 ID 或分叉名称直达
--max-turns <n>       Agent 循环轮次上限（默认无上限）
--no-plugins          禁用插件系统（排障用）
--no-hooks            跳过所有 hook 执行
--plugin-debug        把 plugin/hook 调试日志镜像到 stderr
--version, -v         显示版本号
--help, -h            显示帮助信息

命令行子命令

xc login [--device-auth]           登录 ChatGPT
xc login status                    查看当前 OpenAI 认证方式
xc logout                          退出 ChatGPT 登录
xc plugin <subcommand>            管理插件（list / install / uninstall / enable / disable / search / update / info / doctor / marketplace）
xc plugin install [--yes] <src>   安装插件；非 TTY 默认拒绝，--yes 跳过确认
xc plugin marketplace <sub>       管理插件市场订阅（list / add / remove / refresh / info）

斜杠命令

| 命令 | 说明 | | -------------------------------- | ----------------------------------------------------------------------------------- | | /help | 查看所有可用命令 | | /login [--device-auth\|status] | 登录 ChatGPT 或查看认证状态 | | /logout | 退出 ChatGPT 登录 | | /model [model-id\|refresh] | 选择已预加载的模型，或显式刷新 ChatGPT 模型目录 | | /thinking [on\|off] | 启用 / 禁用思考模式 | | /theme [name] | 切换 UI 主题 | | /plan [on\|off] | 启用 / 禁用 Plan 模式 | | /goal [目标] | 启动持续目标循环（详见 docs/goal.md） | | /usage | 查看 Token 用量：上下文构成分解、分步明细、归因与缓存命中 | | /usage-history | 列出历史会话用量 | | /clear | 清空当前会话 | | /ps | 列出正在运行的后台终端及最近输出 | | /stop [shell-id] | 停止指定后台终端；不带 ID 时停止全部 | | /clear-peer-context | 确认后删除受 Peer 影响的对话后缀 | | /list-agents | 列出可访问的命名 X-Code Session | | /compact | 手动压缩上下文 | | /resume | 从历史会话中选择恢复 | | /fork [名称] | 分叉已完成的上下文，可选命名（仍共享当前工作区） | | /rewind | 回到某条用户消息之前（还原文件 + 截断历史） | | /init | 分析代码库后创建或更新 AGENTS.md | | /review [PR号] | 评审 GitHub PR（需本地装好 gh） | | /memory [子命令] | 查看、搜索、解释或重载全局长期记忆（详见 docs/knowledge.md） | | /skill <sub> | 管理 Skills | | /mcp <sub> | 管理 MCP 服务器 | | /plugin <sub> | 管理插件与 marketplace | | /browser <sub> | 配置交互式 Browser Use 与本地 UI 自动截图检查 | | /doctor | 一键诊断运行环境 | | /exit | 保存会话并退出 |

详细文档

README 是入门视图，每个功能的完整用法在 docs/ 下（中文 *.md，英文 *.en.md）：

| 文档 | 内容 | | -------------------------------------------------------- | ------------------------------------ | | docs/skills.md | 可复用工作流模板 | | docs/goal.md | 持续目标循环（/goal） | | docs/peer-messaging.md | 跨会话 Agent 消息 | | docs/shell-sessions.md | 后台 Shell Session 与交互式终端 | | docs/sub-agents.md | 内置 / 自定义子 Agent（task 工具） | | docs/mcp.md | MCP 服务器配置 | | docs/knowledge.md | 分层知识库与自动记忆 | | docs/plugins.md | 插件安装 / 管理 | | docs/marketplace.md | 插件市场订阅 / 自建 | | docs/hooks.md | Agent 生命周期 Hook | | docs/plugin-authoring.md | 插件开发指南 |

故障排查

临时设置 DEBUG_STDOUT=1 启动即可捕获调试日志：

# bash / zsh
DEBUG_STDOUT=1 xc

# fish
env DEBUG_STDOUT=1 xc

# PowerShell
$env:DEBUG_STDOUT=1; xc

# CMD
set DEBUG_STDOUT=1 && xc

日志路径：~/.x-code/logs/debug.log（Windows: %USERPROFILE%\.x-code\logs\debug.log），单文件 10 MB，滚动备份 ~20 MB。

从源码运行

需要 Node.js 22+ 和 pnpm 10.x。

git clone https://github.com/woai3c/x-code-cli.git
cd x-code-cli
pnpm install
pnpm dev

修改源码后需 pnpm build 或 pnpm dev。自动监听可在 packages/core 下运行 pnpm dev（tsc -b --watch）。

配套小册

想深入了解实现原理，可参考掘金配套小册：《从零打造一个 AI Agent CLI》，以本仓库源码为参照，逐章拆解 Agent Loop、多厂商适配、终端渲染、权限模型等。

• QQ 交流群：455053594
• 微信：fullstack-xf

反馈与贡献

欢迎通过 Issue 和 Pull Request 反馈：https://github.com/woai3c/x-code-cli

License

MIT