教程►Linux/开发工具

CodeArts 代码智能体在 Ubuntu (x86_64) 安装与避坑教程（CLI 版）

CodeArts 代码智能体在 Ubuntu (x86_64) 安装与避坑教程（CLI 版）

本教程记录在 x86_64 / amd64 的 Ubuntu 上安装华为云「码道 CodeArts 代码智能体」的过程，重点是绕开官网只提供 ARM64 桌面版的坑，改用官方 CLI 安装脚本（自带 x64 构建），并解释运行后那条「请使用现代终端」提示到底是怎么回事。

适用版本：CodeArts CLI 26.9.3（安装脚本自动拉取最新 x64 构建）/ Ubuntu 24.04 LTS (x86_64)

一、环境说明

  • 系统：Ubuntu 24.04 LTS，架构 x86_64 / amd64
  • 目标：华为云 CodeArts 代码智能体（AI 编码助手）
  • 结论先行：官网下载页的 IDE 桌面版只有 ARM64，在 amd64 机器上装不了；但 CLI / TUI 版有 x64 构建，用官方安装脚本即可正常安装使用。

二、背景坑：官网 deb 为什么装不上

从华为云下载页（codearts.huaweicloud.com/download.html）拿到的 Linux 安装包是：

1
codearts-agent-linux-arm64-26.9.102-b8b3886.deb

它是 ARM64 架构的 IDE 图形客户端。在 amd64 机器上：

1
2
3
4
uname -m                       # x86_64
dpkg --print-architecture      # amd64
dpkg-deb -I codearts-agent-linux-arm64-*.deb | grep Architecture
# Architecture: arm64

架构不匹配，强行 dpkg --force-architecture 装进去，二进制也无法在 amd64 上运行。实测华为云 OBS 上也没有对应的 x64 IDE 包（arm64 链接返回 200，x64 链接返回 403）。

所以：amd64 用户不要死磕那个 .deb，直接走下面的 CLI 方案。

三、正确方案：官方 CLI 安装脚本（自动识别 x64）

CodeArts 提供了一套独立的 CLI/TUI 安装脚本，它会自动探测本机架构并下载对应构建。在 amd64 上它会拉到 x64 包。

1
2
sh -c "$(curl -L https://cnnorth4-cloudide-marketplace.obs.cn-north-4.myhuaweicloud.com/codearts/cli_tui/install_script/install.sh)" \
  && export PATH=~/.codeartsdoer/installers:$PATH

安装过程中的关键日志（amd64 机器上）：

1
2
3
4
5
6
7
[INFO] Detected platform: x64
[INFO] Matched Download URL: .../codearts-install-26.9.3-linux-x64.tar.gz
[INFO] Downloading codearts (x64)...
[SUCCESS] Executable 'agentkernel' installed to /home/你/.codeartsdoer/installers/bin/codearts
[SUCCESS] Startup script 'codearts' installed to /home/你/.codeartsdoer/installers/codearts
[INFO] Adding /home/你/.codeartsdoer/installers to PATH in /home/你/.bashrc
[SUCCESS] codearts is now available! Version: 26.9.3

注意它检测到的是 **x64**，下载的是 **linux-x64.tar.gz**，所以能正常在 amd64 上跑。

四、验证安装

1
2
3
4
5
6
7
8
9
10
11
12
export PATH=~/.codeartsdoer/installers:$PATH

which codearts
# /home/你/.codeartsdoer/installers/codearts

codearts --version
# 26.9.3

file ~/.codeartsdoer/installers/bin/codearts
# ELF 64-bit LSB executable, x86-64, ...（确认是真正的 amd64 二进制）

codearts --help        # 列出全部子命令（见第七节）

安装位置：~/.codeartsdoer/installers/（启动脚本 codearts + 可执行文件 bin/codearts）。PATH 已自动写入 ~/.bashrc，新开终端即可直接用 codearts。

五、关于「请使用现代终端」提示（重点坑）

首次启动 TUI 时，你大概率会看到这样一段提示，并且界面会停顿约 1 秒：

1
2
3
▲  [兼容性提示] TUI 界面需要 True Color 颜色支持。
▲  若您的终端不兼容，可能会出现颜色失真、乱码或布局错位。
▲  建议换用现代终端以获得完整体验：GNOME, WezTerm, Alacritty, Ghostty, Kitty

常见误解

  • 「Ubuntu 自带的不是现代终端？」 —— Ubuntu 默认的 GNOME Terminal 支持 true color（24 位真彩），本身就是现代终端。这条提示和「用的是哪个 App」无关。
  • 「设 export COLORTERM=truecolor 能去掉它吗？」 —— 不能。我反编译安装后的二进制确认过：这段提示是 TUI 模式下无条件打印的固定横幅（代码逻辑：非鸿蒙系统、且未带位置参数进 TUI 时，直接 kn.warn(...) 并 setTimeout(1000)），并不做真实的终端能力探测。无论你用多现代的终端、怎么设 COLORTERM，纯 codearts 启动都会看到它。
  • 它只影响配色提示，不影响任何功能；TUI 照常工作。

怎么避开这条提示

提示只在「纯 codearts 进入 TUI」时出现。以下调用方式走的是「非 TUI 模式」分支，不会打印它：

1
2
3
4
codearts models              # 列出可用模型（不带参数也行）
codearts run "帮我看下这段代码"   # 带消息直接运行
codearts serve               # 启动无界面(headless)服务，再用 attach 连
codearts <项目路径>           # 带位置参数也会跳过该提示

如果你想用完整交互式 TUI，那就接受它每次出现 1 秒——这是设计如此，无害。

小建议：仍可在 ~/.bashrc 保留 export COLORTERM=truecolor，它能让 TUI 实际用 24-bit 真彩渲染，颜色更准（只是不会消除上面那条横幅）。

六、首次使用

  1. 在终端运行 codearts（或带子命令，见第五节避开提示）。
  2. 按提示完成登录授权（浏览器 OAuth 或设备码流程）。
  3. 登录后即可在 TUI 里选模型、开项目、对话编码。

七、常用命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
codearts                       # 启动交互式 TUI（会显示兼容性横幅）
codearts [project]             # 在指定项目路径启动 TUI
codearts run [message..]       # 带一条消息直接运行
codearts models [provider]     # 列出可用模型
codearts serve                 # 启动无界面服务（可 attach 连接）
codearts acp                  # 启动 ACP (Agent Client Protocol) 服务
codearts mcp                  # 管理 MCP 服务器
codearts session              # 管理会话
codearts agent                # 管理 agents
codearts attach <url>         # 连接到运行中的 codearts 服务
codearts stats                # 查看 token 用量与花费
codearts upgrade              # 升级到最新版
codearts uninstall            # 卸载并清理相关文件
codearts debug                # 调试与排错工具

八、排错速查表

现象 可能原因 处理方式
dpkg -i 装 .deb 后程序无法启动 拿到的是 ARM64 IDE 包，机器是 amd64 改用第三节的 CLI 安装脚本（x64）
下载 x64 deb 返回 403 华为云未发布 x64 IDE 包 同上，走 CLI 方案
启动 TUI 显示「请使用现代终端」 TUI 固定横幅，非能力检测失败 无视即可；或改用 codearts models 等子命令避开
运行 codearts 提示 command not found PATH 未生效 source ~/.bashrc 或重开终端
TUI 颜色发暗/错位 终端未声明 true color ~/.bashrc 加 export COLORTERM=truecolor 后用现代终端
想完全无界面运行 默认进 TUI codearts serve 起 headless 服务再 attach

九、重点回顾

  1. 华为云 CodeArts IDE 桌面版目前只有 ARM64，amd64 机器装不了，别在 .deb 上耗时间。
  2. CLI/TUI 版有 x64 构建，用官方安装脚本 sh -c "$(curl -L .../install.sh)" 会自动识别 x64 并安装，装完即 codearts --version 可用。
  3. 启动 TUI 的「请使用现代终端」是固定横幅、无法关闭、无害；想避开就用子命令（codearts models / codearts run "..." / codearts serve）。
  4. Ubuntu 自带 GNOME Terminal 就是现代终端，支持 true color，不必换终端。